Skip to content

Paraphrasing SemVer Caused Confusion #2022

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Oct 24, 2019
Merged

Paraphrasing SemVer Caused Confusion #2022

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed209dc
TSC 2019-10-03 Feedback
Oct 3, 2019
086ffd5
Ron's wording for Darrels feedback
Oct 15, 2019
0de8bd8
ted updates
Oct 24, 2019
ac6bf57
backticks
Oct 24, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion versions/3.0.3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https:/

The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.

Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
If an OAS definition has its minor version incremented, it MUST still be a valid definition for the new minor version. E.g., if we have a document that is 3.0.2 and we change the version to 3.1.0, then it MUST be a valid 3.1.0 document.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is "OAS definition" here consistent wording? Not to be confused with definitions? Do we mean a document or something?

Copy link

@mkistler mkistler Oct 20, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to make a stronger statement than just

it MUST be a valid 3.1.0 document.

I think we should also require that it have the same interpretation as the 3.0.x document.

To illustrate: consider the "required" attribute in a parameter object. It currently defaults to false. I think that changing this default to true would be considered a "breaking change", but it would not affect the "validity" of any 3.0.x API doc that was updated to 3.1.0.

I'm not sure how best to word this in the spec, but perhaps something like:

If an OAS definition has its minor version incremented, it MUST still be a valid definition for the new minor version with an equivalent interpretation to the original definition. E.g., if we have a document that is 3.0.2 and we change the version to 3.1.0, then it MUST be a valid 3.1.0 document with an equivalent interpretation to the 3.0.2 definition.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mkistler fair enough! @darrelmiller @webron what do you think? Can somebody hit that sweet sweet Suggest button and try to solve this feedback without removing your own meaning?


An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)

Expand Down