Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Communicating version change magnitude #2219

handrews opened this issue Apr 30, 2020 · 2 comments

Communicating version change magnitude #2219

handrews opened this issue Apr 30, 2020 · 2 comments


Copy link

@handrews handrews commented Apr 30, 2020

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!

Copy link

@philsturgeon philsturgeon commented May 6, 2020

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.

Copy link

@philsturgeon philsturgeon commented Dec 3, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet

No branches or pull requests

2 participants