Formats for arrays

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 overloaded
• series: in mathematics, a series is order insensitive
• tuple, 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 (or tuple): 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

No implementation files or tests are named. Start by reviewing the proposed set, multiset, and sequence semantics and the existing OpenAPI format rules, then read the issue discussion for objections or a decision. Done means the proposal is resolved and the specification documents the accepted array formats and their interactions with uniqueItems.