cancel
Showing results for 
Search instead for 
Did you mean: 

Object property name as UUID

SOLVED
Highlighted
Frequent Visitor

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": [
            {
                "id": "0000",
                "type": "Home",
                "ownership": "",
                "monthly": "0",
                "address_1": "23299 Address Parts",
                "address_2": "",
                "city": "Some City",
                "state": "ZZ",
                "zip": "00000",
                "active": "1",
                "primary": "1"
            }
        ]
    }
}

 Here is my attempt (schema portion):

 

components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: UUID
      example: 00000000-0000-0000-0000-000000000000
      pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    CustomerAddresses:
      type: object
      properties:
        '#/components/schemas/uuid':
          type: array
          items:
            $ref: '#/components/schemas/CustomerAddress'
    CustomerAddress:
      type: object
      properties:
        id:
          type: string
          example: "3014"
        type:
          type: string
          enum: ['Home', 'Work'] 
        ownership:
          type: string
          example: ""
        monthly:
          type: string
          example: "0"
        address_1:
          type: string
          example: "23444 Address Parts"
        address_2:
          type: string
          example: "Unit 42"
        city:
          type: string
          example: "Some City"
        state:
          type: string
          maxLength: 2
          minLength: 2
          example: "ZZ"
        zip:
          type: string
          format: int32
          example: "00000"
        active:
          type: string
          enum: ["0", "1"]
        primary:
          type: string
          enum: ["0", "1"]

 

1 ACCEPTED SOLUTION

Accepted Solutions
Highlighted
Moderator

Re: Object property name as UUID

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"
        ..

 


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

1 REPLY 1
Highlighted
Moderator

Re: Object property name as UUID

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"
        ..

 


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

View solution in original post

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors