My Spec Validates But Tools Still Reject It — Why?
TL;DR: Many patterns are technically valid OpenAPI but unsupported by Swagger UI, code generators, or runtime validators. These are called silent failures.
What Are Silent Failures?
Silent failures are patterns that:
- ✅ Pass OpenAPI schema validation
- ❌ Break Swagger UI rendering
- ❌ Cause code generator errors
- ❌ Lead to runtime deserialization failures
Common Silent Failures
nullable with oneOf
Setting nullable: true on a schema with oneOf doesn't work. You must explicitly add { "type": "null" }.
oneOf without discriminator
Without a discriminator, deserializers must try each option sequentially, causing slowness and errors.
Read more →Examples with wrong types
Swagger UI silently ignores examples that don't match the schema type or are missing required fields.
Read more →Default value not in enum
If default isn't one of the enum values, runtime validators will reject it.
Required + nullable
Marking a field as both required and nullable confuses many implementations.
Why Validators Don't Catch These
OpenAPI validators only check that your spec follows the schema structure. They don't check:
- Whether examples are valid against schemas
- Whether patterns are supported by tools
- Whether discriminators are present for polymorphism
- Whether type/format combinations make sense
Find All Silent Failures in Your Spec
Our OpenAPI Silent Failure Validator checks for 10+ patterns that break tooling but pass validation.