# OpenAPI Release Notes # 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. This page is not an official OpenAPI release notes page. It explains key version changes with context, examples, and practical insights to help you decide whether to upgrade. 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](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.2.0) for the canonical changelog. ## OpenAPI version history | **Version** | **Release date** | **Changes** | **Breaking changes** | |-------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------| | **OpenAPI 3.2.0** | Sep 19, 2025 | - Adds hierarchical tag metadata (`summary`, `parent`, `kind`) fields and reusable media types
- Supports streaming-friendly payloads with `itemSchema`, `query` HTTP operations, and `querystring` parameters
- Expands security (OAuth2 device flow, metadata URL), responses (`summary`), and server naming options | Limited | | **OpenAPI 3.1.1** | Oct 24, 2024 | - Clarifies required fields and schema interpretation
- Improves JSON Schema vocabulary integration
- Refines OAuth 2.0 and bearer token documentation
- Fixes minor spec language and formatting
- Confirms no breaking changes from 3.1.0 | No | | **OpenAPI 3.1.0** | Feb 16, 2021 | - Achieves full JSON Schema 2020-12 compliance
- Adds support for the `webhooks` object
- Allows `$schema` declaration at the document root
- Makes `example` and `examples` mutually exclusive
- Removes the SemVer requirement in `info.version`
- Deprecates `nullable` in favor of `type: [T, "null"]`
- Relaxes rules around the `openapi` field | Yes | | **OpenAPI 3.0.0** | July 26, 2017 | - Overhauls the request body structure (`content` replaces `formData`, `body`)
- Introduces `components` for reusable schemas, parameters, and responses
- Improves parameter serialization and content negotiation
- Adds `callbacks` for async APIs
- Enhances documentation via `tags`, `externalDocs`, and `examples` | Yes | ## 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 | **Capability** | **OpenAPI 3.1** | **OpenAPI 3.2** | |--------------------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | **Tag navigation** | Relies on `x-displayName` / `x-tagGroups` vendor extensions | Native `summary`, `parent`, and `kind` fields with registry-backed conventions | | **Streaming payloads** | SSE and sequential feeds require callbacks or prose workarounds | `itemSchema`, `prefixEncoding`, `itemEncoding`, and sequential media types recognized | | **HTTP operations** | Standard verbs only | Adds `query` and `additionalOperations` for uncommon verbs | | **Parameters** | `query`, `header`, `path`, `cookie` locations | Adds `querystring`, extends `allowReserved`, and introduces a cookie `style` | | **Security metadata** | OAuth flows without device support or metadata URLs | Device flow, `oauth2MetadataUrl`, `deprecated`, and URI-based references | | **Documentation polish** | Response `description` required, examples lack structured/serialized split | Optional response `description`, new `summary` field, example `dataValue`/`serializedValue` fields, server `name`, `$self` fields | ### 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?](#whats-new-in-openapi-32) 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](https://github.com/OAI/OpenAPI-Specification/releases/tag/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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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: ```yaml 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`: ```yaml type: object properties: value: type: ["string", "null"] ``` You can learn more about nullability in Speakeasy's [OpenAPI schemas](/openapi/schemas/null) 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: ```yaml 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: ```yaml 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](/post/openapi-tips-webhooks-callbacks#creating-a-webhook-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: ```yaml 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: ```yaml 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](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0) and [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0).