An array is an ordered collection of values, commonly represented in JSON with brackets and comma-separated elements. JSON arrays can contain strings, numbers, Booleans, objects, arrays, or null values. section 5.1.2
Arrays are useful for representing collections such as a catalog of products or a product’s keywords. A collection resource may be modeled as an array, while an individual resource is modeled as an object. section 5.2.1 section 5.2.3
Design arrays with consumer usability and future change in mind:
- Describe an array property in JSON Schema with type: array and an items schema defining each element. section 7.4.5
- Use arrays to group similar data, making related business concepts easier to browse and understand. section 8.6.2
- Keep small, essential lists embedded; separate large lists that need filtering or pagination into dedicated resource models and operations. section 8.7.2
- Prefer arrays of objects when elements may later need additional data; arrays of atomic values are suitable when each value is self-sufficient. section 15.6.3
- Use an object at request and response body level when future metadata or extension may be required, because a bare array cannot be extended without changing the contract. section 15.6.3 section 5.2.1
Product keywords
A Product schema can define keywords as an array of strings: keywords: { type: array, items: { type: string } }. The same items position can contain an object schema when each element needs structured fields. section 7.4.5
Listing 7.7 An array of strings
...
Product:
type: object
properties:
...
keywords:
type: array #1
items: #2
type: string #3
Inspect the compact OpenAPI schema for an array of strings and its items definition. section 7.4.5
