OpenAPI Specification 3.2 Released – What’s New?

Introduction

The OpenAPI Specification (OAS) is the industry standard for describing REST APIs. By writing your API contract in OpenAPI, you can generate client and server stubs, validate requests and responses, create tests, and produce interactive API documentation.

Now, the OpenAPI Initiative has released version 3.2.0. This new version extends the 3.1 release with clarifications, formal definitions, and several important new features. Some of these changes may look small at first sight – but they have big practical implications for API designers and tool builders.

In this post, I’ll walk you through the most important changes, provide examples, and give some recommendations on when and how to adopt 3.2.

New Features in OpenAPI 3.2

According to the official release notes, the following features are the most important highlights of the 3.2 release.

1. Formal Definition of Path Templating

OpenAPI has always supported path variables like /users/{id}, but until now the rules were a bit fuzzy.

In 3.2, the syntax of path templates is now formally defined in ABNF. This means:

• Variables must be enclosed in {}
• Each variable can appear only once per path
• Variable names must match a clear pattern
• Reserved characters are not allowed inside variables

Example:

paths:
  /users/{userId}/orders/{orderId}:
    get:
      summary: Get a specific order
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK

While this looks the same as before, the difference is that tools can now validate path templates strictly and consistently, reducing ambiguities across generators and documentation platforms.

2. Support for Additional HTTP Methods (additionalOperations)

Up to now, OpenAPI only allowed the “standard” HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.).

With OpenAPI 3.2, you can now document non-standard or extension methods via the new additionalOperations keyword. Examples: LINK, UNLINK, PURGE, or even custom verbs.

Example:

paths:
  /resources/{id}:
    additionalOperations:
      LINK:
        summary: Link this resource to another
        parameters:
          - name: id
            in: path
            required: true
            schema:
              type: string
          - name: target
            in: query
            required: true
            schema:
              type: string
        responses:
          '204':
            description: Resource linked
      UNLINK:
        summary: Remove an existing link
        parameters:
          - name: id
            in: path
            required: true
            schema:
              type: string
          - name: target
            in: query
            required: true
            schema:
              type: string
        responses:
          '204':
            description: Link removed

warning

Tool support is critical here. Many existing generators, validators, and UI tools may ignore or reject these operations until they update for 3.2. If you plan to use additionalOperations, make sure your toolchain supports it.

3. Sequential / Streaming Media Types

Modern APIs often deliver a sequence of items instead of a single payload – for example, event streams or log lines. OpenAPI 3.2 adds first-class support for streaming media types, such as:

• text/event-stream (Server-Sent Events)
• application/json-seq
• application/jsonl
• multipart/mixed

You can use the new itemSchema keyword to describe the type of each element in the stream.

Example:

paths:
  /events:
    get:
      responses:
        '200':
          description: Event stream
          content:
            text/event-stream:
              itemSchema:
                type: object
                properties:
                  eventType:
                    type: string
                  data:
                    type: object

This makes OpenAPI a lot more useful for event-driven architectures.

4. Richer Tags

Tags are now more powerful:

• parent: build tag hierarchies
• kind: categorize tags (e.g. navigation vs. audience)
• summary: a short description

Example:

tags:
  - name: users
    summary: User operations
    kind: nav
  - name: users/admin
    parent: users
    summary: Admin-specific operations
    kind: audience

This helps generate better navigation and grouping in documentation tools.

5. Improved Examples

The Example Object now distinguishes between:

• dataValue – structured example data
• serializedValue – the exact on-the-wire representation

Example:

components:
  examples:
    userExample:
      summary: User object
      dataValue:
        id: 123
        name: Alice
      serializedValue: '{"id":123,"name":"Alice"}'

This avoids confusion when serialization formats matter.

Other Notable Changes

Beyond the headline features, OpenAPI 3.2 also brings:

• XML Enhancements: new nodeType field; deprecation of attribute: true and wrapped: true
• Query String as a whole: new in: querystring parameter location
• Security Schemes: Device Authorization Flow for OAuth2, oauth2MetadataUrl´, deprecated` flag
• Response Objects: description is now optional; new summary field
• Reusable Media Types: components/mediaTypes for reusing Media Type Objects

See the full OpenAPI 3.2.0 specification

Migration Notes

• Backward compatibility: Almost all valid 3.1 documents remain valid in 3.2.
• Tool support: Many tools will need time to catch up with features like additionalOperations or itemSchema. Before adopting them, verify that your validators, code generators, and documentation tools support 3.2.
• Incremental adoption: You can start using the new features gradually – e.g. richer examples or tag hierarchies – without breaking compatibility.

Conclusion

OpenAPI 3.2 is not a radical change, but it makes the specification more precise and more powerful.

• The formal path templating rules will improve validation.
• The new additionalOperations keyword finally allows describing non-standard HTTP verbs.
• Streaming support makes event-driven APIs first-class citizens in OpenAPI.
• Documentation gets better with hierarchical tags and richer examples.

If you’re starting a new API, I recommend going directly with 3.2. For existing APIs, you can migrate gradually – just make sure your toolchain supports the features you want to use.