redocly "schema validation failed" discriminator error

TL;DR: Make every discriminator.mapping value match a real subschema name in the oneOf or anyOf list. Redocly's "schema validation failed" on a discriminator means a mapping entry points at a component that does not exist (usually a rename or a typo), or the propertyName field is missing from a subschema. Fix the mapping, confirm each subschema declares the discriminator property, and re-run the linter.

schema validation failed

1. Lint to get the exact location:

   npx @redocly/cli lint openapi.yaml 2>&1 | tee redocly.log

Expected: a finding that names the discriminator and the offending mapping value.

1. Open the discriminator and compare each mapping value with the oneOf entries and the components/schemas names. They must match exactly, including case:

   discriminator:
     propertyName: petType
     mapping:
       dog: '#/components/schemas/Dog'
       cat: '#/components/schemas/Cat'

1. Confirm every subschema (Dog, Cat) declares the petType property, ideally as required.
2. Re-run the lint:

   npx @redocly/cli lint openapi.yaml

Expected: exit code 0 with no errors reported.

1. If the finding persists, check for a second discriminator on a nested schema - the log names only the first failure.

Use this when

• redocly lint fails with "schema validation failed" on a discriminator
• A mapping entry was renamed or added and validation broke
• Polymorphic schemas validate in an editor but fail Redocly's rules

Not for this skill when

• The failure is on a plain schema, not a discriminator - fix the schema itself
• The discriminator uses implicit mapping (no mapping key) - then the subschema names themselves must match the discriminator values
• Another linter passes and only Redocly fails - check which Redocly rule is stricter before changing the spec

Variant phrasings

• "redocly discriminator validation failed"
• "redocly schema validation failed discriminator"
• "openapi discriminator mapping invalid"

Why it happens

A discriminator is a contract: propertyName says which field picks the subtype, and mapping says which value means which schema. When a component is renamed or a mapping value is typed by hand, the two sides disagree, and Redocly fails validation because clients cannot reliably pick the right schema.

Edge cases

• Implicit mapping (no mapping key) requires the subschema component names to equal the discriminator values exactly.
• Mappings may point at external files; those refs must resolve just like any $ref.
• In OpenAPI 3.1 the discriminator semantics are unchanged, but the surrounding schema validation is stricter - fix 3.0 issues before upgrading.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYbHeFu-VRp50SqPptBPFQ