Repository navigation
Spec Compatibility and Versioning
mavrovde edited this page Nov 1, 2026
·
2 revisions
Part of the Technical Specification. Requirement prefix: VER. Refines "Versioning and deprecation" on API Design.
| 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 |
| 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 |
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]
| 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 |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference