Paraphrasing SemVer Caused Confusion

[philsturgeon]

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.

[darrelmiller]

Alternate proposal for clarifying semver confusion:

If an OAS definition has the 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 and we change the version to 3.1, then it MUST a valid 3.1 document.

[philsturgeon]

@darrelmiller my concern is that we are still paraphrasing SemVer, when semver is capable of speaking for itself? This line seems to have less potential for confusion but I’m not entirely sure we need to drive this point home?

[darrelmiller]

@philsturgeon I wish I could agree. Perhaps semver could speak for itself if we were deploying a versioned software component, but all semver says about minor versions is the following:

Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API.

It however doesn't define what "backwards compatible" means. The statement we are adding here is a concrete test to determine backwards compatibility.

[tedepstein]

@darrelmiller wrote:

[SemVer] however doesn't define what "backwards compatible" means. The statement we are adding here is a concrete test to determine backwards compatibility.

I agree, we need to clarify what we mean by backward-compatible because a textbook definition of backward compatibility (if there is such a thing) might imply a kind of compatibility that we do not and cannot support. Here's Wikipedia:

Backward compatibility is a property of a system, product, or technology that allows for interoperability with an older legacy system, or with input designed for such a system.

The language in the current 3.0 spec, deleted in this PR, seems aligned with that definition:

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.

The problem is, this isn't true!

Some 3.0 tools, e.g. code generators, are strictly OpenAPI consumers, and they could process a 3.1 document as a 3.0 document, ignoring unknown keywords. Whether it's advisable to do so depends partly on what guarantees OpenAPI makes w.r.t. "backward compatibility" as we define it.

But 3.0 editors, validators, and other OpenAPI producers really can't support OpenAPI 3.1 documents, and probably shouldn't try. A 3.0 editor won't work with 3.1 because there are new keywords that 3.0 editors would consider to be errors; and because an openapi: 3.1 property value would probably cause a well-behaved 3.0 editor to exit with an error.

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.

This is exactly what I think we mean, intuitively, by backward compatibility. Maybe it's clearer to state it as a guarantee made by the OpenAPI specification, rather than a requirement on the 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 by setting its openapi property to the new minor version.

E.g., a valid OpenAPI 3.0.2 document, upon changing its openapi property to 3.1, SHALL be a valid OpenAPI 3.1 document. New minor versions of the OpenAPI specification MUST be written to ensure this form of backward compatibility.

[philsturgeon]

@darrelmiller you win! 🚢 🤡

[philsturgeon]

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

[mkistler]

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.

[philsturgeon]

@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?

[tedepstein]

Updated language, discussed on the call:

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.

[earth2marsh]

Following the discussions on the TSC call on 2019-10-24, these changes LGTM.