Zum Hauptinhalt springen

OpenAPI Specification 3.2 Released – What’s New?

· 5 Minuten Lesezeit

Grid banner

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
warnung

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.