Using OpenAPI Discriminator for Polymorphic Request and Response Bodies

When to use an OpenAPI discriminator

If a single endpoint must accept or return several distinct object shapes that share a common identifying field, model the polymorphism with an OpenAPI discriminator keyword. This keeps the API surface small, lets generators produce type hierarchies, and documents the dispatch logic directly in the schema.

Worked example: Pet API

The following YAML snippet shows a base Pet schema with a discriminator on the petType property. Two subtypes, Cat and Dog, extend Pet and add their own required fields.

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    post:
      summary: Create a pet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Created pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - petType
        - name
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'
      properties:
        petType:
          type: string
          enum: [cat, dog]
        name:
          type: string
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          required:
            - likesFish
          properties:
            likesFish:
              type: boolean
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          required:
            - breed
          properties:
            breed:
              type: string

How it works:

1. The discriminator keyword tells consumers that the value of petType determines which referenced schema should be used for validation.
2. When a client sends a JSON body with {"petType":"cat","name":"Whiskers","likesFish":true}, the validator matches the petType value to the mapping and validates against the Cat schema.
3. Server‑side code generated from this document (e.g., via openapi-generator) will typically produce a base Pet class with subclasses Cat and Dog, allowing the developer to switch on petType or use polymorphism directly.

Limits and considerations

• The discriminator does not> add runtime validation; it only influences schema resolution and documentation. You still need server‑side code to check the discriminator value if you rely on it for routing.
• Tooling support varies: some validators (e.g., Spectral) fully enforce the mapping, while others may ignore it or produce warnings for missing properties.
• Deeply nested polymorphism can lead to ambiguous oneOf matches that are hard to read and may cause generators to produce overlapping types.
• OpenAPI 3.0 uses a simple mapping object; OpenAPI 3.1 aligns the discriminator with JSON Schema’s discriminator keyword, so behavior can differ between versions.

Common mistakes

• Forgetting to make the discriminator property required in the base schema – without it, clients cannot reliably dispatch.
• Using mapping keys that do not match the actual enum values sent on the wire (e.g., mapping feline while the API sends cat).
• Omitting oneOf or anyOf alongside the discriminator, which leaves the schema undocumented and can confuse generators.
• Assuming the discriminator enforces that subtypes cannot have additional properties beyond those defined; it does not, so extra fields may slip through validation.

How to verify the discriminator works

1. Validate the document – run an OpenAPI linter that understands discriminators. Example using Spectral (requires Node.js and read access to the file):

   npx @stoplight/spectral-cli lint openapi.yaml
   

   Expected output: no errors related to unresolved $ref or missing discriminator property.
2. Generate client/server stubs – use your preferred generator and inspect the output for subtype classes. Example with OpenAPI Generator (Java):

   openapi-generator generate -i openapi.yaml -g java -o ./generated-java
   

   Check that Pet.java exists and that Cat.java and Dog.java extend it.
3. Test payloads – send sample JSON bodies for each subtype and confirm the server deserializes to the correct type (or that a client parses them into the expected class). This step requires permission to call the API or run unit tests against the generated code.

   curl -X POST http://localhost:8080/pets \
     -H "Content-Type: application/json" \
     -d '{"petType":"dog","name":"Rex","breed":"Labrador"}'
   

   Look for a response that includes the breed field, indicating the Dog schema was applied.
4. If any step fails, review the discriminator property name, mapping values, and required fields in the base schema.