Communicating version change magnitude

[handrews]

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:

• exclusiveMinimum and exclusiveMaximum are numbers rather than booleans, and function independently from minimum and maximum
• readOnly and writeOnly cannot change the meaning of required based on whether they are in a request or response, or based on HTTP method

This means that for a 3.0.3 spec that uses boolean exclusive* or relies on combinations of *Only and required being HTTP-context-aware, changing the openapi property to 3.1.0 would result in an invalid spec file, contradicting the Semantic Versioning policy for minor versions.

The options are:

1. Stop short of full JSON Schema compatibility
2. Call this OAS 4.0.0 and do some additional communication explaining that it's not that big of a change
3. Discard SemVer, call this OAS 3.1.0, and do some additional communication explaining that it's not quite backwards compatibile
4. Discard SemVer, call this OAS 3.5.0 to indicate it's bigger than one minor version, and do some additional communication explaining what "bigger than one minor version" means
5. Discard X.Y.Z entirely and do some additional communication explaining what the new thing is

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:

Object	Magnitude	Fields	Notes
Server Variable Object	clarification		enum should not be empty, likely to be a MUST NOT soon
Paths Object	clarification		paths start with /, clarified parameter matching
Path Item Object	clarification	$ref	sibling field behavior
Operation Object	clarification	callbacks	clarified map structure
Schema Object	clarification	pattern, nullable	clarified valid regex patterns, clarified underspecified nullable behavior

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.

Object	Magnitude	Fields	Notes
Schema Object	incompatible	exclusiveMinimum, exclusiveMaximum, minimum, maximum	exclusive* now numeric rather than boolean, and independent from minimum and maximum
Schema Object	incompatible	readOnly, writeOnly, required	required is no longer conditional based on *Only plus HTTP request vs response context
Schema Object	incompatible	format	no longer validated by default (although note that few validators ever did this reliably), byte and binary deprecated in favor of new content* keywords
Schema Object	compatible	many new keywords	All draft 2019-09 keywords supported
Discriminator Object	compatible	^x-	extensions now allowed
Reference Object	compatible	summary, description	also other fields allowed for $ref in Schema Objects
OpenAPI Object	compatible	paths, webhooks	new webhooks feature, paths now optional if webhooks or components present
Info Object	compatible	summary, description	summary added, longer description allowed
Security Scheme Object	compatible	securitySchemeType	"mutualTLS" added
Security Requirements Object	compatible	{name}	scopes array usable in more cases
OAuth Flow Object	compatible	oauthFlowAuthorizationUrl	"implicit" to be deprecated by OAuth2
Operation Object	compatible	requestBody	request bodies allowed but discouraged for GET and DELETE
Media Type Object	compatible	encodingStyle, encodingExplode, encodingAllowReserved	improved multipart/form-data support

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!

[philsturgeon]

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.

[philsturgeon]

And the winner is:

Discard SemVer, call this OAS 3.1.0, and do some additional communication explaining that it's not quite backwards compatibile

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.