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?

[baywet]

I can't talk to all of Microsoft, I'm a tiny developer in a tiny team part of this big enterprise :)
But using the latest stable version of vscode (1.106.2) the support for JSON schema 2020-12 seems to be working as expected.
Judging by those two PRs:

• use flat 2019-09 and 2020-12 schemas microsoft/vscode-json-languageservice#295
• include bundled schemas 2020-12 & 2019-09 microsoft/vscode-json-languageservice#294

It seems this was added 3 weeks ago. I have reached out to @aeschli the author internally to get a better sense of what's going on here (if the feature is complete, the issues should have been closed). And will report back.

[handrews]

I can't talk to all of Microsoft, I'm a tiny developer in a tiny team part of this big enterprise :)

Now I have this cartoon visual of chibi-Vincent climbing around an org chart like a jungle gym, trying to find the right team, stuck in my head 🤣 (@baywet I spent the majority of my career in large or rapidly growing enterprise software companies, I know what you mean).

---

Anyway... based on comments in an issue that I just commented on but cannot find for the life of me right now, I think that PR 294 is removing $dynamicRef so that they don't have to support it, not actually fixing the problem.

[handrews]

From that comment I can't find, it seems to also be related to the mistaken assumption that resolving $ref and $dynamicRef should involve a network operation, when in fact it SHOULD NOT as that's a horrible performance problem and a gaping, egregious security hole.

[baywet]

Yes... it does feel like running around to find the right person in the organization. Thankfully (or not for my health maybe?) we now have teams...
Thank you for the additional information. Let's see what @aeschli comes back with (either here, or internally)

[lornajane]

AWS Gateway only supports OpenAPI 3.0

[baywet]

FWIW openAPI.net supports doing that. And is available as a cli for that purpose as hidi.
We don't advertise that tool a whole lot though.

[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.

[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.

[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]

Can we collect use cases from actual users? Ideally getting testimonials from users along the lines of "support for these features is a major factor in vendor choice for us." Or "we need these features but are being held back by (VSCode, AWS, Google, whoever).

For example, from my time working with the Open Geospatial Consortium, I know that both $dynamicRef (for generics/templates) and $self (separating identity and location) are hugely important to them. And as a standards organization publishing shared components, it matters that all of their component library users are able to update their tools.

We also know that several major LLM APIs use streaming JSON and/or SSE.

@lornajane you also know people were already using tags along the lines of the structured tag improvements.

I've definitely seen some excitement around the new security addition (device authorization flow?)

Someone was telling me that improved XML features were good because LLMs now also need to interact with XML APIs, but of course I can't find that now.

I know @jeremyfiel has major use cases for multipart/mixed, and @thecheatah had a use case for streaming multipart/mixed.

---

Somewhat separately, I wonder if there has been some self-sorting among the main documentation-slash-client-library set of implementations. People who want newer support have gone to the vendors that are more up-to-date, and older vendors mostly have conservative customers who are less interested in updating.

The problem isn't so much that those docs/client tools aren't updating, but rather that other parts of the ecosystem that are orthogonal to that choice, such as AWS Gateway and VSCode, are not budging. There's less of a direct connection there, which makes it more challenging.

[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!

[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

[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?