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).
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.
> OK Moonwalk has a great vision, but how do we actually make it a real spec?
I'm not sure the article really succeeds if that was the goal. I suspect that there might be some aspects of the discussion that are taking place that are missing from the article making it a little difficult for someone who wasn't in those discussions to connect the dots.
Don't get me wrong, I think the article had some useful pieces in it, 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.
With that said, I really appreciate transparency into the thought process!
> 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" :-)
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... :-)
