Semantic versioning for APIs
5 min · 50 XP · Read → Check → Complete
A version number is a promise
Exchange assets use semantic versioning: MAJOR.MINOR.PATCH. The number
tells consumers what to expect.
| Change | Bump | Example |
|---|---|---|
| Breaking (removed field, renamed path) | MAJOR | 1.4.2 → 2.0.0 |
| Backward-compatible addition | MINOR | 1.4.2 → 1.5.0 |
| Fix / docs, no contract change | PATCH | 1.4.2 → 1.4.3 |
The rule that protects consumers
Never make a breaking change without a major version bump. Adding an optional field is a minor bump. Removing a field, tightening validation, or renaming a resource is major — and major means a new, separately consumable asset version.
Coaching note
The most common governance failure you will see is a "small fix" that quietly breaks consumers. Coach teams to ask one question before publishing: could an existing consumer break? If yes, it is a major bump — full stop.
Check your understanding
1. A team removes a response field from an API. What version bump is required?
2. Adding a new optional field to a response is which kind of change?