What's New in OpenAPI 3.2.0

OpenAPI 3.2.0 was published on September 19, 2025, marking the first minor version bump since 3.1.0 landed in February 2021. While 3.1.1 and 3.1.2 were patch releases focused on clarifications, 3.2.0 introduces genuine new features — new fields, new HTTP method support, improved streaming descriptions, and several quality-of-life additions that make the spec more expressive.

Here's a practical rundown of everything that changed.

ApiNotes now supports OpenAPI 3.2.0 validation. You can validate your 3.2 specs — including all the new fields covered below — using our free OpenAPI validator. It supports OpenAPI 3.2, 3.1, 3.0, and Swagger 2.0 in both JSON and YAML.

# The $self Field — Declaring a Document's Own URI

The OpenAPI Object now supports a $self field. This string must be a URI reference and serves as the document's self-assigned URI and base URI for resolving all relative references within it.

openapi: 3.2.0
$self: https://example.com/api/openapi.yaml
info:
  title: My API
  version: 1.0.0

This solves a long-standing pain point in multi-document API descriptions. Previously, reference resolution depended on retrieval URIs (the URL you actually fetched the file from), which broke when documents were moved, served locally, or embedded in other formats. With $self, the base URI is explicit and portable.

# Support for the QUERY HTTP Method

The Path Item Object now includes a dedicated query fixed field for describing a QUERY operation, based on the IETF draft draft-ietf-httpbis-safe-method-w-body. QUERY is a safe, idempotent method (like GET) that allows a request body — filling the gap where developers previously misused POST for complex search queries.

paths:
  /search:
    query:
      summary: Search for items
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCriteria'
      responses:
        '200':
          description: Search results

# additionalOperations — Any HTTP Method

For HTTP methods not covered by the fixed fields (GET, POST, PUT, DELETE, etc.), the new additionalOperations map on the Path Item Object lets you describe operations for any method. The map key is the HTTP method name with the exact capitalization to be sent in the request.

paths:
  /resources/{id}:
    additionalOperations:
      COPY:
        summary: Copy a resource
        operationId: copyResource
        responses:
          '200':
            description: Resource copied
      PURGE:
        summary: Purge a cached resource
        responses:
          '204':
            description: Cache purged

This removes the previous limitation where non-standard HTTP methods simply couldn't be described in an OpenAPI document.

# The querystring Parameter Location

A new value for the in field on Parameter Objects — "querystring" — allows you to describe the entire query string as a single parameter rather than decomposing it into individual query parameters. This is useful when the query string uses a format like JSONPath, GraphQL, or any structure that doesn't map cleanly to key-value pairs.

parameters:
  - in: querystring
    name: selector
    content:
      application/jsonpath:
        schema:
          type: string
        example: $.a.b[1:1]

# Tag Object Enhancements — Hierarchies and Kinds

Tags got significantly more useful with three new fields:

# parent

Tags can now reference a parent tag, creating a hierarchy. This is ideal for organizing large APIs into nested groups.

tags:
  - name: external
    summary: External
    kind: audience

  - name: partner
    summary: Partner
    parent: external
    kind: audience

# kind

A machine-readable string that categorizes what sort of tag it is. Common values include nav (for navigation grouping), badge (for visible badges), and audience (for consumer segmentation).

# summary

A short display-friendly name for the tag, separate from the name (which is used as an identifier) and the description (which supports full Markdown).

# Server Object: name Field

Server Objects can now include an optional name field — a unique string identifier for the server. This is useful when an API has multiple server entries and tooling or configuration needs to reference a specific one by name.

servers:
  - url: https://api.example.com/v2
    description: Production
    name: prod
  - url: https://sandbox.example.com/v2
    description: Sandbox
    name: sandbox

# Streaming and Sequential Content

OpenAPI 3.2.0 adds first-class support for describing streaming and sequential content, which was previously awkward or impossible.

# Sequential Media Types

The spec now formally defines "sequential media types" — media types that consist of a repeating structure without headers or envelopes. Examples include application/jsonl, application/x-ndjson, application/json-seq, and text/event-stream.

# itemSchema

The Media Type Object can use itemSchema to describe the schema of each individual item in a sequential stream, separate from schema which describes the complete collection.

# Server-Sent Events

There is now dedicated guidance for describing text/event-stream (SSE) content, including how to model the event, data, id, and retry fields.

# Example Object: dataValue and serializedValue

The Example Object has two new fields alongside the existing value:

• dataValue — An example of the data structure that must be valid according to the relevant Schema Object. If present, value must be absent.
• serializedValue — A string containing the serialized form of the example as it would appear in a request or response. This is useful for non-JSON examples (query strings, headers, binary-adjacent formats).

examples:
  withRating:
    summary: A work with a rating
    dataValue:
      author: A. Writer
      title: An Older Book
      rating: 4.5
    serializedValue: |
      {
        "author": "A. Writer",
        "title": "An Older Book",
        "rating": 4.5
      }

# Response Object: summary Field

Response Objects now support a summary field — a short human-readable string that complements the longer description. This mirrors the pattern already used on Operation, Info, and Tag objects.

# OAuth 2.0 Device Authorization Flow

The OAuth Flows Object gains a new deviceAuthorization flow, supporting the OAuth 2.0 Device Authorization Grant defined in RFC 8628. This is common for CLI tools, smart TVs, and IoT devices where a browser-based login isn't practical.

type: oauth2
flows:
  deviceAuthorization:
    deviceAuthorizationUrl: https://auth.example.com/device
    tokenUrl: https://auth.example.com/token
    scopes:
      read: Read access

# Security Scheme Improvements

# oauth2MetadataUrl

A new field on Security Scheme Objects of type oauth2 that points to the OAuth2 Authorization Server Metadata (RFC 8414). This lets tooling auto-discover endpoints rather than requiring them to be manually specified.

# deprecated

Security Scheme Objects can now be marked as deprecated, signaling to consumers that a particular authentication method should be transitioned away from.

# Cookie-Style Serialization

A new style: "cookie" value is available for cookie parameters, providing serialization that follows RFC 6265 cookie syntax rules (semicolon-space separated pairs, no percent-encoding). This replaces the previous approach of using style: "form" for cookies, which was a compatibility compromise.

# Encoding Improvements

# prefixEncoding

The Media Type Object supports prefixEncoding — an array of positional Encoding Objects for multipart media types. This enables describing ordered, unnamed multipart parts where the position in the array determines which part is being described.

# Nested Encoding

The spec adds guidance for nested encoding scenarios in multipart content.

# XML Object Enhancements

The XML Object received several new capabilities:

• nodeType field — Explicitly declare whether a schema maps to an XML element, attribute, or text node.
• Ordered elements — prefixItems in schemas can now represent ordered XML children, including mixed content (elements interleaved with text nodes).
• null handling — Formal guidance for serializing null values in XML using xsi:nil="true".

# Specification Extensions Registry

The OpenAPI Initiative now maintains registries for individual extension keywords and extension keyword namespaces. Extension field names beginning with x-oai- and x-oas- are reserved for uses defined by the OpenAPI Initiative.

# What Hasn't Changed

• JSON Schema alignment — 3.2.0 continues to use JSON Schema Draft 2020-12, same as 3.1.
• Format — Documents are still JSON or YAML. YAML 1.2 is recommended.
• Schema dialect — The OAS dialect schema ID remains https://spec.openapis.org/oas/3.1/dialect/base.
• Backwards compatibility — Tooling that supports OAS 3.1 should be broadly compatible. The patch version should not be considered by tooling, and the spec notes that non-backwards-compatible changes in minor versions are only made when impact is low relative to the benefit.

# Should You Upgrade?

If your API descriptions work fine on 3.1.x and you don't need the new features, there's no urgent reason to bump the version. But if any of these apply to you, 3.2.0 is worth adopting:

• You maintain multi-document API descriptions and want reliable reference resolution → use $self
• You need to describe non-standard HTTP methods → use additionalOperations
• You have streaming or SSE endpoints → use sequential media type support
• You organize a large API with many tags → use parent and kind
• Your auth uses OAuth device flow → use deviceAuthorization
• You describe complex query formats → use in: "querystring"

The full specification is available at spec.openapis.org/oas/v3.2.0.