The OpenAPI spec has always been a careful evolution, not a revolution. Each release nudges things forward without breaking what’s already working. Version 3.2 continues that tradition - it’s incremental, compatible with 3.1, but still meaningful in the ways that matter most to developers, docs teams, and tool builders.

So, what’s changing? And what will it mean for the way we design and document APIs?

A Quick Overview of What’s New

Here are the highlights you’ll notice when 3.2 lands:

1. OAuth device flow support

You can now properly describe device authorisation flows. The spec also adds new metadata fields for OAuth 2 servers and marks a few older OAuth flows as deprecated.

➡️ This means cleaner, more accurate auth documentation and better generator support for modern login patterns.

2. Structured tags

Tags in 3.2 can be hierarchical, not just a flat list. You’ll be able to group operations under categories, subdomains, or even business units.

➡️ Expect to see better grouping in tools like DeveloperHub - fewer long scrolls, more structure.

Further reading: Structured Tags in OpenAPI 3.2: Organising APIs the Way They Deserve

3. A new “QUERY” HTTP method

OpenAPI is adding support for the QUERY method alongside the usual GET/POST/PUT. It’s mostly for APIs that expose custom, read-only search endpoints.

➡️ This brings a few niche APIs out of the “custom extension” shadows and into proper, spec-supported territory.

Further reading: The New QUERY Method in OpenAPI 3.2: A Small Addition That Clears Up a Big Ambiguity

4. Better multipart handling

Multipart/form-data definitions are now clearer, especially when you’re mixing file uploads with structured metadata.

➡️ If you’ve ever struggled to describe an endpoint that uploads an image plus a JSON blob of details, this one’s for you.

5. Event streams and real-time patterns

The spec now acknowledges streaming APIs like server-sent events, as first-class citizens.

➡️ Tooling can start generating and validating them instead of treating streams as weird one-off hacks.

Further reading: Event streaming in OpenAPI 3.2: What changed and why it matters

Why This Release Feels Different

OpenAPI 3.2 isn’t flashy but it’s pragmatic. It focuses on the real pain points that show up when you scale: messy docs, patchy auth support, and unclear streaming behavior.

Here’s what that means in practice:

  • Cleaner documentation: Hierarchical tags make large APIs actually browsable.
  • Smarter SDKs: Code generators can finally infer correct flows for device-based logins.
  • More predictable testing: Validators understand streaming and multipart payloads instead of ignoring them.
  • Low-risk adoption: Everything is still compatible with 3.1. You can move gradually, feature by feature.

It’s the kind of release that quietly improves your workflow without demanding a rewrite.

A Simple Upgrade Path

Migrating to 3.2 should be painless:

  1. Update your OpenAPI toolchain (linters, generators, validators).
  2. Change the version number in your spec to openapi: 3.2.0.
  3. Start using new features as you need them — nested tags, device flows, multipart fixes.
  4. Validate your specs early in CI to make sure your tools all agree.

Because 3.2 is a compatible update, you can introduce new patterns gradually while your existing specs keep working.

Looking Ahead: The Road to 4.0 (“Moonwalk”)

3.2 also lays groundwork for the future. The OpenAPI community is already experimenting with 3.3 and the bigger 4.0 (Moonwalk) release, which aims to simplify nested structures, improve parameter-based responses, and extend support beyond REST.

Think of 3.2 as a safe stepping stone: you get a few of the next-gen ideas today, without waiting for the big version bump.

Final Thoughts

If you live in API specs all day, this update is worth your attention. You’ll spend less time fighting your documentation tools and more time focusing on the design itself.

In short:

✅ Better structure

✅ Better auth support

✅ Better file and stream handling

✅ Zero breaking changes

It’s the kind of quiet progress that keeps the OpenAPI ecosystem healthy — and keeps your documentation future-proof.

Read the full specification here: https://spec.openapis.org/oas/v3.2.0.html