Go OpenAPI 3.2 (upgrade initiative)

[lornajane]

We recognise that many OpenAPI users experience difficult upgrade experiences and roadblocks along the way. Let's identify those roadblocks and discuss ways that we can help users to get past them by fixing tools, providing resources, socialising alternative approaches, or lobbying for change.

[lornajane]

From TDC Call:

VSCode doesn't support JSONSchema 2020-12 and there are some related issues:

• Support JSON schema draft 2020-12 microsoft/vscode#251315 (comment)
• [json] Support json-schema draft 2020-12 microsoft/vscode#165219 (comment)
• Intellisense is missing JSON Schema versions 2019-09, 2020-12 microsoft/vscode-json-languageservice#208
• Autocompletion doesn't work with 2020-12 schema for sub levels microsoft/vscode-json-languageservice#179
• Partial JSON Schema 2020-12 support results in failuer to highlight invalid schema features? microsoft/vscode-json-languageservice#149

Microsoft folks, what can we do here?

[handrews]

@baywet given Microsoft's interest in code generation, I would emphasize the use case of modeling generics. I also recall that MS has some large-scale multi-document descriptions. If I'm remembering that correctly, you might want to point out that proper $id support allows much more flexible configuration for loading and (perhaps even more importantly, with schemas) bundling multiple documents.

[handrews]

@baywet Some of your comments make me think you're focusing on the openapi schema (the schema that describes OADs). While that is a critical use case that is not currently supported at all, it is even more about being able to write 2020-12 schemas for use in OADs.

[baywet]

@baywet Some of your comments make me think you're focusing on the openapi schema (the schema that describes OADs). While that is a critical use case that is not currently supported at all, it is even more about being able to write 2020-12 schemas for use in OADs.

Yes, that was the main angle I was coming at this initially. I now understand there's also the use case of "people using dynamicRef in their OADs, or directly in JSON schema" (as stated in my earlier comment quoted below). Thank you for clarifying.

Now the question is do we need that for our own schema? If not, the limitation would only be for descriptions that make use of this.

To answer the question here (now that I have access to a computer), this schema (which defines the structure of OADs), makes use of dynamicRef.

I also recall that MS has some large-scale multi-document descriptions

Yes, that was a HUGE use case for my previous team (Microsoft Graph). That API supports paging all over the place. And as of now, we have model definition for each page type (Page of User, Page of Files, Page of Emails....), but the only thing that varies here is the type of the "value" property (which is an array of the would-be generic type). We shaved some bytes in the SDKs by hoisting all the common properties in a base model, but still, using generics where possible would go a long way to reduce the SDKs size.
I suspect Azure also faces something similar. Of course, the support for dynamicRef is only the first step here, more infrastructure work would be required to enable scenarios like these.

[handrews]

To answer the question here (now that I have access to a computer), this schema (which defines the structure of OADs), makes use of dynamicRef.

Yes, anytime you need to extend a recursive schema, such as the metaschema (to add our own extra vocabulary), you use $dynamicAnchor and $dynamicRef. And because of how that works, our main OAD schema needs to use a $dynamicRef to reference the Schema Object's schema (which is a JSON Schema metaschema).

[handrews]

@baywet as you've no doubt already realized, this is probably your strongest argument as you can make it a net cost-savings for Microsoft overall. Give a bit of budget to VSCode and save lots of budget elsewhere:

We shaved some bytes in the SDKs by hoisting all the common properties in a base model, but still, using generics where possible would go a long way to reduce the SDKs size.
I suspect Azure also faces something similar. Of course, the support for dynamicRef is only the first step here, more infrastructure work would be required to enable scenarios like these.

While $dynamicRef support is only the first step, it is the one that unblocks all possibilities. And since you need $dynamicAnchor support, supporting $anchor is even easier (it's a subset of $dynamicAnchor's capabilities) and $id is pretty easy as well (as with $dynamicAnchor, you need to know if you found it in another schema document; unlike with $dynamicAnchor, though, it might be in a schema document you know about but haven't parsed yet).

[lornajane]

AWS Gateway only supports OpenAPI 3.0

[jeremyfiel]

These are very relevant for 2020-12.

microsoft/vscode-json-languageservice#295

Meager attempt to support flattened schemas without $dynamicRef.

microsoft/vscode-json-languageservice#224

[jeremyfiel]

@handrews AWS should just support 3.1+ with their own dialect. At least it would be extensible to add OAS features as they adopt them.

[lornajane]

Yes I mean that we flip the script around from teams that can't upgrade until all tools are ready to upgrading to a new standard with new tools as available - and then dumbing back down for stuff that's lagging.

[lornajane]

@baywet can you show us an example of doing this? Maybe we can put it on a learn site page or something.

[baywet]

Sorry, I should have included the documentation link.
The transform operation is the one you want to try.

https://github.com/microsoft/openapi.net/blob/main/src%2FMicrosoft.OpenApi.Hidi%2Freadme.md

Let me know if you have any other questions.

(Writing from my phone)

[jeremyfiel]

some welcome updates from Google, although I can't find any information or posts where they announced support for OAS 3.0.x. Previously, they only supported Swagger 2.0 as recent as last year

This page was updated on Nov 11, 2025

https://docs.cloud.google.com/api-gateway/docs/openapi-overview

[handrews]

@jeremyfiel so... they finally reached 3.0, most of a decade after its release, nearly half a decade after 3.1's release, and possibly even a couple months after 3.2's release. 🤦 I guess it is progress, but... ugh, why even invest in 3.0 in 2025?

[lornajane]

Down-convert recommendation from them as well. I don't know why it's the API gateways that are getting left behind, don't they need the new security features?

[karenetheridge]

We might want to change the name of this initiative to make it clear that this has nothing to do with Go the programming language? :)

[lornajane]

Naming things is hard!

[lornajane]

"Go Go Go OpenAPI 3.2" ? We might need to workshop this 😆

[handrews]

Improving tooling support for multi-document OADs by advertising 3.2's $self

One thing to consider is lack of support in many (most?) tools for multi-document OADs, which has historically had good reasons, but these have been fixed in 3.2. Lack of support for this is a huge problem for large-scale OAS users.

To support multi-document OADs, you need to:

1. Know where you are, in order to resolve relative references
2. Be able to access referenced locations

In 2.0 and 3.0, and also 3.1 unless you were really good at understanding the implications of JSON Schema's ` $id (which most people are not, if they even realized it was relevant) and added the ability to assign a URI to a document (which a few tools did), these things were hard.

If you are in some sort of cloud environment where the uploaded document location is opaque, you can't do either of these things. And there are many performance, security, and network topology reasons why the second might be impossible or impractical.

We should push for tools to add multi-document support when they add 3.2 support, at least when $self and $id are used to enable identity-based resolution. Most modern JSON Schema implementations support this, and correctly do not perform disk or network I/O by default.

Formats such as JSON Lines (or YAML's native document stream feature) make bundling such multi-document OADs easy (unless you have non-JSON examples/external docs, but there are solutions for that, too).

[lornajane]

How can we identify which tools would be open to improving their story on that, and help them to do so? There's a really strong story about using this feature to have shared libraries of components that can be used by everything else - how can we socialise this and make it achievable? Redocly has something that worked with the older versions of OpenAPI, and JSONSchema has good bundling instructions - could we do something similar that people could use?

[lornajane]

Having smaller pieces of OpenAPI description, even without the reusability, makes for an easier life with reviewing and maintaining potentially very long OpenAPI descriptions where source control platforms may not handle the diff.

[handrews]

@lornajane we could host a registry (like a package management server) of useful components?

The Open Geospatial Consortium wants to publish OAS components — they were one of the motivations for getting this into 3.2, since they gave me a real-world use case to point to. Standards organizations are a good candidate in general here, because they are trying to describe ways to design APIs without building APIs of their own.

[lornajane]

This is pretty interesting to me as I'm now in standards as a day job! Are there some examples already? Does it make sense for us to maintain registries or link to others?

[lornajane]

Tools makes tell us that their users don't care about upgrades and don't ask. Users tell us they can't consider upgrading because the tools don't offer support but they wish they did. How can we help connect the groups to make change?

[handrews]

@lornajane I'm wondering if we might want to theme this more around LLMs/AI. I'm envisioning a cute cartoon character LLM demanding 3.2 support.

This isn't just because AI is the buzz right now. I've heard a lot about how 3.2 addresses things that LLM APIs need. At least one person described 3.2 as "catching up to where APIs are now." So I think there's a real connection, if we go and look at LLM APIs and use cases.

And, more practically, LLMs are where the money is right now. If we make the case that LLM integration requires 3.2, there's actual money attached to that requirement.

[lornajane]

I am not sure about the AI angle as an overall thing - good APIs are good for everything including non-vibe actual tech use cases and I think we might turn off people with hype fatigue. Definitely worth including some good practice content and docs around the topic though, some of it seems like common sense but it really isn't all that common ....

[handrews]

@lornajane

some of it seems like common sense but it really isn't all that common ....

Words of wisdom! And yeah, good point that we don't want to make it all about AI. I'm just trying to think of what would get implementors to think "this is worth it for my bottom line." Which is, as you no doubt know better than I, is a very different proposition than getting users to think "this is a feature I want."

[lornajane]

If the raft of features in 3.1 and 3.2 isn't enough, I'm not sure what is!

[handrews]

@lornajane

If the raft of features in 3.1 and 3.2 isn't enough, I'm not sure what is!

Which I think brings us back to tying use cases for new features to potential revenue for vendors. How do we show vendors that there are untapped markets that would be unlocked by 3.2 support? Including 3.1 support, but let's just frame it as 3.2 for simplicity- with JSON Schema, we found it helpful to sometimes downplay a release (draft-06 and 2019-09) that was superseded by a (more or less) compatible better release before the older draft was widely implemented (draft-07 and 2020-12, respectively).

[lornajane]

Helping to surface the tools that are available and news about existing tools getting upgrades might be useful - I saw some chat in slack about https://openapi.tools and definitely think we could be contributors to that site as well as generating some content to round up what's available - lots of users checked once to see if they could upgrade and may not realise they can NOW.

[handrews]

We could also contribute to our own tools site... unless we want to stop having one and just go with openapis.tools?

[lornajane]

One thing that has caught me in the past is that the 3.0 to >=3.1 upgrade is that those tools were mostly created at the time that 3.1 was released, and many are no longer actively maintained or may have out of date dependencies. Does anyone have a favourite tool to recommend TODAY for upgrading an existing 3.0 description? I think from 3.1 you don't really need a tool for 3.2 .... but happy to have recommendations on that too.

[lornajane]

I don't think we're adding much value with our own tools site and always recommend openapi.tools because it's curated - but there's a LOT there, and it's awkward because most vendors are members as well and I don't want to show favourites!! I'm not sure what is best here.

[lornajane]

I also asked openapi.tools if they could try to hide the pre-3.1 support tools from their main view: apisyouwonthate/openapi.tools#624

[handrews]

I feel much the same way about the tools site. It looks nice, but we don't have the resources to curate it properly, and that feels more suited to a community project. Also agree with using the site design (of whichever site) to heavily promote 3.1+ tools. When I was part of the JSON Schema effort, I split the tools page so that anything that did not support at least (whatever the not-quite-current-draft was at the time, I forget) got put on an "obsolete implementations page." We were trying very hard to kill off draft-04 at the time, and I think that helped (the center of gravity has long since moved to draft-07, with VSCode being the main reason it's not move up to 2020-12 by now).

[lornajane]

I hear reports of OpenAPI Generator being a blocking factor, and it does look like they still don't support 3.1 even. There's a (now locked) issue conversation: OpenAPITools/openapi-generator#9083 and a list of tagged issues to track individual aspects: https://github.com/OpenAPITools/openapi-generator/issues?q=state%3Aopen%20label%3A%22Feature%3A%20OAS%203.1.0%20spec%20support%22 - we may need to reach out to this project to see if they would accept any help and connect them with helpers?

[Thebutlersguilty3]

Based on the thread, here are the stated limitations and current support levels for OpenAPI by the major API gateway vendors mentioned: - *AWS Gateway:* - *REST APIs:* Support OpenAPI 3.0 and Swagger 2.0. - *Limitations:* The support comes with a long list of exceptions and limitations, including the use of standard JSON Schema draft-04 instead of the OAS's superset-subset, and a limitation on only being able to use object schemas in response roots. Henry Andrews noted that AWS has essentially created its own version of OpenAPI that is not compatible with anything else. - *HTTP APIs:* Support OpenAPI 3.0. - *Overall:* They only support up to OpenAPI 3.0. - *Azure API Management:* - *Current Support:* Supports OpenAPI 2 through 3.0.3 for import and export, and OpenAPI *3.1.0 only for import.* - *Limitation:* They are on an older version of the underlying Microsoft.OpenAPI library, but are expected to support up to 3.2.0 once they upgrade the library to version 3.X. - *Google Cloud's API Gateway:* - *Current Support:* Has recently reached support for *OpenAPI 3.0.x* (updated on November 11, 2025). - *Limitation:* This update comes nearly half a decade after 3.1's release, and possibly after 3.2's release, making the adoption significantly delayed.

…

On Fri, Dec 5, 2025 at 3:08 PM Henry Andrews ***@***.***> wrote: @baywet <https://github.com/baywet> as you've no doubt already realized, this is probably your strongest argument as you can make it a net cost-savings for Microsoft overall. Give a bit of budget to VSCode and save lots of budget elsewhere: We shaved some bytes in the SDKs by hoisting all the common properties in a base model, but still, using generics where possible would go a long way to reduce the SDKs size. I suspect Azure also faces something similar. Of course, the support for dynamicRef is only the first step here, more infrastructure work would be required to enable scenarios like these. While $dynamicRef support is only the first step, it is the one that unblocks all possibilities. And since you need $dynamicAnchor support, supporting $anchor is even easier (it's a subset of $dynamicAnchor's capabilities) and $id is pretty easy as well (as with $dynamicAnchor, you need to know if you found it in another schema document; unlike with $dynamicAnchor, though, it might be in a schema document you know about but haven't parsed yet). — Reply to this email directly, view it on GitHub <#5130 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AWLW4QKDWIHHP7YJ2TPLA5T4AHQ4BAVCNFSM6AAAAACMXESLRSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMJXGYYTMOI> . You are receiving this because you are subscribed to this thread.Message ID: <OAI/OpenAPI-Specification/repo-discussions/5130/comments/15176169@ github.com>