Lessons learned from API client generation - 03 Collections

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