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

[handrews]

@lornajane do you mean "down-convert tool" in the sense of "if you have a 3.1 or 3.2 OAD, this tool will provide the closest OAD 3.0 equivalent that will work with <insert your recalcitrant implementation here>?

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

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

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

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.