Request for API Version Chaining Feature

Hey all, after discussions with Marsh at API Strat, I'm putting forth a feature request that allows for better API version discovery. It's basically triplets (aka hypermedia) for versions.

Today, the spec allows for notation of the current version. However, humans and machines have no way of knowing if, when "interrogating" an particular OAS file, if you're looking at the most current version, if there's a previous version, or if there's a next version. It'd be great if machines/humans could see where in the chain of versions, they are when looking at a specific spec.

So,

info: 
   version:                  2.4.1  (this version)
   previousVersion:  <uri to openapi spec for previous version>
   nextVersion:          <uri to openapi spec for next version>

pretty simple. from there, machines/humans can take care of the rest.

Background here is that tooling should be able to monitor a spec file to spot changes to the API. However, unless it's a super minor change, then those changes trigger a new version and subsequently, those changes are reflected in a new spec file (as opposed to the existing spec file). But currently, there's no way for machines/humans to determine from a current spec file if another spec file exists.

Extra credit might be another field to give some additional status as to the production-level of the current spec file. For example:

info: 
   version:                  2.4.1  (this version)
   previousVersion:  <uri to openapi spec for previous version>
   nextVersion:          <uri to openapi spec for next version> 
   productionStatus: Pre-Release

This might be more difficult as its effectiveness would require standard vocabulary which might trigger a difficult debate. But, if there's interest in this feature, I do have suggested vocabulary that spans everything from pre-release to deactivated.

Thank you.

David Berlind
ProgrammableWeb

Start with the YAML examples in the issue and review how the proposed previousVersion, nextVersion, and productionStatus fields would fit the OpenAPI specification. Done would require an agreed schema and status vocabulary, but the issue does not name repository files or tests to run.