Formats for arrays #3572
Description
Across various use cases for arrays, we find that in some situations the order is sensitive (for example, when the array functions as a vector, tuple, series, etc.), while in other situations the array functions as a set and is not order sensitive. The three formats proposed here are intended to cover all variants of array use cases.
Proposed formats
The base type for these formats is array.
set
A collection of unique, unordered items. The position of an item in the array is not significant.
Order need not be preserved in serialization, deserialization, compression, and transmission.
This format implies uniqueItems: true and is incompatible with uniqueItems: false.
multiset
A collection of unordered items allowing for duplicates. The position of an item in the array is not significant.
Order need not be preserved in serialization, deserialization, compression, and transmission.
This format implies uniqueItems: false and is incompatible with uniqueItems: true.
sequence
An ordered collection of items. The order is defined by each item's index in the array, and not by comparing the items' values.
Order must be preserved in serialization, deserialization, compression, and transmission.
This format is compatible with any value for uniqueItems.
Alternative names for this format were considered, but were deemed less suitable:
list: too vague and overloadedseries: in mathematics, a series is order insensitivetuple,vector: these imply a fixed length
Notes
These formats do not alter the definition of item uniqueness, which comes from the JSON Schema definition of instance equality. Note that uniqueItems does not consider semantic equivalence. For example, date-time equivalency is not considered here:
ExampleTimes:
type: array
uniqueItems: true
items:
type: string
format: date-time
example:
- '1996-12-19T16:39:57-08:00'
- '1996-12-20T00:39:57Z'The set and multiset formats are incompatible with conflicting uniqueItems values, as described above. Existing formats have similar incompatibilities. For example, string-based formats like date and email are incompatible with conflicting pattern values.
The multiset format is included for completeness. The data type it represents does not appear to be commonly used.
The sequence and set formats represent data types that are very common in real-world API use. For example, the Terraform types include:
list(ortuple): a sequence of values, like["us-west-1a", "us-west-1c"]. Identify
elements in a list with consecutive whole numbers, starting with zero.set: a collection of unique values that do not have any secondary identifiers or ordering.
Having the proposed formats enables Terraform providers to correctly make use of the above Terraform types.
Examples
set
Album:
properties:
name:
type: string
genres:
type: array
format: set
items:
type: string
example: [jazz, rock] # equivalent to [rock, jazz]multiset
Survey:
properties:
question:
type: string
example: How often do you exercise?
collected_responses:
type: array
format: multiset
items:
type: string
example:
- "Daily"
- "Once or twice a week"
- "Daily"
- "Every month"
example2: # equivalent to the above example
- "Daily"
- "Daily"
- "Every month"
- "Once or twice a week"sequence
NetworkConfiguration:
properties:
dns_servers:
type: array
uniqueItems: true
format: sequence # Order is significant. The first server will be queried first.
# The next server will be used only when the first server fails.
items:
type: string
format: ipv4
example:
- 192.168.0.3
- 192.168.0.2