Version Enhancement to Compatibility Strategy

The current OpenAPI Specification includes a field version in the Info Object that is a required string containing a version number for the API. Currently the specification does not state the semantics or syntax of the structure of this string. Community discussion has indicated a preference for semver format and semantics.

Versioning is really just an obvious, intuitive, and commonly used approach to the deeper issue of API compatibility. From that perspective, versioning is just one of several possible compatibility strategies. There are several commonly used approaches to versioning. Many in the hypermedia community feel that we should not version resources, although that pushes potential versioning into the representation. Since the OpenAPI specification describes both the URL and the payload, representation compatibility strategies should be addressed, as well.

I would like to propose that the current info.version be elaborated to a compatibilityStrategy object functionally similar to the Security Definitions and Scheme Objects. To maintain compatibility and for forward migration, the default strategy would map to the equivalent of the current version definition.

An example might be

{
    "openapi": "3.1.0",
    "info": {
        "title": "MyAPI",
        "compatibilityStrategy": "semver"
    },
    ...
}

The details of compatibility strategies and their corresponding objects needs to be elaborated.

Other strategies might include “simple”, “date”, or “migration”. The “simple” strategy might be a single-digit strategy based on a major version or a sequence number as is most commonly represented in URL-based API versions. The “date” strategy is fairly self-evident and might address use cases like Stripe. The “migration” strategy describes an approach I am developing that obviates the need for versioning based on a limited compatibility period.

I would also like to propose that compatibility strategies could apply at smaller granularities than the API as a whole, most notably at the level of the payload entity defined in the Schema Object. This proposal will also impact the evolution of the “deprecated” fields and should be coordinated or merged with issue #782.

[srvance]

@darrelmiller How would you feel about defining it as the version of the API description, not of the API itself?

The word version carries connotations that steer users and tools and block alternate approaches. I understand if you don’t want ideas you don’t feel are fully mature to be represented in the standard yet, but do you really want to prevent them?

Frankly, @fehguy, lots of people feel the pain of versions, but few understand that there are alternatives and what they are. The ones who do usually get drowned out by the ones who insist there aren’t practical alternatives or don’t want to be bothered. Millions of people thought the world was flat for hundreds of years, and look where we are now. Mass belief is not a strong argument of anything other than mass belief and an acknowledged current perceived reality.

Is there any way to put it to the thousands? Counting reactions, there are five in this thread in favor of the proposal and two against.

[handrews]

For better or worse, using a version identifier for an API is by far the most commonly expected declaration of compatibility.

That’s a reason to support it, not a reason to require it.