Why Does My oneOf Schema Cause Deserialization Errors?

TL;DR: Without a discriminator, deserializers must try each oneOf option sequentially. This is slow, error-prone, and many tools fail entirely.

The Problem

You have a schema with multiple object types:

oneOf:
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Cat'

When receiving JSON, the deserializer doesn't know which schema to use. It must:

Try deserializing as Dog
If that fails, try Cat
If all fail, throw an error

The Fix

Add a discriminator field that explicitly identifies which schema to use:

oneOf:
  - $ref: '#/components/schemas/Dog'
  - $ref: '#/components/schemas/Cat'
discriminator:
  propertyName: petType
  mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

Now the deserializer looks at the petType field in the JSON and knows immediately which schema to use.

Catch All Silent Failures

Use our OpenAPI Silent Failure Validator to find this and other breaking patterns.

Analyze My Spec