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": [
            {
                "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"]

 

oas
OpenApi
swagger
Swagger Editor
  • HKosova's avatar
    HKosova
    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"
        ..

     

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)
    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"
        ..