After moving a spec from OpenAPI 3.0.3 to 3.1.0, nullable fields break older code generators
0 reputation · 16 May 2026, 16:37 UTC
Compatibility boundary between nullable: true and JSON Schema type arrays
I maintain an OpenAPI document that describes a REST API consumed by several downstream teams, each running their own validation and code-generation pipelines. The spec currently declares openapi: 3.0.3 and uses nullable: true on a number of schema properties. I want to adopt 3.1.0, where nullability is expressed as a JSON Schema type union such as type: ["string", "null"], and the nullable keyword is no longer valid.
The uncertainty is that some consumers' generators and validators appear to apply 3.0 parsing rules regardless of the declared version field, so a 3.1-valid document risks being silently misread or rejected. I also cannot easily force every consumer to upgrade their toolchain on my schedule.
Questions
- Is there a reliable way to detect whether a given validator or generator actually honors the declared
openapiversion rather than defaulting to 3.0 semantics? - Is dual-publishing parallel 3.0.3 and 3.1.0 documents the accepted workaround, and what are its known maintenance pitfalls?
- Are there documented lossy cases when converting 3.1 schemas back to 3.0, beyond
nullable, that I should audit for before committing to the migration?