{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 3.2 was released in September 2025 as a follow-up to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/oas/v3.1.0.html"},"children":["3.1"]},". This release adds support for streaming APIs, hierarchical tags, new HTTP methods, and updated security flows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hierarchical-tags","__idx":0},"children":["Hierarchical tags"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-tagGroups"]}," extension that we introduced for this purpose. OpenAPI 3.2 brings a native version of this idea directly into the spec."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/oas/v3.2.0.html#tag-object"},"children":["Tag Object"]}," now has three new fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parent"]}]}," — reference another tag to create a hierarchy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]}]}," — a short display label. Works the same way as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-displayName"]}," extension in Redocly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}]}," — classify tags by purpose, backed by a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/registry/tag-kind/index.html"},"children":["community registry"]},"."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"tags:\n  - name: information\n    summary: About the museum\n    description: Information about the museum\n    kind: nav\n\n  - name: museum-hours\n    summary: Museum hours\n    description: Opening hours and schedule\n    parent: information\n    kind: nav\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"streaming-support","__idx":1},"children":["Streaming support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 3.2 adds built-in support for streaming media types:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text/event-stream"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/jsonl"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json-seq"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/mixed"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Along with these media types, there's a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itemSchema"]}," field that describes the shape of each individual item in the stream."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n  /events:\n    get:\n      responses:\n        '200':\n          content:\n            text/event-stream:\n              itemSchema:\n                type: object\n                properties:\n                  event:\n                    type: string\n                  data:\n                    type: string\n                  timestamp:\n                    type: string\n                    format: date-time\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"query-method-and-additional-http-methods","__idx":2},"children":["QUERY method and additional HTTP methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n  /search:\n    query:\n      operationId: searchProducts\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/SearchCriteria'\n      responses:\n        '200':\n          description: Search results\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There's also a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["additionalOperations"]}," field for APIs that use HTTP methods beyond the standard set."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"updated-security-features","__idx":3},"children":["Updated security features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 3.2 adds support for ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc8628"},"children":["OAuth 2.0 Device Authorization Flow"]}," through the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deviceAuthorization"]}," field in the OAuth Flows Object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The release also introduces ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth2MetadataUrl"]}," for pointing to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc8414"},"children":["OAuth 2.0 server metadata"]},", and the ability to mark security schemes as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"new-example-fields-datavalue-and-serializedvalue","__idx":4},"children":["New example fields: dataValue and serializedValue"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI 3.2 introduces two new fields for examples: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"examples:\n  UserPrefs:\n    description: Cookie with encoded values\n    dataValue:\n      theme: \"dark,mode\"\n      notifications: true\n    serializedValue: \"theme=dark%2Cmode; notifications=true\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataValue"]}," is the structured data that developers work with in code. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serializedValue"]}," is how it looks when transmitted over HTTP. Having both in the same place makes API documentation easier to understand."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"other-changes-worth-knowing-about","__idx":5},"children":["Other changes worth knowing about"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some more features added in this release:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queryString"]}]}," — a new parameter location that lets you describe the entire query string as a single schema, rather than individual parameters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["XML ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nodeType"]}]}," — explicit mapping of schemas to XML elements, attributes, text, or CDATA nodes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultMapping"]}," on discriminators"]}," — define a fallback schema when the discriminator property is missing or doesn't match any mapping."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-started-with-openapi-32-in-redocly","__idx":6},"children":["Get started with OpenAPI 3.2 in Redocly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly fully supports OpenAPI 3.2 - linting, rendering, code samples, mock server, Respect, and all the features described in this post. To upgrade, change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi: 3.1.0"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi: 3.2.0"]}," in your description and start adopting new features as you need them. Since 3.2 is backward-compatible, nothing breaks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Useful links:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/oas/v3.2.0.html"},"children":["OpenAPI 3.2 specification"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://learn.openapis.org/upgrading/v3.1-to-v3.2.html"},"children":["Migration guide from 3.1 to 3.2"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/realm/changelog"},"children":["Redocly changelog"]}]}]}]},"frontmatter":{"template":"../@theme/templates/BlogPost","title":"OpenAPI 3.2 is here: what's new and how Redocly supports it","description":"An overview of OpenAPI 3.2 features and how to start using them with Redocly.","seo":{"title":"OpenAPI 3.2 is here: what's new and how Redocly supports it","description":"An overview of OpenAPI 3.2 features and how to start using them with Redocly."},"author":"ivan-kropyvnytskyi","publishedDate":"2026-03-11","categories":["api-specifications:openapi","redocly:redocly-cli","redocly:product-updates"],"image":"Redocly_blog_6.jpg"},"tagList":[],"title":"OpenAPI 3.2 is here: what's new and how Redocly supports it","lastModified":"2026-03-11T16:03:40.000Z"}