Compatible evolution, explicit migrations.
The main version is in the URL. Additive changes go into v1 without breaking clients; Incompatible changes require a new version and migration window.
What might change in v1
Additional operations and features may be published.
Clients should ignore unknown properties in responses.
Subscriptions with * can have types added to the catalog.
Open enums can gain documented states or providers.
What requires new version
Existing endpoint, field, or value does not disappear silently.
Incompatible semantics, unit or format requires new contract.
An optional field does not become mandatory within the same version.
Incompatible authorization changes receive their own migration.
Depreciation cycle
Change enters history with replacement and impact.
The two forms coexist during the informed window.
Documentation and responses identify the discontinued contract.
Removal only takes place on the announced date.