As of September 2026, OpenAPI 3.2 support is uneven: Swagger's tooling suite (Swagger UI, Swagger Client, Swagger Editor, ApiDOM) and Redocly's suite (linting, rendering, code samples, mock server) both support it, Spectral has schema-level support merged but not yet in every stable release, and OpenAPI Generator — the generator most teams use for non-TypeScript/Python SDKs — has no 3.2 support as of this writing, with an open feature request and no committed timeline. The default advice hasn't changed from any prior OpenAPI version jump: stay on 3.1 for anything you publish until every tool in your chain says yes, and check each tool directly rather than assuming "reads 3.1" means "reads 3.2."
OpenAPI 3.2.0 was published by the OpenAPI Initiative on 2025-09-19, a year before this post. That's enough time for some tools to ship support and not others — which is exactly the gap this page tracks.
What's new in OpenAPI 3.2
The 3.2.0 specification is a backward-compatible minor release on top of 3.1. The changes that affect tooling support most:
$self— an optional field giving a document its own base URI, for resolving references across multi-document OpenAPI descriptions.queryHTTP method — a new operation type for the IETF-drafted QUERY method (a safe method that carries a request body).additionalOperations— a map for HTTP methods beyond the standard set.in: "querystring"parameters — a parameter location covering the entire URL query string as one value via thecontentfield.- Reusable
pathItemsandmediaTypesincomponents— composition for path items and media types, not just schemas. - Structured tags —
summary,parent, andkindfields on tags, replacing vendor extensions likex-displayNameandx-tagGroupsthat docs tools invented to fill the gap. - Streaming media type support —
itemSchema,prefixEncoding, and sequential media type guidance, aimed at making SSE, JSON Lines, and MCP-style channels first-class in the spec. - OAuth 2.0 Device Authorization Flow — a new
deviceAuthorizationfield in the OAuth Flows Object.
Any of these can trip up a tool that only validates against the 3.1 JSON Schema dialect, even if the rest of your document parses fine — that's the practical risk of moving early.
Support matrix (checked September 2026)
| Tool | Category | 3.2 status | Source |
|---|---|---|---|
| Swagger UI / Swagger Client / Swagger Editor / ApiDOM | Docs / validation | Supported — SmartBear says Swagger is "the first open-source tooling suite to ship support for OpenAPI 3.2.0" | Swagger blog |
| Redocly (Redoc, Redocly CLI, Respect, mock server) | Docs / linting / mocking | Supported — "Redocly fully supports OpenAPI 3.2 — linting, rendering, code samples, mock server, Respect" | Redocly blog |
| Spectral | Linting | Partial — the 3.2 JSON Schema bundle and format detection are merged to the develop branch; operation-level rules for query and additionalOperations are not complete yet |
Spectral PR #2917, PR #3033 |
| OpenAPI Generator | SDK generation | Not supported — open feature request, no maintainer timeline as of this writing | Issue #22728 |
| Kiota | SDK generation | Unconfirmed — no evidence of a shipped 3.2 support announcement found as of this writing; verify directly against your spec before relying on it | Kiota releases |
| Sourced | Docs / validation / SDK generation | Reads 3.0 and 3.1 today; 3.2-specific handling not yet confirmed — verify against your own spec via a free preview before depending on it | Sourced |
Where this table says "unconfirmed" or doesn't list a tool, that's a gap in what's publicly documented as of this writing, not a claim either way — check the tool's own changelog or issue tracker before you commit a spec to 3.2.
The go/no-go checklist
Before moving a spec to 3.2, confirm every tool in your actual pipeline — not just the ones in the table above:
- Validator — does it accept a 3.2
openapi:version line without falling back to 3.1 rules silently? A validator that "passes" a 3.2 spec by ignoring the parts it doesn't understand is worse than one that rejects it outright. - SDK generator(s) — for every language you ship, check that specific generator's issue tracker or changelog for 3.2, not just "does it support 3.1." As the matrix above shows, 3.1 support does not predict 3.2 support.
- Docs renderer — confirm it renders the specific 3.2 features your spec actually uses (structured tags, streaming media types, the
querymethod) rather than just "loads without an error." - CI linting (Spectral or similar) — check whether your ruleset's 3.2 schema is in a released version, not just merged to a development branch.
- Anything downstream that parses your spec — internal tooling, a partner's import step, a gateway's OpenAPI ingestion — these rarely show up in a public support matrix at all, so ask directly.
If any answer is "not yet" or "unconfirmed," stay on 3.1. The JSON Schema 2020-12 alignment that makes 3.1 worth using is untouched by 3.2 — you lose nothing meaningful by waiting, and 3.2's changes (webhooks refinements, the query method, structured tags) are additive, not fixes to something broken in 3.1.
What to do this week
- Check your specific generator, validator, and docs tool against their own changelogs or issue trackers — this matrix will go stale faster than most pages on this topic, precisely because tool support is actively shipping.
- If you're not using any 3.2-only feature yet, there's no reason to bump the version line. Staying on 3.1 costs you nothing.
- If a specific 3.2 feature (streaming media types, the
querymethod) is something you need today, test your full pipeline against a throwaway spec before touching a production document. - Run your spec through the OpenAPI validator regardless of version — catching a malformed spec before codegen saves more time than any version decision.
FAQ
Is OpenAPI 3.2 backward compatible with 3.1?
Yes. The 3.2.0 spec states tooling supporting OAS 3.1 "SHOULD be compatible with all OAS 3.1.* versions," and 3.2 is designed as an additive minor release on the same JSON Schema 2020-12 foundation as 3.1 — it doesn't remove or redefine anything 3.1 introduced.
Should I move my spec to 3.2 now?
Only if every tool in your actual pipeline confirms 3.2 support and you specifically need a 3.2-only feature. As of September 2026, OpenAPI Generator — the tool behind most non-TypeScript/Python SDK generation — has no 3.2 support, which rules out 3.2 today for a lot of multi-language teams regardless of what your validator or docs tool supports.
Does OpenAPI 3.1 vs 3.0 advice still apply if I'm considering 3.2?
Yes — see OpenAPI 3.1 vs 3.0: which to use in 2026 for that comparison. The practical rule carries forward: use the newest version your entire toolchain actually supports, not the newest version that exists.
What's the single biggest 3.2 feature for API teams building for AI agents?
The streaming media type support — itemSchema, prefixEncoding, and sequential media type guidance — is aimed directly at SSE, JSON Lines, and MCP-style channels, which is relevant if you're generating an MCP server or documenting a streaming endpoint. It's also one of the features tool support is thinnest for right now, so test it specifically rather than assuming it works because the rest of your spec validates.
Does a validator that "loads" a 3.2 spec mean it fully supports 3.2?
Not necessarily. Some tools accept a spec by falling back to 3.1-era parsing for anything they don't recognize, which can silently ignore new 3.2 fields like $self or structured tags rather than erroring on them. Check the tool's changelog for an explicit 3.2 support statement, not just "it didn't crash."
Does Sourced validate OpenAPI 3.2 specs?
Sourced reads OpenAPI 3.0 and 3.1 today; full 3.2-specific handling isn't confirmed as of this writing. Run your spec through the validator to check its current behavior against your document directly.
Create hosted docs from your repo or start free — unlimited OpenAPI previews, no credit card required, and the fastest way to see how your spec actually behaves against current tooling.