Choosing and Implementing OpenAPI Discriminators for Polymorphic Schemas

When designing an API that needs to accept or return different object types that share a common base, you must decide how to express polymorphism in your OpenAPI document. The decision hinges on whether a single property can reliably distinguish the subtypes. If such a property exists and is guaranteed to be present, using an OpenAPI discriminator is usually the best choice because it reduces duplication, improves tooling support, and yields cleaner generated client models. If the distinguishing information is spread across multiple properties or absent, you must fall back to oneOf or anyOf without a discriminator, accepting higher validation complexity and less‑friendly code generation.

Decision and Constraints

Choose a discriminator when:

• You are authoring an OpenAPI 3.0 (or later) document – the feature is not available in OpenAPI 2.0 (Swagger).
• All candidate schemas share a top‑level property with the same name and type (e.g., a string petType).
• That property’s value is guaranteed to be present in every instance and uniquely maps to one subtype.
• You want generated client/server code to produce concrete classes (e.g., Dog, Cat) rather than a generic map.

If any of these conditions cannot be met, you must consider alternatives.

Supported Options Comparison

Option	How it works	When to use	Main drawbacks
discriminator with mapping property	Defines a base schema, specifies the property name that acts as the discriminator, and maps each possible value to a referenced schema.	Single, known property can distinguish subtypes; OAS 3.0+.	Requires the discriminator property to exist in all schemas; some generators ignore it if the name mismatches.
oneOf / anyOf without discriminator	Lists candidate schemas; validation succeeds if the payload matches one (or any) of them.	Subtypes differ on multiple properties or no single discriminating field exists.	Harder for tools to infer concrete types; validation may be ambiguous; generated models often stay as generic objects.
Explicit separate schemas via inheritance (not directly supported)	Model inheritance is expressed outside OpenAPI (e.g., using allOf to reuse properties) but still needs a discriminator or oneOf for selection.	When you want to reuse common fields while keeping subtype definitions separate.	Does not remove the need for a discriminator or oneOf; adds schema duplication if not combined with allOf.

Trade‑offs

The discriminator approach yields a single base schema with a clear mapping table, which most OpenAPI generators translate into a class hierarchy. This improves readability and reduces the chance of mismatched fields. The trade‑off is a stricter contract: the discriminator property must be present and its value must exactly match one of the keys in the mapping object. If a payload omits the property or contains an unknown value, validation fails, which can be desirable for strict APIs but may require additional error handling.

Using oneOf or anyOf without a discriminator offers more flexibility—you can differentiate based on any combination of fields—but the resulting schema is harder for generators to interpret. Many generators produce a generic map or an interface with runtime checks, increasing boilerplate on the consumer side. Validation can also be slower because the parser must test each candidate schema until a match is found.

Concrete Implementation Example

Consider a simple “Pet” API where clients can create either a dog or a cat. Both share id and name, but dogs have a breed field and cats have a flavor field. The distinguishing property is petType with values dog or cat.

openapi: 3.0.3
info:
  title: Pet 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
      discriminator:
        propertyName: petType
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'
      required:
        - id
        - name
        - petType
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        petType:
          type: string
          enum: [dog, cat]
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            breed:
              type: string
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            flavor:
              type: string

This snippet shows the base Pet schema with a discriminator on petType. The mapping ties each enum value to a specific subtype that extends the base via allOf.

Validation and Verification Steps

To confirm that the discriminator works as intended, perform the following checks:

1. Schema validation – Run the YAML through a validator such as swagger-parser or the openapi-generator CLI’s validate command. Ensure no errors are reported about missing discriminator mapping.
2. Generated code inspection – Generate client models (e.g., Java with openapi-generator generate -i pet.yaml -g java -o out). Verify that the output contains a base Pet class and subclasses Dog and Cat with the expected extra fields.
3. Manual UI test – Load the document in Swagger UI. In the “Try it out” panel for the POST /pets endpoint, the petType dropdown should appear, and selecting dog should reveal the breed field while cat shows flavor.
4. Deserialization unit test – Write a test that sends a JSON payload like { "id": 1, "name": "Buddy", "petType": "dog", "breed": "Golden Retriever" } to the generated client’s deserialization method. Assert that the resulting object is an instance of Dog and that breed is correctly set. Repeat for a cat payload.

These steps give you confidence that the discriminator is correctly wired and that consumers will receive the proper concrete types.

Limitations and Practical Checks

Even when the discriminator is a good fit, be aware of these constraints:

• The discriminator property must exist in every schema referenced in the mapping. If a subtype omits it, validation will fail.
• Some older or community‑maintained generators may ignore the discriminator if the property name does not exactly match a defined property in all referenced schemas, leading to runtime errors where the base class is used instead of the subtype.
• If you need to support OpenAPI 2.0 clients, you cannot use a discriminator; you must duplicate the common fields or rely on oneOf.

To check that your chosen generator respects the discriminator, inspect the generated model files for a subclass hierarchy or for a discriminator‑aware deserialization routine (often annotated with @JsonSubTypes in Jackson‑based generators). If the generator produces only a flat class with a petType field and no subclasses, you may need to switch to a different generator version or adjust the mapping.