Skip to content

Spec Compatibility and Versioning

mavrovde edited this page Nov 1, 2026 · 2 revisions

Spec: Compatibility and Versioning

Part of the Technical Specification. Requirement prefix: VER. Refines "Versioning and deprecation" on API Design.

1. Two version numbers

Version Where Rule
Interface major the path, /v1 Changes only with a breaking change
Release version /v1/meta apiVersion, the OpenAPI info.version, image tags, the changelog Semantic Versioning 2.0.0: 0.x pre-releases until the first public release (Roadmap), from then on kept in step with the platform version ([[Development Process

2. What is breaking

Change Breaking?
Adding an operation, an optional parameter, a response member, a problem type refinement, a warning code, a language No
Adding a value to an open enumeration No (ENV-050)
Adding a new source family to an answer No
Removing or renaming an operation, parameter or member Yes
Changing a type, a format, a unit, the meaning of a value or the default of a parameter Yes
Making an optional parameter required, or narrowing accepted values Yes
Changing the order of a list, or the status code of a case Yes
Removing an enumeration value Yes
Tightening a limit below a documented design default Yes; raising a limit is not
Changing an error type URI Yes
Fixing a defect that contradicts this specification No, but announced in the changelog

3. Lifecycle of a major version

flowchart LR
  B[Beta: v2 beside v1,<br/>may change] --> G[v2 generally available]
  G --> D[v1 deprecated:<br/>Deprecation and Sunset headers]
  D -->|at least 6 months| S[v1 sunset:<br/>404 not-found with a link to v2]
Loading

Requirements

ID Requirement Verification
VER-001 Within a major version only non-breaking changes per section 2 MAY be made. Contract
VER-002 Every pull request MUST run a breaking-change diff of the OpenAPI document against the default branch; a breaking change without a new major path MUST fail the check. Lint
VER-003 A new major MUST be served beside the old one; the old one MUST then carry deprecation signals (ENV-060) for at least deprecation.min_notice (design 183 days) before sunset. Handler
VER-004 After sunset, every operation of the old major MUST answer 404 not-found with a Link to the successor operation for at least 90 further days. Handler
VER-005 Release versions MUST follow Semantic Versioning 2.0.0; the changelog MUST follow Keep a Changelog 1.1.0 and be generated from Conventional Commits 1.0.0. Lint
VER-006 The OpenAPI document MUST be the single source of truth for the interface: generated from the code, committed, served at /v1/openapi.json, and published with every release as a release asset and on the documentation portal. Contract
VER-007 A beta operation MUST be marked x-stability: beta and be reachable only with keys that opted in; it MAY change without notice. Stable operations are x-stability: stable. Contract
VER-008 Deprecations and sunsets MUST be announced in the changelog, on the documentation portal and in /v1/meta deprecations[] on the day they take effect. Docs
VER-009 Read-contract version changes on the storage side MUST NOT change the public interface; the service MUST report its contract version and refuse readiness on an incompatible major (contract.expected). Handler

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally