Second pattern of our series: collections.
components:
schemas:
Model:
type: object
properties:
stringArray:
type: array
items:
type: string
stringArrayNoType:
items:
type: string
arrayOfUnknown:
type: array
items: {}
In the above snippet, stringArray describes an array of string values. While this works well for the purpose of generating code, it is not very specific. It is assumed that an array will be enough for the application developer, and while that might be the case, signaling generator whether to use a basic array or a more advanced data structure would help for scenarios where the client application cannot have duplicate entries, or needs to quickly find one of the entries, or needs to do some sorting, etc.
StringArrayNoType, while valid for data validation purposes, makes for a more complex decision tree in the generator as the type is not set and we have to infer the use of a collection through the use of the items property.
ArrayOfUnknown does not contain enough information for code generation, array of what exactly?
Suggestions
We’ll need to add the placeholder for the missing information, we could add a collectionKind property for the items property in the OAS vocabulary. (array, hashset, list, default array). Which should not be a breaking change.
We can then make sure that API owners improve their descriptions through linting tools rules:
- Error when using the items property and the type is not set to array.
- Error when using the items property and the items type is not set.
- Warning when the collection kind is not set.
Here is an example of what the solution would look like.
components:
schemas:
Model:
type: object
properties:
stringArray:
type: array
items:
type: string
x-ms-collection-kind: array # or hashset or list