2026-09-28 · 6 min read · Rahul Chitturi
- openapi
- schema
- api
An OpenAPI discriminator helps tooling choose among polymorphic schemas by inspecting a named property. It does not replace the oneOf or anyOf constraints that define whether an instance is valid.
Generation and validation diverge when the discriminator property is optional, mapping values do not match serialized payloads, branches overlap, or a tool interprets implicit schema-name mappings differently.
Normalize the union before debugging tools
Record the OpenAPI version, complete schema, discriminator propertyName, explicit mapping, referenced component names, payload, validator output, and generated model. Resolve references while preserving their canonical targets.
- Require the discriminator property in relevant branches.
- Use a unique constrained tag value per branch.
- Prefer explicit mappings over naming conventions.
- Treat tag values as exact strings unless the contract says otherwise.
Prove the schema without discriminator hints
Each valid payload should satisfy the intended branch and, with oneOf, no other branch. Add const or enum constraints to the tag in each branch so server validation remains correct even when a validator ignores the discriminator extension.
Then inspect documentation, SDK, serialization, and deserialization behavior separately. A generated client selecting a class does not prove the server accepts the payload.
Maintain variant fixtures
Use Flashman's YAML/JSON converter for the specification, JSON formatter for payloads, diff for generated artifacts, and case converter for tag naming drift.
Test every mapped tag, missing and null tags, unknown values, case changes, overlapping branches, inline and referenced schemas, renamed components, nested unions, read/write variants, generator upgrades, and backward-compatible additions.