From ed209dc8573838f57cf609a41ab172a609e2f2fb Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 3 Oct 2019 18:42:36 +0200 Subject: [PATCH 1/4] TSC 2019-10-03 Feedback This sentance was meant to paraphrase semver for clarifty, but ended up suggesting a confusion situation where new things essentially cannot really happen. @webron has context on this. --- versions/3.0.3.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 24132d28bd..12eda52335 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -102,8 +102,6 @@ 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`. - 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"`.) ### Format From 086ffd56bc203b3d1b0fafa74bee3973ae7482f0 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Tue, 15 Oct 2019 13:13:16 -0700 Subject: [PATCH 2/4] Ron's wording for Darrels feedback --- versions/3.0.3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 12eda52335..6ce5fbb4f5 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -102,6 +102,8 @@ 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. +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. + 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"`.) ### Format From 0de8bd8d04a9716aed1e844319414741bd79bbd1 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 24 Oct 2019 12:45:01 -0400 Subject: [PATCH 3/4] ted updates --- versions/3.0.3.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 6ce5fbb4f5..70a5ab3dd4 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -102,7 +102,9 @@ 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. -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. +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. + +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. 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"`.) From ac6bf574ed2bb960046cc1dbd4ff67c5314a7e31 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 24 Oct 2019 12:46:58 -0400 Subject: [PATCH 4/4] backticks --- versions/3.0.3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 70a5ab3dd4..055bc9dd66 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -102,9 +102,9 @@ 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. -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. +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. -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. +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. 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"`.)