Skip to content

OpenAPI emitter - add support for OpenAPI 3.2.0 defaultMapping for discriminated unions #9261

@baywet

Description

@baywet

Clear and concise description of the problem

The following TypeSpec definition

@discriminated(#{discriminatorPropertyName: "taxonomic_family", envelope: "none"})
union Animal {
  Dog,
  felidae: Cat,
  muscidae: Ferret
}

model Dog {
  taxonomic_family: "canidae"
}

model Cat {
  taxonomic_family: "felidae"
}

model Ferret {
  taxonomic_family: "muscidae"
}

Results in the following OpenAPI 3.2.0 description

openapi: 3.2.0
info:
  title: (title)
  version: 0.0.0
tags: []
paths: {}
components:
  schemas:
    Animal:
      type: object
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Ferret'
      discriminator:
        propertyName: taxonomic_family
        mapping:
          felidae: '#/components/schemas/Cat'
          muscidae: '#/components/schemas/Ferret'
    Cat:
      type: object
      required:
        - taxonomic_family
      properties:
        taxonomic_family:
          type: string
          enum:
            - felidae
    Dog:
      type: object
      required:
        - taxonomic_family
      properties:
        taxonomic_family:
          type: string
          enum:
            - canidae
    Ferret:
      type: object
      required:
        - taxonomic_family
      properties:
        taxonomic_family:
          type: string
          enum:
            - muscidae

For any OpenAPI version, the dog component schema should be present in the oneOf section. For any OpenAPI version prior to 3.2.0, a canidae entry should be present in the mapping.
This is because:

  • Dog model is discoverable from the union (it's the default value)
  • It has one value that's known in advance and can be mapped (through discovering the discriminator property)

In addition to those changes, when emitting OpenAPI 3.2.0, since Dog is the default member of the union, and since their can be only one default member in union definitions, there should be a "defaultMapping" property on the discriminator object. Here is an example of what it should look like

      discriminator:
        propertyName: taxonomic_family
        defaultMapping: '#/components/schemas/Dog'
        mapping:
          felidae: '#/components/schemas/Cat'
          muscidae: '#/components/schemas/Ferret'

Checklist

  • Follow our Code of Conduct
  • Read the docs.
  • Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions