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 the x-displayName extension 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: nav

OpenAPI 3.2 adds built-in support for streaming media types:

• text/event-stream
• application/jsonl
• application/json-seq
• multipart/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-time

OpenAPI 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 results

There'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.
• defaultMapping on 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:

• OpenAPI 3.2 specification
• Migration guide from 3.1 to 3.2
• Redocly changelog