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:
propertyNameis 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 namestypeunderrequired.mappingconnects 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".constin 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
| Mistake | What happens | Fix |
|---|---|---|
The discriminating property is not in required | A payload without it is ambiguous; the specification leaves the behaviour undefined | Add it to required in every schema |
No const or enum on the property | Two schemas can match the same payload, and oneOf then fails | Fix the value in each schema |
| Mapping values that are not in the payloads | Generated clients cannot pick a class | Keep the mapping keys equal to the real values |
discriminator on a schema that takes no part in oneOf, anyOf or allOf | The specification allows it only with those keywords; anything else is undefined | Put 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.