Forum Discussion

Etrahkad's avatar
Etrahkad
Frequent Visitor
5 years ago

Object property name as UUID

In the given API response how would you write the schema yaml to support UUIDs as a property name { "results": { "11b17cd8-0000-0000-0000-2092b242027f": [ { "...
  • HKosova's avatar
    5 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"
            ..