Versioning
Versions tell you whether two services still understand the same contract after an update. A minor update adds compatible information. A major update can require changes to your integration.
For example, adding an optional field to an open response can be minor: older callers ignore it. Renaming a required field is major because those callers would no longer find the answer they expect.
The protocol, each profile, and each binding version independently as MAJOR.MINOR, and callers pin on the major. Open value spaces and open objects are what make MINOR additions safe: a consumer ignores what it does not recognise instead of failing.
What changes what#
| Change | Impact |
|---|---|
| New optional member on an open object, event type, operation, or error code | MINOR |
| New value in an open space (store, environment, eventType…) | MINOR |
| Member removed, renamed, retyped, or made required | MAJOR |
| Member added to a closed object or closed enumeration | MAJOR |
| Operation removed, or its path, method, or auth role changed | MAJOR |
The REST path's v1 segment is the protocol major, so two majors can be served side by side during a migration. The full decision table is SPEC.md §12.