Versioning and deprecation

Five things are versioned separately

Axis	Where it appears
Protocol reference baseline	The pinned validator revision
Universe API surface	The /v1/ segment and the service revision
Marketplace contract	The Marketplace v1 route and signing contract
Generated schemas	A version field inside each schema
Documentation	The documentation version on every page

Never assume two of them move together.

Reading a service version

GET /version returns the service name and version, the source revision and its evidence, the declared Git revision where available, the runtime version, the pinned provider version, tag, commit, and required AIPs, the projection name, and the asset types covered.

Record all of it with anything you cache.

What counts as breaking

• Removing a route, a field, or an enum value.
• Changing the type or meaning of an existing field.
• Changing a default that alters results.
• Tightening validation so a previously accepted request is refused.
• Changing an identifier’s shape.

Adding an optional field or a new route is not breaking, so build clients that ignore unknown fields.

Deprecation

A deprecated capability still works and is scheduled for removal. Every deprecation carries the old behavior, the new behavior, the effective version, migration instructions, the compatibility impact, and the source evidence.

Current example: the legacy Marketplace /buys and /orders/{orderId}/reconcile aliases remain available, and new integrations use /reservations, /purchases, and /settlements.

What a deprecation does not promise

It does not promise the old behavior is identical to the new one. Read the migration note rather than assuming a rename.

Where changes are published

Artefact	Contains
Releases	Human readable changelog
Versions	The compatibility matrix
Deprecations	What is scheduled for removal, and when
Migrations	Step by step moves between versions
The changelog feed	A machine readable feed of the same

Source

Migration and releases.