Semantic versioning communicates compatibility impact through major, minor, and patch components. For API interfaces, increment major versions for breaking changes and minor versions for backward-compatible changes; reserve patch versions for implementation bug fixes rather than API versioning. section 15.4.2
API changes map to version increments according to their effect on consumers:
- Add a backward-compatible operation: increment the minor version, such as 1.0 to 1.1. section 15.4.2
- Add backward-compatible response fields: increment the minor version, such as 1.1 to 1.2. section 15.4.2
- Replace a path parameter or remove always-returned data: increment the major version, such as 1.2 to 2.0 or 3.0. section 15.4.2
Representing the version in OpenAPI
Set the API version as a quoted string in info.version: version: "1.2". If the document itself changes without changing the interface contract, use a document patch value such as version: "1.2.1". Check generated documents because tools may insert an implementation version instead of the API version. section 15.7.1
Figure 15.9 Semantic versioning indicates the type of change and date-based versioning doesn’t.
Compare semantic versioning, which signals the type of change, with date-based versioning, which signals release timing but requires documentation to identify differences. section 15.4.2
Choose the scheme and its representation early, assess affected consumers before breaking changes, and document updates with changelogs and deprecated elements. Semantic versioning is the default choice; date-based versions may suit frequent, regular releases. section 15.8
Automated enforcement
A Spectral rule can target $.info.version and validate the API and document version format. Test the JSONPath on a valid OpenAPI document before replacing a temporary undefined function with the final validation function. section 18.12 section 18.5.1
