Versioning and deprecation policy

This page says what you can rely on when you build against the platform, and how a change reaches you.

What carries a version

The contract file. info.version of the OpenAPI file, now 1.0.0, and the version in the path: /v1 on the verify host, /api/v1, /d/v1, /s/v1.
The proof-of-play batch. The schema field of a batch, now tanba.pop/1.
The signed files. A revocation list, a seal and an anchor have v in the signed body, and the inputs file of a ledger day has its own v.
The status of a connection on this site: live, beta or draft.

Statuses

Status	What it means	Notice before a breaking change
Live	Stable. Built to be depended on	At least 12 months
Beta	Works and is used, but may still change. The device protocol and the evidence files are beta while the identifiers of the signed attributes sit in a provisional arc	At least 30 days, when we can; the changelog says what changed
Draft	A proposal. Not on the index of the search engines	None

Changes that are not breaking

We make these at any time, without notice, in the current version. Your client must tolerate them:

a new operation, a new optional parameter, a new field in an answer or in a signed body;
a new value in a list of values, for example a new flag, a refusal reason, an event name or an error code;
a longer text, a new header, a different order of fields.

So: ignore fields you do not know, and treat a value you do not know as "other", not as an error. Match on code, never on the texts of title or detail.

Breaking changes

These are breaking and only come in a new major version, next to the old one:

removing or renaming an operation, a parameter or a field;
changing the meaning or the type of a field, or the format of a number;
a new required parameter or a new required field in a request;
a limit that is tighter than the published one;
a different signature algorithm or a different way to compute a signed value.

A new major version has its own path (/v2) or its own schema (tanba.pop/2). The old version keeps working for the whole notice period.

How a deprecation runs

The operation or field is marked deprecated in the reference and in the OpenAPI file (deprecated: true), with what to use instead and the date it stops working.
The changelog gets an entry the same day.
The deprecated thing keeps working until that date. The notice period is the one of the status in the table, counted from the entry in the changelog.
After that date it is removed, and the changelog says so.

Security and legal exceptions

A change that closes a security hole, or that the law requires, can take effect at once. We publish the entry in the changelog as soon as we can, and say what you have to do.

Where to look

Every change to the contract is in the changelog, newest first, in plain words. The raw OpenAPI files on each connection page are the source of this site, so a client generated from them always matches the pages.