Skip to content

Commit 5bd02e1

Browse files
authored
Merge pull request #2022 from philsturgeon/dont-paraphrase-semver
Paraphrasing SemVer Caused Confusion
2 parents 03735c8 + ac6bf57 commit 5bd02e1

File tree

1 file changed

+3
-1
lines changed

1 file changed

+3
-1
lines changed

versions/3.0.3.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,9 @@ The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https:/
102102

103103
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.
104104

105-
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`.
105+
Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the `openapi` property to the new minor version.
106+
107+
For example, a valid OpenAPI 3.0.2 document, upon changing its `openapi` property to `3.1.0`, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
106108

107109
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"`.)
108110

0 commit comments

Comments
 (0)