OpenAPI release notes

Each release of the OpenAPI Specification introduces new features, schema refinements, and structural changes - some safe, others breaking - that influence how developers design, describe, and document their APIs.

OpenAPI 3.2.0 (September 2025) is the newest feature release. It adds structured tag navigation, streaming-friendly media types, and fresh OAuth flows onto the JSON Schema-aligned foundation introduced in 3.1. Refer to the official release notes  for the canonical changelog.

OpenAPI version history

OpenAPI 3.2 vs 3.1

OpenAPI 3.2.0 builds on the JSON Schema 2020-12 alignment introduced in 3.1.0. It is a feature release: Your existing 3.1 descriptions keep working while you opt into new ergonomics for documentation, streaming, and security. The update is particularly useful if you publish Server-Sent Events (SSE) feeds or Model Context Protocol (MCP) connectors and want everything captured in one OpenAPI file.

At a glance

• Tag metadata is now standardized with summary, parent, and kind, replacing the vendor extensions many teams relied on.
• Streaming payloads gain first-class support through itemSchema, prefixEncoding, and guidance for sequential media types, such as SSE, JSON Lines, and multipart feeds.
• Security schemes pick up OAuth 2.0 device authorization, metadata URLs, a deprecated flag, and the option to reference shared schemes by URI.
• Documentation polish includes response summary, example dataValue/serializedValue, reusable components.mediaTypes, server name, and the top-level $self field.

Quick comparison

What’s new when you move to 3.2?

OpenAPI 3.2 keeps the OpenAPI 3.1 descriptions valid while unlocking several headline upgrades. Here’s what changes for teams planning the move:

• Navigation metadata: Standard tag fields (summary, parent, and kind) replace the common x-displayName / x-tagGroups pattern. You can keep existing vendor extensions for backwards compatibility, but update doc toolchains so they favor the official fields.
• Streaming support: The addition of itemSchema, prefixEncoding, and sequential media type guidance makes SSE, JSON Lines (JSONL), and MCP channels first-class citizens. Preview how your generators or SDKs render stream payloads before switching production specs.
• HTTP coverage: The new query operation, additionalOperations, and querystring parameter location align the spec with real-world verbs and encodings. Check linters and gateways for compatibility — old keywords still work, but new ones may require upgrades.
• Docs and security polish: Addition of response summary field, example dataValue/serializedValue fields, reusable components.mediaTypes, server name, $self fields, OAuth device flows, metadata URLs, and URI-referenced schemes all streamline governance. Adopt them incrementally; every feature is opt-in.

Ready for the deep dive? Head to What’s new in OpenAPI 3.2? for implementation examples and notes.

Should you upgrade?

Upgrade now if:

• Your docs currently rely on x-displayName / x-tagGroups or you want cleaner nested navigation
• You expose streaming APIs (SSE, JSON Lines, multipart feeds) or MCP connectors and want generators to understand them
• Security reviews would benefit from the OAuth device flow, metadata URLs, or scheme deprecation signals
• You plan to publish reusable media type definitions or need a canonical $self URL for multi-document specs

Hold off if:

• Your tooling pipeline cannot yet parse query operations, the querystring parameter location, or the new example fields
• You are mid-migration from OpenAPI 2.0 or 3.0 and prefer to stabilize on 3.1 before adopting new keywords
• Third-party consumers depend on current vendor extensions and need time to add support for the standardized fields

OpenAPI 3.2 vs 3.0

If you’re still on OpenAPI 3.0, moving straight to 3.2 lets you skip an intermediate upgrade while adopting both the OpenAPI 3.1 JSON Schema alignment and the OpenAPI 3.2 usability improvements. OpenAPI 3.1.0 was a mostly iterative release, with some breaking changes, whereas 3.2.0 is a feature release.

OpenAPI 3.1 vs 3.0

OpenAPI 3.1 introduces JSON Schema compliance, improved webhooks support, and breaking changes like the discontinued support for semantic versioning. You may want to stick to OpenAPI 3.0 because it offers:

• Easier migration from OpenAPI 2.0: Incremental changes make the transition smoother.
• More stable tooling support: Many API tools and frameworks still default to OpenAPI 3.0.

OpenAPI 3.1.1 vs 3.1.0

OpenAPI 3.1.1  is not a feature release but a refinement of OpenAPI 3.1.0. It improves terminology, JSON Schema alignment, reference handling, and documentation clarity without introducing breaking changes from OpenAPI 3.1.0. The most interesting change is in terminology.

Previously, “OpenAPI document” and “OpenAPI definition” were used inconsistently. OpenAPI 3.1.1 standardizes these definitions:

• OpenAPI description: The complete API definition, which may span multiple documents.
• OpenAPI document: A single file that makes up the whole or a part of an OpenAPI description.
• OpenAPI entry document: The starting point of an OpenAPI description, from which references can be resolved.

If your OpenAPI definition spans multiple files, the entry document is the file that tools like Swagger or Redoc first load to process your API definition.

What’s new in OpenAPI 3.2?

OpenAPI 3.2.0 folds years of community extensions directly into the specification. Use this deep dive when you’re ready to implement the changes. The sections below walk through the navigation metadata, streaming semantics, and security tooling, including snippets and migration tips.

Hierarchical tags and navigation metadata

Tag objects now ship with the summary, parent, and kind fields, so documentation tools can build nested navigation without relying on x-displayName or x-tagGroups. The optional kind field works with the OpenAPI registry to keep category names consistent across docs, and it lets you earmark tags for specific audiences (docs-only, SDK badges, internal tooling) without polluting navigation. As you migrate, consider contributing new kind values back to the community registry, so other teams can reuse the same taxonomy.

tags:
  - name: accounts
    summary: Account management
    kind: nav
  - name: accounts.reports
    summary: Analytics reports
    parent: accounts
    kind: badge

You can mix these standard fields with existing vendor extensions while your tooling catches up.

SSE, MCP streams, and other streaming media types

OpenAPI 3.2 makes Server-Sent Events (SSE) a first-class citizen. Describe each message with itemSchema, and tooling will treat the response as a stream rather than an opaque blob. The same technique covers application/jsonl, application/json-seq, and multipart payloads, and you can adjust chunk boundaries with prefixEncoding and itemEncoding. If you ship Model Context Protocol (MCP) connectors over SSE, you can now keep the stream contract in the same OpenAPI document as the rest of the API.

The spec explicitly recognizes text/event-stream, application/jsonl, application/json-seq, and multipart/mixed, which gives generators consistent guidance for chat, AI, IoT, and financial-data feeds that were previously awkward to document.

With the stream semantics defined in OpenAPI, MCP server generators can wire up REST setup endpoints and SSE tool channels from one source, instead of juggling separate manifests.

content:
  multipart/mixed:
    prefixEncoding:
      boundary: live-feed
    itemSchema:
      type: object
      properties:
        id:
          type: string
        attachment:
          type: string
          format: binary
    itemEncoding:
      attachment:
        contentType: image/png

With itemSchema in place, documentation portals can render example SSE payloads line-by-line, and client SDKs can surface typed callbacks, such as onPriceUpdate, without additional vendor extensions. You can also pre-register shared SSE schemas under components.mediaTypes to keep event definitions consistent across multiple endpoints.

SSE authoring checklist

• Model each SSE field (event, id, retry, and data) in the schema, so consumers know which keys to expect.
• Document reconnection behavior by pairing the SSE response with Last-Event-ID headers or query parameters.
• Add an example showing the literal wire format (serializedValue) alongside the structured dataValue object that will be parsed by the client.
• Mention compatible client tooling (for example, browsers’ EventSource API or server frameworks) in accompanying guides to capture discovery traffic.
• If your API powers MCP connectors, note the tool IDs or channel names, so agent builders can map SSE topics to MCP tools without hunting through extra docs.

HTTP operation and parameter updates

OpenAPI 3.2 expands HTTP coverage with a dedicated query method and an additionalOperations bucket for less common verbs. The query verb formalizes safe, idempotent payload-driven lookups, so you no longer have to overload POST to support complex search builders. Parameters can target the entire querystring, letting you model structured filters as a single Schema Object, allowReserved works wherever percent-encoding would normally apply, and cookies gain a purpose-built cookie style that preserves delimiters.

paths:
  /preferences:
    query:
      summary: Fetch preference suggestions
      parameters:
        - in: querystring
          name: payload
          content:
            application/json:
              schema:
                type: object
        - in: cookie
          name: preferences
          style: cookie
          explode: false
      additionalOperations:
        PROPFIND:
          summary: Inspect stored preference metadata

Examples, responses, and documentation polish

The Example Object gains dataValue and serializedValue fields, so you can show both structured data and the literal payload. Responses now support a short summary and no longer require description, and components.mediaTypes lets you register reusable content definitions. A new name field for servers, plus the top-level $self URI, make multi-environment docs easier to navigate.

components:
  mediaTypes:
    application/jsonl:
      schema:
        $ref: '#/components/schemas/ResultEvent'
 
paths:
  /results:
    get:
      responses:
        "200":
          summary: Batch of results
          content:
            application/jsonl:
              examples:
                sample:
                  dataValue:
                    id: evt_01
                    status: success
                  serializedValue: '{"id":"evt_01","status":"success"}'
 
servers:
  - url: https://sandbox.api.example.com
    name: Sandbox
$self: https://api.example.com/openapi.yaml

Security, server, and document governance

OAuth 2.0 device flows join the core spec alongside an oauth2MetadataUrl for OpenID Connect discovery documents. The device profile is tailored for smart TVs, kiosks, and other limited-input form factors, so you can model the hand-off without falling back to prose. Security schemes can be flagged as deprecated, and you can reference shared schemes by URI. The metadata URL support mirrors how open finance ecosystems publish discovery endpoints, and together with formalized URL-resolution guidance and $self, federated specs become easier to compose.

components:
  securitySchemes:
    oauthDevice:
      type: oauth2
      oauth2MetadataUrl: https://auth.example.com/.well-known/oauth-authorization-server
      deprecated: false
      flows:
        deviceAuthorization:
          deviceAuthorizationUrl: https://auth.example.com/device
          tokenUrl: https://auth.example.com/token
          scopes:
            reports: Read usage reports
security:
  - https://security.example.com/schemes/api-key: []
  - oauthDevice: [reports]

XML and polymorphism improvements

XML-heavy APIs receive a new nodeType property that replaces attribute: true and clarifies how arrays and CDATA map to XML nodes. Discriminators now accept a defaultMapping, and propertyName can be omitted when tooling infers the correct schema.

components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          xml:
            nodeType: attribute
        notes:
          type: string
          xml:
            nodeType: cdata
    Payment:
      oneOf:
        - $ref: '#/components/schemas/CardPayment'
        - $ref: '#/components/schemas/BankTransfer'
      discriminator:
        defaultMapping: '#/components/schemas/CardPayment'

What’s new in OpenAPI 3.1?

OpenAPI 3.1 introduces the following changes.

Full JSON Schema 2019-09 support

In OpenAPI 3.0, handling null values requires the use of a separate nullable property, which is inconsistent with JSON Schema standards.

In OpenAPI 3.1, nullable has been removed, and you can use null directly as a valid type, which aligns with the JSON Schema 2019-09.

Nullable in OpenAPI 3.0

The following schema demonstrates how to define nullability in OpenAPI 3.0:

type: object
properties:
  value:
    type: string
    nullable: true

Null in OpenAPI 3.1

The equivalent schema in OpenAPI 3.1 uses a union type to represent null:

type: object
properties:
  value:
    type: ["string", "null"]

You can learn more about nullability in Speakeasy’s OpenAPI schemas documentation.

Webhooks support

Before OpenAPI 3.x, the OpenAPI Specification didn’t provide a way to describe event-driven behavior.

OpenAPI 3.0 introduces callbacks, which allow for the documenting of asynchronous requests from the server back to the client. While callbacks aren’t a perfect fit for modeling webhooks, they are often used as a workaround for doing so.

OpenAPI 3.1 introduces a dedicated webhooks field for documenting outgoing API events (for example, notifying a client when a user is created).

Webhooks in OpenAPI 3.0

In OpenAPI 3.0, you need to use a workaround like callbacks to document webhooks:

paths:
  /subscribe:
    post:
      summary: Subscribe to price change events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
              required:
                - callbackUrl
      responses:
        "202":
          description: Subscription accepted
      callbacks:
        onPriceChange:
          "{$request.body#/callbackUrl}":
            post:
              summary: Price change notification
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        id:
                          type: string
                        price:
                          type: number
                      required:
                        - id
                        - price
              responses:
                "200":
                  description: Notification received

Webhooks in OpenAPI 3.1

With OpenAPI 3.1, you can define webhooks directly:

webhooks:
  userRegistered:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
      responses:
        "200":
          description: Acknowledged

OpenAPI does not provide a way to explicitly link a webhook with its registration, which is needed to allow users to subscribe to alerts, but you can address this by following the Speakeasy guide to using webhooks in OpenAPI.

Path items in components

In OpenAPI 3.0, if you have multiple endpoints with similar structures (for example, user-related paths like /users/{id} and /admins/{id}), you have to repeat the same request structure for each path.

OpenAPI 3.1 allows reusable path item objects to be stored in components.pathItems, reducing duplication and improving maintainability.

Paths in OpenAPI 3.0

In OpenAPI 3.0, each path has to be fully defined, even if multiple endpoints share the same request structure:

paths:
  /users/{id}:
    get:
      summary: Get user information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User data
 
  /admins/{id}:
    get:
      summary: Get admin information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Admin data

Paths in OpenAPI 3.1

In OpenAPI 3.1, you can define the path structure once and reuse it across multiple paths:

components:
  pathItems:
    userLookup:
      get:
        summary: Get user or admin information
        parameters:
          - name: id
            in: path
            required: true
            schema:
              type: string
        responses:
          "200":
            description: User or admin data
 
paths:
  /users/{id}:
    $ref: "#/components/pathItems/userLookup"
 
  /admins/{id}:
    $ref: "#/components/pathItems/userLookup"

Breaking changes in OpenAPI 3.1

Apart from these structural improvements, OpenAPI 3.1 introduces breaking changes that may require modifications to existing OpenAPI documents. Here are the most important ones:

• OpenAPI no longer follows semantic versioning (SemVer): Future updates may introduce breaking changes, even in minor version increments.
• exclusiveMaximum and exclusiveMinimum values must be numeric: Boolean values (true and false) are no longer valid. Use a numeric limit instead.
• format no longer defines file payloads: You can no longer use format: binary or format: base64. Use contentEncoding and contentMediaType instead.
• The jsonSchemaDialect field has been added: A new top-level field allows you to specify the default $schema value for schema objects, ensuring consistency in JSON Schema validation.

Visit the OpenAPI GitHub repository to learn more about the changes introduced in OpenAPI 3.0  and OpenAPI 3.1 .