OpenAPI 3.0 vs 3.1 for API Teams

Practical recommendation

OpenAPI 3.1 aligns its Schema Object with modern JSON Schema and represents nullable values through type unions. OpenAPI 3.0 uses its own Schema Object conventions such as nullable.

Inventory tooling before changing the version field. A syntactically correct 3.1 document can still break an older gateway, code generator, linter, or documentation pipeline.

Working example

# OpenAPI 3.0
type: string
nullable: true

# OpenAPI 3.1
type: [string, 'null']

Review checklist

• Every consumer declares 3.1 support.
• Nullable and exclusive bounds are migrated intentionally.
• Schema dialect behavior is tested.
• Generated clients receive regression coverage.

Compatibility, security, and limitations

• Version migration is not a text-only field change.
• Tool support changes over time and must be rechecked.
• DevPouch validates a focused local subset, not every extension.

Migration affects schema meaning

OpenAPI 3.1 aligns its Schema Object with a modern JSON Schema dialect. Nullable values use type unions, examples and exclusive bounds follow JSON Schema behavior, and a dialect can be declared. Changing only the openapi field can leave 3.0-specific keywords with different or ineffective meaning.

Inventory gateways, code generators, client/server generators, validators, documentation tools, mocks, and governance rules. A consumer that ignores unsupported 3.1 keywords is more dangerous than one that fails immediately because it can generate code with silently weaker constraints.

Compatibility test set

• Nullable scalar and nullable referenced object.
• Exclusive numeric bounds and multiple types.
• Schema dialect declaration and unsupported keyword reporting.
• Webhooks where they are part of the design.
• Generated client serialization and server validation.
• Rollback to the prior published contract without losing changed semantics.

References

• OpenAPI Specification 3.0.4
• OpenAPI Specification 3.1.1
• JSON Schema Draft 2020-12

FAQ

Related guides