OpenAPI 3.2.0: nested tags, query method, streaming (SSE, J…

The OpenAPI Initiative shipped v3.2.0 as the next backward-compatible step on the 3.x line — the GitHub tag landed 2025-09-19, with the blog walkthrough on 2025-09-23. It's a minor release in version-number terms but a significant one in practice: navigation, the HTTP method surface, streaming media types, and security flows all pick up first-class support for patterns that previously required hand-rolled extensions.

We are delighted and proud to announce the release of v3.2.0 of the OpenAPI Specification!

TL;DR

Tags get summary, parent (nesting), and kind for richer navigation and tooling roles.
`query` HTTP method as a first-class verb for idempotent reads with a structured body.
`additionalOperations` opens the door to verbs outside the default map.
`querystring` location models the entire query string as a single Schema Object.
Sequential media types (SSE, JSONL, JSON Sequences, multipart/mixed) document with itemSchema.
OAuth 2.0 Device Authorization and Authorization Server Metadata added.
Backward compatible with 3.1 — most existing documents validate against 3.2 unchanged.

Tags and navigation

The Tag Object has been the same for a decade: a name and an optional description. v3.2 makes tags a richer organizational unit:

`summary` — a short label distinct from the description.
`parent` — references another tag as the parent, enabling nested navigation.
`kind` — typed taxonomy for the tag (nav, badge, audience, capability), with a community tag-kind registry.

For documentation generators, this is a real upgrade. Instead of a flat alphabetical list, tools can render a tree:

Billing
  └─ Subscriptions
  └─ Invoices
Users
  └─ Authentication
  └─ Profile

The `kind` registry standardizes labels across documentation tools so a tag marked "internal" in one tool's syntax means the same thing in another's.

HTTP method surface

OpenAPI's HTTP method coverage was conservative for years — the standard get, post, put, patch, delete, options, head, trace. v3.2 expands the surface:

### query method

The IETF HTTP QUERY method is a draft standard for idempotent reads that need a structured body. Two reasons it exists:

Long, complex search filters that don't fit in a URL.
Sensitive search criteria that shouldn't appear in URL query strings (logged, cached, mirrored to telemetry).

The traditional workaround was to overload POST /search, which broke the semantic distinction between safe and unsafe methods. v3.2 documents query as a first-class operation:

paths:
  /users/search:
    query:
      summary: Search users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSearch'
      responses:
        '200':
          description: Users matching the criteria

### additionalOperations

For HTTP methods outside the default map (custom WebDAV verbs, application-specific methods), additionalOperations provides an escape hatch:

paths:
  /resource:
    additionalOperations:
      LOCK:
        summary: Acquire an exclusive lock
        responses:
          '200': { description: Lock acquired }

Each additional operation is a normal Operation Object — same schema, same validation rules.

### querystring location

Query parameters were typically declared one at a time:

parameters:
  - in: query
    name: page
  - in: query
    name: pageSize
  - in: query
    name: sort

For complex queries, that becomes verbose and obscures the relationship between fields. v3.2 adds querystring as a parameter location, allowing a single Schema Object to model the entire query string:

parameters:
  - in: querystring
    schema:
      $ref: '#/components/schemas/UserListQuery'

The schema can express conditional fields, mutual exclusivity, and nested objects (URL-encoded) — things hard to capture with one-parameter-at-a-time syntax.

Streaming and AI-shaped APIs

Modern APIs increasingly stream responses — chat completions deliver tokens as they're generated, IoT feeds push events continuously, dashboards subscribe to metrics. v3.2 documents these patterns natively:

`text/event-stream` (Server-Sent Events).
`application/json-seq` (JSON Sequences, RFC 7464).
`application/jsonl` (JSON Lines).
`multipart/mixed` for boundary-delimited streams.

For each, itemSchema describes the shape of an individual streamed item:

responses:
  '200':
    content:
      text/event-stream:
        itemSchema:
          $ref: '#/components/schemas/ChatToken'

Codegen tools and runtime validators can use itemSchema to type the stream's items, enabling typed streaming clients without bespoke spec extensions. This is the biggest practical win for AI-adjacent APIs that previously had to document streaming responses with prose comments.

Security: OAuth 2.0 device flow and metadata

Two OAuth 2.0 features get first-class support:

Device Authorization Grant (RFC 8628) — the flow used by smart TVs, CLI tools, and other devices that can't easily host a browser. v3.2 adds the relevant flow descriptor.
Authorization Server Metadata (RFC 8414) — clients can discover an authorization server's endpoints and capabilities from a well-known URL. v3.2 adds oauth2MetadataUrl to flow definitions, pointing at the server's metadata document.

securitySchemes:
  oauth2:
    type: oauth2
    flows:
      deviceAuthorization:
        deviceAuthorizationUrl: https://auth.example.com/device
        tokenUrl: https://auth.example.com/token
        oauth2MetadataUrl: https://auth.example.com/.well-known/oauth-authorization-server
        scopes:
          read: Read access

For tooling, this means clients can discover scopes and supported grant types without out-of-band configuration.

Backward compatibility

3.2 is backward compatible with 3.1. Existing documents validate against 3.2 unchanged. The new features are additive — opt in when you want them. Most validators released 3.2 support during late 2025 / early 2026.

Migration

If you're upgrading from 3.1:

Bump the `openapi` version field to 3.2.0. That's the only mandatory change.
Adopt new tag attributes when you want richer navigation in your docs.
Replace overloaded `POST /search` patterns with query operations where appropriate.
Document streaming responses with itemSchema instead of prose.
Add `oauth2MetadataUrl` to existing OAuth flows for better client discovery.

The official v3.1 → v3.2 upgrade guide covers each migration in detail.

Tooling status

By early 2026, the major OpenAPI tools have shipped 3.2 support:

Validators — @apidevtools/swagger-parser, spectral, and the OpenAPI Foundation's own validators all read 3.2 documents.
Documentation generators — redocly, scalar, stoplight, elements, and swagger-ui render the new tag attributes and querystring parameters.
Codegen — openapi-typescript, openapi-fetch, openapi-zod, and @hey-api/openapi-ts generate clients that understand the new media types.
Editors — @redocly/cli, stoplight studio, and the JetBrains / VS Code OpenAPI plugins offer 3.2 schemas for autocompletion.

The fact that all major implementations shipped support within months of the spec is unusual for OpenAPI minor releases — historically the ecosystem trailed by half a year or more. The shorter latency reflects how tightly the OAI now coordinates with the major vendors.

Common pitfalls during the migration

A few patterns that have tripped up early adopters:

Tag references must reference real tag definitions. Adding parent: Foo doesn't auto-create a Foo tag; declare it explicitly under the top-level tags array.
`querystring` parameters and individual query parameters can't be mixed within the same operation. Pick one.
`itemSchema` on response media types validates each streamed event, not the whole response body. Don't put a wrapper schema there.
`additionalOperations` is for verbs the OpenAPI spec doesn't enumerate. Don't redefine standard methods (get, post) under it; you'll get duplicate-operation errors from validators.
OAuth `oauth2MetadataUrl` points at the server's metadata document, not your application's API description. Common mistake: pointing at /.well-known/openapi.yaml instead of /.well-known/oauth-authorization-server.

The validator output is usually clear about these errors, but the messages can read like spec-jargon if you're not used to it.

Where this connects

The Overlay Specification 1.1.0 release is the companion patch-layer spec — together they let you ship one canonical OpenAPI document and apply per-environment edits without forking. The February 2026 OAI newsletter covers Moonwalk and the LLM-agent direction.

References

Source / further reading: OpenAPI Initiative blog

OpenAPI 3.2.0: nested tags, query method, streaming (SSE, JSONL), OAuth device flow