Object property name as UUID
- 4 years ago
The next version of the spec, OpenAPI 3.1 (which is currently at the "release candidate" stage) will use the updated JSON Schema that has the patternProperties and propertyNames keywords exactly for this purpose. "patternProperties" lets you define a regular expression for allowed property names. Whereas "propertyNames" lets you provide a schema for property names rather than values, i.e. specify that the names have "format: uuid" or have minLength/maxLength of 36.
In OpenAPI 3.1, the "results" property from your example can be defined as follows. Note that regexes aren't implicitly anchored, so make sure to add ^ and $ for an exact match.
# openapi: 3.1.0 results: type: object patternProperties: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$': type: array items: $ref: '#/components/schemas/CustomerAddress' additionalProperties: false
or
results: type: object propertyNames: format: uuid example: 00000000-0000-0000-0000-000000000000 # pattern can be provided for tools that don't know "format: uuid" # pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' additionalProperties: type: array items: $ref: '#/components/schemas/CustomerAddress'
OpenAPI 3.0 (the current version) doesn't have a way to define the format of dynamic property names, so "results" can be defined as just a string-to-array dictionary. However, you can mention these details in the schema description and provide a schema example that shows how those dynamic property names look like.
results: type: object description: Property names are UUIDs, and property values are ... additionalProperties: type: array items: $ref: '#/components/schemas/CustomerAddress' example: 11b17cd8-0000-0000-0000-2092b242027f: - id: "0000" type: "Home" ..