OpenAPI 3.2 was released in September 2025 as a follow-up to 3.1. This release adds support for streaming APIs, hierarchical tags, new HTTP methods, and updated security flows.
It's also a fully backward-compatible release. Nothing breaks. You can update the version number and start using new features at your own pace. Here's a look at what's new and how Redocly supports it.
Tags in OpenAPI can now be organized into hierarchies. This is especially useful for larger APIs where grouping operations into categories makes navigation easier. Redocly users may recognize the x-tagGroups extension that we introduced for this purpose. OpenAPI 3.2 brings a native version of this idea directly into the spec.
The Tag Object now has three new fields:
parent— reference another tag to create a hierarchy.summary— a short display label. Works the same way as thex-displayNameextension in Redocly.kind— classify tags by purpose, backed by a community registry.
tags:
- name: information
summary: About the museum
description: Information about the museum
kind: nav
- name: museum-hours
summary: Museum hours
description: Opening hours and schedule
parent: information
kind: navOpenAPI 3.2 adds built-in support for streaming media types:
text/event-streamapplication/jsonlapplication/json-seqmultipart/mixed
Along with these media types, there's a new itemSchema field that describes the shape of each individual item in the stream.
paths:
/events:
get:
responses:
'200':
content:
text/event-stream:
itemSchema:
type: object
properties:
event:
type: string
data:
type: string
timestamp:
type: string
format: date-timeOpenAPI 3.2 adds support for the QUERY method. QUERY is idempotent, safe, and accepts a request body, making it a good fit for complex search operations where you need to send structured criteria.
paths:
/search:
query:
operationId: searchProducts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCriteria'
responses:
'200':
description: Search resultsThere's also a new additionalOperations field for APIs that use HTTP methods beyond the standard set.
OpenAPI 3.2 adds support for OAuth 2.0 Device Authorization Flow through the new deviceAuthorization field in the OAuth Flows Object.
The release also introduces oauth2MetadataUrl for pointing to OAuth 2.0 server metadata, and the ability to mark security schemes as deprecated.
OpenAPI 3.2 introduces two new fields for examples: dataValue and serializedValue. These let you show both the structured data and the serialized representation of an example, which is especially helpful for cookies, headers, and other parameters with encoding rules.
examples:
UserPrefs:
description: Cookie with encoded values
dataValue:
theme: "dark,mode"
notifications: true
serializedValue: "theme=dark%2Cmode; notifications=true"dataValue is the structured data that developers work with in code. serializedValue is how it looks when transmitted over HTTP. Having both in the same place makes API documentation easier to understand.
Some more features added in this release:
queryString— a new parameter location that lets you describe the entire query string as a single schema, rather than individual parameters.- XML
nodeType— explicit mapping of schemas to XML elements, attributes, text, or CDATA nodes. defaultMappingon discriminators — define a fallback schema when the discriminator property is missing or doesn't match any mapping.
Redocly fully supports OpenAPI 3.2 - linting, rendering, code samples, mock server, Respect, and all the features described in this post. To upgrade, change openapi: 3.1.0 to openapi: 3.2.0 in your description and start adopting new features as you need them. Since 3.2 is backward-compatible, nothing breaks.
Useful links: