After moving a spec from OpenAPI 3.0.3 to 3.1.0, nullable fields break older code generators

Short answer

There is no negotiation mechanism in OpenAPI: the openapi field is declarative, and many older tools hard-code 3.0 parsing regardless of what it says. The only reliable way to know whether a consumer's toolchain honors the version is to probe it empirically with a 3.1-only construct. Given that you cannot force upgrades, dual-publishing — authoring one version and mechanically generating the other — is the accepted workaround, but only if one document is a build artifact, not a second source of truth.

Detecting version-honoring tools

Don't trust that a tool "accepts" a 3.1 file; acceptance can mean it parsed the YAML and silently applied 3.0 semantics. Instead, send each consumer a minimal probe spec:

openapi: 3.1.0
info: { title: probe, version: 0.0.1 }
paths: {}
components:
  schemas:
    Probe:
      type: object
      properties:
        maybeName:
          type: ["string", "null"]
        kind:
          const: probe

Then check three things: the validator accepts the document, the generator produces a nullable type for maybeName (not a plain required string), and const is handled rather than dropped. A tool that validates but generates a non-nullable field is the dangerous case — it parsed successfully with wrong semantics. Cross-check probe results against each tool's release notes or issue tracker for explicit OpenAPI 3.1 / JSON Schema 2020-12 support claims.

Dual-publishing without drift

Parallel 3.0.3 and 3.1.0 documents are the standard answer to mixed consumer toolchains. The dominant failure mode is drift between hand-maintained copies, so:

• Pick one authored source (keeping 3.0.3 as the published contract is the conservative choice while consumers lag) and generate the other variant in CI via an automated transformation.
• Validate each artifact with a version-appropriate validator — a 3.1 document containing nullable: true is invalid, and a 3.0 tool fed type: ["string","null"] will typically reject or misread it, so CI should catch both directions.
• Diff generated client code from both specs against a fixed set of representative valid and invalid payloads. This surfaces semantic drift (validation strictness changes) before downstream teams do.

Lossy 3.1 → 3.0 downgrade cases to audit

nullable is the visible break, but the schema dialect change to JSON Schema 2020-12 creates subtler ones:

• exclusiveMinimum / exclusiveMaximum: numbers in 3.1, booleans paired with minimum/maximum in 3.0. Converters usually handle this, but verify boundary payloads.
• const: no 3.0 equivalent; must be emulated with a single-value enum.
• prefixItems / tuple validation: no 3.0 equivalent at all; converters may silently drop it.
• Type arrays generally: any multi-type union beyond null needs oneOf restructuring.
• example vs examples and items semantics differ subtly, so a converter can succeed syntactically while changing validation strictness.

The key caution: automated converters may drop unsupported constructs rather than fail loudly. Audit the converter's output schema-by-schema; do not trust exit codes.

Assumptions and uncertainty

Tool support for 3.1 changes frequently, so treat any specific generator's behavior as unverified until probed — the probe approach above is deliberately tool-agnostic for that reason. If you can share which generators your downstream teams run, the recommendation on which version to author as the source may change, since some converters are stronger in one direction than the other.