What are the key differences between OpenAPI 3.0 and OpenAPI 3.1? #

The OpenAPI Specification has evolved significantly over the years, and one of its most consequential upgrades was the transition from version 3.0 to version 3.1. Released in February 2021 by the OpenAPI Initiative, OpenAPI 3.1 introduced a range of improvements that tightened the relationship between OpenAPI and JSON Schema, resolved long-standing inconsistencies, and added new capabilities for describing modern APIs. For teams that have invested in OpenAPI 3.0 documents, understanding these differences is essential before planning a migration.

Full Alignment with JSON Schema #

The most significant change in OpenAPI 3.1 is its full alignment with the JSON Schema specification — specifically JSON Schema Draft 2020-12. In OpenAPI 3.0, the Schema Object was described as an extended subset of JSON Schema Draft 4 with some modifications that actually made it incompatible with standard JSON Schema validators. This caused friction for developers trying to reuse schemas across tooling ecosystems.

OpenAPI 3.1 resolves this by adopting JSON Schema vocabulary in full, without modification. This means:

• Standard JSON Schema keywords like $schema, $id, $dynamicRef, $dynamicAnchor, unevaluatedProperties, and unevaluatedItems are now valid in OpenAPI schema objects.
• Schemas written for OpenAPI 3.1 can be validated with any conformant JSON Schema Draft 2020-12 validator, such as AJV or jsonschema.
• Tools and libraries that already support JSON Schema can now work with OpenAPI schemas without translation layers.

For teams building large API platforms, this alignment drastically simplifies schema reuse and tooling integration.

Removal of OpenAPI-Specific Schema Modifications #

OpenAPI 3.0 introduced several modifications to JSON Schema keywords that deviated from the standard. Two notable examples:

nullable Replaced by JSON Schema type Arrays #

In OpenAPI 3.0, making a field nullable required the proprietary nullable: true keyword alongside the type. For example:

schema:
  type: string
  nullable: true

In OpenAPI 3.1, the standard JSON Schema approach is used — type can be an array of types:

schema:
  type: [string, "null"]

This is a breaking change that requires updating schemas on migration, but it correctly aligns with how JSON Schema handles optional null values.

exclusiveMinimum and exclusiveMaximum Changed #

In OpenAPI 3.0, exclusiveMinimum and exclusiveMaximum were booleans that modified the behavior of minimum and maximum. In JSON Schema Draft 2020-12 (and therefore OpenAPI 3.1), they are numbers that directly express the exclusive bound:

# OpenAPI 3.0
minimum: 0
exclusiveMinimum: true

# OpenAPI 3.1
exclusiveMinimum: 0

Webhooks Support #

OpenAPI 3.0 lacked a standard way to describe webhooks — asynchronous HTTP callbacks that a server sends to a client-registered URL. While callbacks existed, they modeled a different pattern (request-triggered outgoing calls).

OpenAPI 3.1 introduces a dedicated top-level webhooks object, allowing API providers to formally describe the shape of events their service will POST to subscriber endpoints:

webhooks:
  newOrder:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        "200":
          description: Return a 200 to signal receipt

This is especially relevant for event-driven integrations found in platforms like Stripe, GitHub, and Shopify.

Improved $ref Behavior #

In OpenAPI 3.0, the $ref object did not allow sibling properties — any keywords alongside $ref were silently ignored. OpenAPI 3.1 lifts this restriction, following the JSON Schema specification, which means you can now do:

schema:
  $ref: '#/components/schemas/BaseModel'
  description: An override description for this specific usage

This enables more precise documentation without duplicating entire schema definitions.

The pathItems Component Type #

OpenAPI 3.1 adds pathItems as a new reusable component type, allowing path item objects (which describe a set of operations for a given path) to be defined once in components and referenced via $ref wherever needed. This reduces repetition in APIs with similar endpoint patterns across multiple paths.

Schema const Keyword #

OpenAPI 3.1 now supports the const keyword from JSON Schema, which restricts a field to a single exact value:

schema:
  type: string
  const: "active"

This was previously approximated using an enum with a single value in OpenAPI 3.0, but const is more semantically precise and better supported in schema-aware tooling.

summary Field on Path Items #

OpenAPI 3.1 adds an optional summary field to Path Item Objects, complementing the existing description field. This is a minor but useful documentation improvement, enabling concise one-line summaries that appear prominently in generated documentation tools like Redoc and Stoplight Elements.

Licensing and Info Improvements #

The info object gains two new optional fields in OpenAPI 3.1:

• summary — a short, single-sentence description of the API, useful in contexts where a full description is too verbose.
• license.identifier — an SPDX license identifier (e.g., MIT, Apache-2.0) as an alternative to providing a full url.

Breaking Changes Summary #

Migrating from OpenAPI 3.0 to 3.1 requires addressing a handful of breaking changes:

Tooling Ecosystem Adoption #

As of 2025, most major OpenAPI tools have added OpenAPI 3.1 support, though coverage varies. Tools that have adopted it include:

• Redocly CLI — supports bundling, linting, and rendering 3.1 documents.
• Stoplight Studio — visual editor with full 3.1 support.
• Swagger UI — rendering support for 3.1 was added in version 5.x.
• openapi-generator — code generation support for 3.1 is ongoing.
• Spectral — linting ruleset support for 3.1.

Teams should evaluate their toolchain before upgrading to ensure full compatibility.

Should You Upgrade? #

For new projects, OpenAPI 3.1 is the recommended starting point. Its alignment with JSON Schema dramatically improves ecosystem interoperability and makes schemas portable across validation, documentation, and code generation tooling.

For existing OpenAPI 3.0 projects, upgrading involves schema changes (nullable, exclusive bounds), but the benefits — especially full JSON Schema compatibility and webhook support — are worth the investment. Tools like openapi-format and the Redocly CLI can assist with automated migration.

The official OpenAPI 3.1.0 release blog post and the full specification are the authoritative references for teams planning an upgrade.

Conclusion #

OpenAPI 3.1 is a significant and mostly backward-compatible leap forward from 3.0. By fully embracing JSON Schema, adding webhook support, and resolving longstanding inconsistencies, it positions the OpenAPI Specification as a more robust and interoperable standard for API description. Understanding the key differences is the first step toward making an informed migration decision for any API team.

Last updated on April 29, 2026.