OpenAPI 3.2 - What to expect?

Tech

07/22/2025

Jay Cormier

2 minutes read

In this article

With growing adoption and undeniable strengths, OpenAPI continues to evolve, and version 3.2 is set to be released in the coming weeks. What can we expect in terms of new features? Should we be preparing for compatibility issues?

Let’s take a quick look together.

Where Are We Coming From?

Let’s start with version 3.1, which was more significant than it may seem.

Released in 2021, OpenAPI 3.1 was a major update marking the convergence between OpenAPI and JSON Schema (thanks to full compatibility with JSON Schema 2020-12). This helped reduce the friction often encountered when editing or sharing API schemas. It also brought greater flexibility and clarity. For instance, $ref now generally behaves in line with JSON Schema, and the new contentEncoding and contentMediaType help cover more complicated use cases around file uploads and mixed content payloads than were possible before.

Version 3.1 also improved support for asynchronous APIs via webhooks, for which you can now find many guides to help you get started.

This version laid a unified, modern foundation, and more importantly, set the stage for the future of OpenAPI, creating a solid base for its upcoming iterations. This improvement came with the price of minor backwards compatibility breaks, so will OpenAPI v3.2 do the same?

What’s New in OpenAPI 3.2?

Thankfully OpenAPI 3.2 is fully backwards compatible with OpenAPI v3.1, and whilst it’s only a minor update it brings a lot of useful improvements that have been requested by the OpenAPI community. Here are a few of the upcoming changes:

  • OAuth 2.0 Device Authorization Grant: Allow a new OAuth 2.0 flow “Device Authorization Grant” as defined by RFC 8628, which adds flows.deviceAuthorization with the following required fields (and any other other flow fields allowed).
  • Deprecate Security Schemes: Declares this security scheme to be deprecated, to let consumers know they should avoid using it if possible.
  • Tag Summary: Tags can now have a short summary of the tag, used for display purposes, replacing the need for historical vendor extensions like x-displayName.
  • Support for all HTTP methods: Including not yet standardized ones like QUERY, old WebDev methods like COPY, or any custom HTTP methods.
  • JSON Streaming: Official support for sequential JSON formats (e.g.: RFC 7464: JSON Sequences, JSON Lines, NDJSON).
  • Other enhancements: Improvements to security definitions, examples, support for new media types, and more.

OpenAPI 3.2 is expected to be released sometime this summer (estimated August), and we’ll have guides ready to help you adopt it smoothly.

In the meantime, you can already check out our complete guide to OpenAPI 3.1 or our best practices for API Governance using OpenAPI Specification.

Share this article

Related articles

We think you might like these articles too.

What is OpenAPI?

OpenAPI is a standard for describing APIs (Application Programming Interfaces). The OpenAPI specification (or OAS) defines an open and independent description format for API services and allows both humans and computers to discover and understand how an API works and how to interact with it, without the need to look at the source code. More specifically, OpenAPI allows to describe, develop, test, and document APIs conforming to the REST architecture, to create RESTful APIs.

OpenAPI

01/13/2022

How to prepare for your API documentation revamp?

There are many reasons that might lead you to undertake a full overhaul of your API documentation. It may stem from an audit that reveals errors, or even complete omissions. Maybe the API docs need better integration with other existing documentation, and perhaps there’s been some user feedback or a growing number of support tickets… If you’re interested in the question of why you should consider a documentation overhaul, we actually have a dedicated article waiting for you.

Tech

08/05/2025

OpenAPI 3.1 - The Cheat Sheet

We can’t tell you how stoked we are about this. It’s been a while that we realized something key was missing, to help the entire community adopt and use OpenAPI daily.

Tech

09/16/2024