Skip to content

The OpenAPI discriminator: what it does and what it does not

Last checked and updated

discriminator names one property of a payload whose value says which of several schemas the payload follows. It is used together with oneOf, anyOf or allOf: on the schema that lists the alternatives, or on a parent that children include through allOf. It is a hint for tools, such as code generators, documentation and some validators; it validates nothing by itself. The schemas it points to must still tell the cases apart.

An example that validates

A payment is made by card or by bank transfer. The property type says which:

components:
  schemas:
    PaymentMethod:
      oneOf:
        - $ref: "#/components/schemas/Card"
        - $ref: "#/components/schemas/BankTransfer"
      discriminator:
        propertyName: type
        mapping:
          card: "#/components/schemas/Card"
          bank_transfer: "#/components/schemas/BankTransfer"
    Card:
      type: object
      required: [type, number]
      properties:
        type:
          const: card
        number:
          type: string
    BankTransfer:
      type: object
      required: [type, iban]
      properties:
        type:
          const: bank_transfer
        iban:
          type: string

Three things make this work:

  1. propertyName is the property to look at. The specification says it should be required in every schema of the list (its section on inheritance says must), because what a tool does when the property is absent is undefined: each schema here names type under required.
  2. mapping connects a value in the payload (card) to a schema. Without a mapping, the value has to be the schema's name: the payload would have to say "type": "Card".
  3. const in each schema is what actually separates the cases. Remove it and a card payload also fits any other schema that does not forbid its properties.

const needs OpenAPI 3.1, whose schemas are full JSON Schema 2020-12. OpenAPI 3.0 supports only the keywords its Schema Object lists, and const is not one of them: write a one-value enum there, enum: [card].

What the tools do with it

The file passes a linter (apigit lint, default rule set) with no finding on these schemas. A mock server generated from it accepts a correct payload and answers with one:

$ curl -X POST http://127.0.0.1:4611/payments \
    -H 'content-type: application/json' -d '{"type":"card","number":"4242"}'
HTTP/1.1 201 Created

{"type":"card","number":"string"}

A payload with an unknown type is refused. The validator reports why each schema of the oneOf did not match, not "unknown discriminator value":

$ curl -X POST http://127.0.0.1:4611/payments \
    -H 'content-type: application/json' -d '{"type":"cash"}'
HTTP/1.1 422 Unprocessable Entity

{"errors":[
  {"in":"body","pointer":"","message":"must have required property 'number'"},
  {"in":"body","pointer":"/type","message":"must be equal to constant"},
  {"in":"body","pointer":"","message":"must have required property 'iban'"},
  {"in":"body","pointer":"","message":"must match exactly one schema in oneOf"}],
 "type":"https://apigit.com/mock/problems/invalid-request",
 "title":"The request does not match the API description","status":422, ...}

That is the practical meaning of "a hint": this validator decided from the schemas alone. A tool may instead use the discriminator to pick one schema and report only that schema's errors. Since you cannot know which kind will read your file, write the schemas so that they are correct without the discriminator.

Mistakes that reach production

MistakeWhat happensFix
The discriminating property is not in requiredA payload without it is ambiguous; the specification leaves the behaviour undefinedAdd it to required in every schema
No const or enum on the propertyTwo schemas can match the same payload, and oneOf then failsFix the value in each schema
Mapping values that are not in the payloadsGenerated clients cannot pick a classKeep the mapping keys equal to the real values
discriminator on a schema that takes no part in oneOf, anyOf or allOfThe specification allows it only with those keywords; anything else is undefinedPut it on the schema that lists the alternatives, or on the parent that children include with allOf

Where to put it with allOf

With inheritance, the discriminator goes on the parent, and each child uses allOf to include the parent:

Pet:
  type: object
  required: [petType]
  properties:
    petType:
      type: string
  discriminator:
    propertyName: petType
Cat:
  allOf:
    - $ref: "#/components/schemas/Pet"
    - type: object
      properties:
        huntingSkill:
          type: string

A payload with "petType": "Cat" is then read as a Cat. This form says which schemas exist only through their names, so a reader of the file cannot see the list of children in one place. Prefer oneOf with a mapping when the set of cases is closed.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish