handrews

Thanks! :-)

I actually looked at that one, too, and know the person (or one of the people) that started it. Their classification is better than tools.openapis.org (slightly embarrassing, but we don't have anyone who has volunteered to curate it beyond minimal PR approvals, so...). Although you still fundamentally see the same problems. And it was more convenient for me to point to the messier list for the purpose of this blog post, anyway!

For a while, the "P" key on my laptop wouldn't work reliably... which is really annoying when your work is all focused around OpenAPI but everyone else keeps assuming AI :P

My involvement started in the lead-up to OAS 3.1 so I don't have any insight into the Smartbear/OpenAPI Initiative hand-off. Yes, the decision to be vendor-neutral is part of the reason the ecosystem is so fractured. But most technical standards are vendor-neutral and work just fine.

OpenAPI also has the problem of not providing any guidance on what the tooling ecosystem ought to look like, regardless of who implements the tools. You want enough leeway to encourage innovation, but if you don't put out _anything_, you get... well... this. Lots of tools that don't all fully implement things, and not much in the way of interoperable points of hand-off between tools beyond the format. And when many tools leave off some feature or another (most egregiously, external referencing - down the line in this blog post I'll actually show a concrete solution for that), just sharing the format isn't enough.

I'm hoping that this approach I'm sharing through these blog posts will help us start to shape the ecosystem more. For Moonwalk if nothing else (although I'd love to get 3.x into more of an interoperable state- let's make life better for people working with things now, not just years down the line).

Part of the problem is that OpenAPI depends on JSON Schema and JSON Schema is a runtime constraint system, not a data definition system [1]. That shows up in the diagram with the three colors crammed into the "Interface Modeling and Validation" area because the boundary between those three ends up being very weird. And there's no standard for using JSON Schema as a data definition system... people just started kinda doing stuff.

I've been advocating for finding a better data definition system for Moonwalk (and yes, that's my name on the post-2016 JSON Schema drafts- it's a great runtime constraint system, and it could still be useful for that purpose alongside a system more tailored to data definition).

[1] https://modern-json-schema.com/json-schema-is-a-constraint-s...

> I just think if that was the goal of the article it could possibly use some additional framing for people who don't have the full context.

It's always a struggle to figure out how much explanation to put in before people see something like "20 minute read" and just refuse to read it. (BTW I don't mind the critical feedback at all- I'm just glad you found something useful in it).

But keep in mind that _we_ haven't answered "how do we actually make it a real spec?" either! This is a snapshot of our efforts at this particular moment. Also, there's a reason that this is "part one in a series" :-)

Yeah this article is more about how we (the OpenAPI Initiative) are designing the next versions of the OpenAPI Specification than it is about how to use it. The diagram does include both an OAD generator and editor, intended to encompass both code-first and description-first (which doesn't make too much difference for this blog post). The Moonwalk article is definitely more general purpose! This is "OK Moonwalk has a great vision, but how do we actually make it a real spec?" I've been using variations of this diagram in the weekly Moonwalk calls for the past month or two.

Yup. JSON Schema is a constraint system, not a data definition system. https://modern-json-schema.com/json-schema-is-a-constraint-s...

Technically, there isn't an "official" OpenAPI 3.x tool of any sort. SmartBear/Swagger is no more official than any other vendor with 3.0+ (obviously it's different for the versions named "Swagger"!). I am working on an official parser/linter (oascomply) on a contract for the OpenAPI Initiative to set a baseline to help tool developers implement consistent support for the spec. However, this is more about the parts of OAS outside of the Schema Object.

I'll repeat a relevant bit from an earlier reply of mine:

The ideal system, to me (speaking as the most prolific contributor to JSON Schema drafts-07 through 2020-12), would have clearly defined code generation and runtime validation features that did not get in each other's way. Keywords like "anyOf" and "not" are very useful for runtime validation but should be excluded from type definition / code generation semantics.

This would also help balance the needs of strongly typed languages vs dynamically typed languages.

The fundamental problem is that JSON Schema was designed as a constraint validation system (https://modern-json-schema.com/json-schema-is-a-constraint-s...) and it's been overloaded for type definition in ways that don't always make sense. But the JSON Schema alternatives that I've seen go too far in the other direction. There is a lot of value in being able to perform more complex runtime validation in a language-independent way.

There is a balance and clear separation of concerns needed between data definition and runtime validation, although they still should live in the same contract as there is considerable overlap. Now if I could only find someone who wants to fund the design of such a system... :-)

There are ways that URI Templates could be disambiguated for reverse mapping- that would be a discussion worth opening on the Moonwalk repo.

You can write it in JSON, you know. Not even "JSON as a subset of YAML" but actual JSON. The proposed media types are application/openapi+yaml and application/openapi+json

If you dig through enough of the discussions, you will definitely see talk around code gen. There's more discussions happening in the background that haven't really percolated out to the moonwalk repo because it's all pretty hand-wavey right now. My intention, when advocating for OpenAPI 3.1 to adopt JSON Schema 2020-12, which brings custom vocabulary support (which I led the design of for JSON Schema), was for additional vocabularies to improve code generation semantics. This has not really happened (for a variety of reasons including that vocabularies weren't quite done and I ended up unable to follow up on the whole thing for several years).

It's not entirely clear to me where things go from here, but I suspect Moonwalk will address it in some way. I'd like to focus on it some (from the OpenAPI perspective more than JSON Schema, specifically) but I haven't found anyone who would sponsor that work (I guess the dollars are flowing more to these alternatives several folks have mentioned)

OAS 3.0 is pretty well-supported by now. One of the biggest lags was Swagger, and they now support 3.0 and are finally making progress on 3.1.

One factor in 3.1 support is that it came out more-or-less concurrently with JSON Schema draft 2020-12, and depends on it. 2020-12 support has recently become more common across more languages, and we're seeing 3.1 work pick up the pace a bit.

But (from years of experience working on these standards), there is _always_ a lag in adoption. You can't just sit and wait until everyone "catches up" because that won't really shorten the lag to the next major version (OAS 3.1, despite the numbering, had significant enough changes to lag like a major version).

So while I'd agree that it's slower than if there were a clear and well-funded owner of things (which is closer to the situation with AsyncAPI), it's not _unusually_ slow as these things go.

One of the Moonwalk discussions is indeed about moving from objects to arrays for many structures: https://github.com/OAI/moonwalk/discussions/32

Also, I agree with the person who mentioned JSON Patch (RFC 6902), which I feel is an under-rated and underused technology. While less intuitive than JSON Merge Patch (RFC 7396), it is far more powerful. I have used both together, using JSON Merge Patch where possible to keep things more readable and intuitive, and using JSON Patch where JSON Merge Patch can't do what is needed. Although if most of your changes need JSON Patch, I find it's better to just stick with that.

I think it's worth pointing out that a lot (most?) of Fern's complaints against OpenAPI are really complaints against JSON Schema. There have been talks before about allowing other schema systems in OpenAPI - I wouldn't be incredibly surprised to see such things come up for Moonwalk. JSON Schema is not not a type definition system https://modern-json-schema.com/json-schema-is-a-constraint-s....

It's also worth noting that most JSON Schema replacements I've seen that prioritize code generation are far less powerful in terms of runtime validation (I have not examined Fern's proposal in detail, so I do not know if this is true for them).

The ideal system, to me (speaking as the most prolific contributor to JSON Schema drafts-07 through 2020-12), would have clearly defined code generation and runtime validation features that did not get in each other's way. Keywords like "anyOf" and "not" are very useful for runtime validation but should be excluded from type definition / code generation semantics.

This would also help balance the needs of strongly typed languages vs dynamically typed languages. Most JSON Schema replacements-for-code-generation I've seen discard tons of functionality that is immensely useful for other JSON Schema use cases (again, I have not deeply examined Fern).

Yes, JSON Schema describes documents/resources, not entire APIs on its own.

Even Hyper-Schema (to the extent that it's implemented at all yet) is a resource-by-resource system, not an API-scope system.

Note that "Understanding JSON Schema" has been updated for draft-07 and is now under the aegis of the main JSON Schema project: https://json-schema.org/understanding-json-schema/

JSON Schema has "$comment" as of draft-06 or -07 (I forget, which is funny b/c I was the one who added it).

Hi- I'm one of the main editors of the JSON Schema specification, and one thing we are doing with the next draft is making it easier to build extensions for things like code generation. We expect to work with the OpenAPI folks on this as it is very relevant to their interests :-)

Also, we and the OpenAPI Technical Steering Committee are actively working together to re-converge the specifications. OpenAPI 3 was developed while JSON Schema progress was stalled due to the prior editors leaving and a new group of us (eventually) picking it up.

OpenAPI 3.1 will most likely include a keyword to allow using standard JSON Schema as an alternative to their customized syntax, and hopefully we can achieve full integration on OpenAPI 4. There are also some other ideas being explored for improved compatibility in 3.x.

Standards work is hard, but the relationship between the OpenAPI TSC and the JSON Schema editors is quite healthy and we are making good progress.

Hi- I'm one of the main editors of the JSON Schema specification, and we and the OpenAPI Technical Steering Committee are actively working together to re-converge the specifications.

OpenAPI 3 was developed while JSON Schema progress was stalled due to the prior editors leaving and a new group of us (eventually) picking it up.

OpenAPI 3.1 will most likely include a keyword to allow using standard JSON Schema as an alternative to their customized syntax, and hopefully we can achieve full integration on OpenAPI 4. There are also some other ideas being explored for improved compatibility in 3.x.

Standards work is hard, but the relationship between the OpenAPI TSC and the JSON Schema editors is quite healthy and we are making good progress.