What is the Latest Version of the OpenAPI Specification? #

OpenAPI Specification (OAS) has established itself as the cornerstone for API documentation, standardization, and adherence to best practices. Teams around the world leverage OpenAPI to define interfaces, automate processes, and ensure consistency across systems. As APIs continue to evolve, the OpenAPI Specification must also progress to reflect new needs and technological advancements. So, what is the latest version of the OpenAPI Specification, and what does it bring to the table?

The Latest Version: OpenAPI Specification 3.2.0 #

As of 2026, the latest version of the OpenAPI Specification is 3.2.0, released on September 19, 2025. It is a minor, backward-compatible release on the 3.x line — every valid 3.0 or 3.1 document remains meaningful under 3.2 — but it adds a substantial set of new fields and capabilities aimed at modern API patterns like streaming, richer tagging, and additional authentication flows.

Alongside 3.2.0, the OpenAPI Initiative (OAI) also published 3.1.2 (an editorial-only patch to the 3.1 line, with no material behavior changes) on the same day. The most recent 3.0.x patch is 3.0.4, released October 24, 2024.

Key Features New in OpenAPI 3.2.0 #

1. Multipurpose, Nested Tags #

The Tag Object gains a summary field, a parent field (to nest tags under other tags), and a kind field to classify a tag’s purpose (for example, nav for navigation groupings versus tags used to indicate an audience). A companion tag-kind registry establishes conventional values for kind.

2. Additional HTTP Methods #

Beyond the existing get/post/put/delete/options/head/patch/trace, OAS 3.2 adds first-class support for the query method, plus an additionalOperations map on the Path Item Object for any other HTTP method (such as LINK) that isn’t already a named key.

3. Document Identity with $self #

A new top-level $self field lets a document declare its own base URI, which is used to resolve relative references. This makes OpenAPI documents self-identifying — useful when a document is split across files or served from different locations.

4. Streaming and Server-Sent Events (SSE) #

OAS 3.2 formally supports sequential media types such as text/event-stream (SSE), multipart/mixed, application/jsonl, and application/json-seq. A response can now be described as a repeating stream of items using the new itemSchema field in a Media Type Object.

responses:
  '200':
    description: A stream of stock price updates
    content:
      text/event-stream:
        itemSchema:
          $ref: '#/components/schemas/StockUpdate'

5. querystring Parameter Location and Cookie Style #

A new parameter location, querystring, allows the entire query string to be parsed as a single field (using content), similar to how request bodies are handled. A new cookie style value is also available for parameters and headers, matching how browsers format cookie values.

6. Multipart Media Type Improvements #

New prefixEncoding and itemEncoding fields give finer-grained control over encoding for multipart media types, alongside the new itemSchema field for describing each part.

7. XML Modeling with nodeType #

The Schema Object’s xml keyword gains a nodeType field (element, attribute, text, cdata, or none), replacing the old boolean attribute and wrapped fields (both now deprecated, though still supported for backward compatibility).

8. Structured and Serialized Examples #

The Example Object adds dataValue (the example in structured/native form) and serializedValue (how the example looks once serialized on the wire), giving a clearer distinction than the previous single value field alone.

9. Security Scheme Enhancements #

• Support for the OAuth2 Device Authorization flow, via a new deviceAuthorizationUrl field.
• A new oauth2MetadataUrl field for pointing to an OAuth2 Authorization Server Metadata document.
• Security schemes can now be marked deprecated, and can be referenced by URI instead of only being declared inline under components.

10. Smaller but Notable Additions #

• The Server Object gains a name field, and server URL variable substitution now has a formal ABNF grammar.
• The discriminator’s propertyName is now optional, with a new defaultMapping field for the fallback schema.
• Response description is now optional, and a new summary field is available on responses.
• A new mediaTypes entry under components allows reusable Media Type Objects.

How 3.2 Relates to OpenAPI 4.0 (“Moonwalk”) #

Some of these additions — most notably the tag improvements and the $self field — originated as explorations in the OpenAPI Moonwalk initiative, the OAI’s effort to design OpenAPI 4.0. Because they were backward-compatible, the working group brought them into the 3.x line early rather than waiting for a future major release. Moonwalk/4.0 itself remains in active, open-ended design work with no fixed release date, so 3.2 is the version to adopt today.

Migration from Previous Versions #

Upgrading from OAS 3.0.x or 3.1.x to 3.2.0 is straightforward, since 3.2 is fully backward-compatible — no existing valid document becomes invalid. To take advantage of the new version, though, it’s worth reviewing your toolchain:

1. Check tooling support: Confirm that your parsers, linters, and code generators have added 3.2 support before relying on 3.2-only fields like $self, itemSchema, or additionalOperations.
2. Adopt tag nesting incrementally: The new parent/kind/summary tag fields are additive — you can adopt them gradually without restructuring existing tags.
3. Consider streaming support: If your API already uses SSE or newline-delimited JSON informally, migrating those responses to use itemSchema gives consumers a formally documented shape.
4. Review deprecated XML fields: Replace attribute: true and wrapped: true with the new nodeType field where your tooling supports it.
5. Bump the openapi field: Set openapi: 3.2.0 once your document is validated against the new version.

Tools and Ecosystem Support #

Tooling support for 3.2.0 is still rolling out across the ecosystem (as is typical immediately after a spec release), while 3.1.x and 3.0.x support is mature and universal:

• Swagger: Swagger Editor and Swagger UI support OAS 3.0 and 3.1 broadly, with 3.2 support landing incrementally.
• Redocly CLI and ReDoc: Actively tracking new OAS releases, including 3.2 fields.
• Postman: Supports importing and working with OAS 3.0 and 3.1 definitions, with 3.2 support following the spec’s adoption curve.

Because 3.2 is additive, tools that only understand 3.0/3.1 will typically still handle a 3.2 document reasonably well for the fields they recognize — just without the new capabilities.

Conclusion #

The OpenAPI Specification 3.2.0 is the current latest version, building on 3.1’s full JSON Schema alignment with practical additions for streaming APIs, richer tag organization, self-describing documents, and expanded authentication flows — all while remaining backward-compatible with existing 3.0.x and 3.1.x documents. Meanwhile, the OpenAPI 4.0 (“Moonwalk”) initiative continues its longer-term, open-ended redesign work, with select ideas continuing to be backported into the 3.x line where possible.

For more details on the OpenAPI Specification and the latest updates, visit the OpenAPI Initiative or check the release notes on GitHub.

Last updated on August 12, 2026.