OpenAPI 3.1 vs 3.0: What's Actually New

OpenAPI 3.1, released in 2021, is the current version of the spec — but adoption has lagged because 3.0 already covers most teams’ needs and the migration isn’t always obvious. Here’s what actually changed.

Full JSON Schema compatibility

This is the headline change. OpenAPI 3.0’s Schema Object was inspired by JSON Schema but diverged from it in several places, which meant tooling built for standard JSON Schema couldn’t be reused directly against an OpenAPI 3.0 document. 3.1 aligns the Schema Object with JSON Schema 2020-12 exactly, so:

• Any JSON Schema validator now works unmodified against 3.1 schemas.
• Keywords that 3.0 excluded or handled differently — if/then/else, unevaluatedProperties, prefixItems — are now valid and behave per the standard.
• type can be an array (type: ["string", "null"]), matching plain JSON Schema, instead of only ever being a single value.

nullable is gone

The change most likely to actually break something during migration: OpenAPI 3.0’s nullable: true flag is removed in 3.1. The 3.1-correct way to express a nullable string is:

# OpenAPI 3.0
type: string
nullable: true

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

If you’re generating your spec from code annotations (FastAPI, NestJS, springdoc), check what your generator emits by default — some still produce the 3.0-style nullable flag even under an openapi: 3.1.0 declaration, which is invalid per the 3.1 schema even though most viewers will render it anyway out of leniency.

Webhooks are now first-class

3.1 adds a top-level webhooks field, letting a spec describe outbound calls your API makes to a consumer’s endpoint — not just the inbound endpoints it serves. This matters for any API with event-driven callbacks (payment providers, CI systems, messaging platforms) that previously had no standard way to document those shapes inside the same spec as the rest of the API.

Smaller field-level additions

• license.identifier — an SPDX license expression, as an alternative to a bare license.url string.
• summary on the Schema Object, alongside the existing description — useful for a short label distinct from a longer explanation.
• Path Item Objects can now be referenced with $ref directly, not just Schema and Parameter Objects.

Should you migrate?

If your spec doesn’t use nullable heavily and you don’t need webhooks documented, there’s little urgency — 3.0 remains well-supported and most tooling reads both versions without issue. The practical trigger for migrating is usually needing standard JSON Schema tooling to validate or transform your spec directly, since that’s the one thing 3.0’s schema dialect actively gets in the way of.

Either way, you don’t need to pick a viewer based on spec version — GetMan reads 3.0 and 3.1 documents the same way, since both declare their version explicitly in the openapi field. If you’re earlier in the naming confusion between the spec and the tooling built on it, OpenAPI vs Swagger covers that separately. For setup details, see the docs.