Deprecation policy
Within a version
Section titled “Within a version”Every API carries its major version in the path (/v1/). Within a version, changes are additive only:
- new endpoints;
- new optional request members, and new values in lists the documentation says may grow;
- new members in responses — ignore members you do not know;
- new error codes.
Nothing is renamed or removed, and no existing request starts being refused, within a version.
Error codes are permanent
Section titled “Error codes are permanent”A published error code is never renamed and never reused for a different meaning. Its human title may be reworded.
Removing something
Section titled “Removing something”Nothing is removed without twelve months’ notice: a new version is published beside the old, the old one is marked deprecated in the reference and in this changelog, and both are served until the notice ends. A security fix that cannot wait is the only exception, and it is announced here with its reason.
Signed artefacts are forever
Section titled “Signed artefacts are forever”A seal, a certificate, a receipt or a sealed record is never re-issued in a new shape. Every one carries its own version — v, schema, ai_policy_schema, payloadType, adl_proj — so a verifier written today can read what was signed today in 2035, and refuses a version it does not know instead of guessing. New formats are new versions beside the old; verifiers accept each version they know. Projection specifications are pinned by hash and stay published, so an old row can always be checked against the specification that made it.
Libraries
Section titled “Libraries”The verifier libraries and SDKs follow semantic versioning. A release that pins MasterDB’s trust anchors, or adds a root successor, is a routine minor release: anchors are a set, so a root can rotate without a flag day.