Communicating version change magnitude #2219
For those who have not been following (if you have you can skip down past the horizontal line), the question of whether we can include full JSON Schema compatibility in the next release and call it OAS 3.1 has been brought up. Proper JSON Schema compatibility would require:
This means that for a 3.0.3 spec that uses boolean
The options are:
I don't think anyone is pushing hard for option 1, although I'm not 100% sure everyone's up to speed on the breakages so I don't want to assume. But if we go with any of the others (that last one is unlikely but included for completeness), we need extra communication and that's what this issues is about. I'll personally be fine with any of 2-5, but I understand why just calling this OAS 4.0.0 is undesirable for most people in the conversation so far.
I propose prominently featuring a table listing which Objects (or other major things that aren't directly associated with a single Object) have changed, and the magnitude of the changes: clarification, compatible, or incompatible. Clarifications need only be mentioned if users are likely to have misinterpreted the unclear prior version and used it incorrectly.
Here are examples for three releases. This shows how the tables make the distinction between "incompatible, but in a limited way" and "you're going to have to basically rewrite everything."
There is no table for a purely backwards compatible (but more than clarification) release, because we haven't had one yet, but hopefully it's obvious how that would show up and be clear.
OAS 3.0.2 => 3.0.3
You can see immediately that there's nothing but clarifications:
OAS 3.0.3 => ?3.1.0? ?3.5.0? ?4.0.0?
You can see immediately that it's not fully compatible, but that the incompatibilities are contained within the Schema Object and even then only a few keywords.
OAS 2 => OAS 3
It would not even be possible to write out such a table, because the entire format was refactored, as were many of the objects in ways too major to break down to just a few keywords. Or maybe it would be possible, but it would be nearly as large as the spec so there wouldn't be much point!
The text was updated successfully, but these errors were encountered:
In the last call we discussed how people were fearful of going to v4 - people being mostly end users, not tooling vendors.
That's how you solve it, clearly communicating "narrow" breaking changes, an that they could effect you. OpenAPI needs a blog, with an excellent DevRel writing it, then it's a non issue.
And the winner is:
As with most things in programming, there are lots of awful choices with lots of pros and cons, so let's not dwell on decisions that have been made. None of them were perfect.