Versioning & deprecation
Tarno exposes a stable read contract. This document describes the policy: what counts as a compatible change, how a breaking one is shipped, and how an integrator finds out.
The per-field schema is the live, interactive OpenAPI (Scalar) reference at
/docs— it is generated from the running code and is always current. This page describes the policy;/docsis the authoritative schema. The two are not duplicated.✅ This policy has been in force since 2026-09-23. That day the
v1prefix stopped answering, in a single deploy and with no redirect. Integrators got it through the migration letter, with the fullbefore → afterguide.
The contract carries no version in the URL
There is no v1 or v2 in the path. An endpoint is https://api.tarno.cl/trademarks, full
stop. The contract is versioned by its changelog, not by its URL:
- The contract changelog is the version. Every entry says what changed, when,
and under which of its seven labels:
[ADD]adds (a route, a field, an optional parameter) ·[BEH]behaviour changes (same shape, different values) ·[BREAK]breaks ·[FIX]fixes a fault without changing the shape ·[INT]internal change, no visible effect except on a failure ·[DATA]the corpus itself moved (a recovery, a backfill, a corrected series) ·[WITHDRAWN]an entry announced and retracted before it shipped: the contract did not move. - The OpenAPI carries the contract date in
info.version— it is a dated document, not a semantic version number nobody ever incremented. ⚠info.versionis the date of the last cut of the contract, not a change counter: it does not move with every changelog entry. - To know whether you must re-read the document, read
info.x-revisionand theETag.info.x-revisionis the date of the newest changelog entry with a visible effect on the document (computed at build time;[INT],[DATA]and[WITHDRAWN]do not count) and, when it is missing, the server could not compute it: do not assume it. TheETagofGET /docs/openapi.jsonidentifies its exact content: sendIf-None-Matchand a304tells you nothing changed, even if the date did not move.
A version prefix promises something it cannot honestly keep: that the old version will keep serving. Keeping two live contracts doubles the work of every change and, with a single integrator, protects nobody. It is retired.
Additive by default — and what it asks of you in return
Most changes are compatible and ship without prior notice:
- A new endpoint.
- A new optional request parameter.
- A new field on a response object.
- A new value in an open-set enumeration, where the contract already documents that the set may grow.
⚠ What makes that addition safe is an obligation on your side, and it is the only one we ask of you:
you must ignore fields you do not recognise. A client that fails on an unexpected key, or that
validates the response against a closed schema, will break on a change that is compatible for everyone
else. If your language allows it, deserialise with additionalProperties permitted and do not assume
the response shape is closed.
What breaks is a direct [BREAK]
A backwards-incompatible change is applied in place, marked [BREAK] in the changelog, and
announced. There is no deprecation window, no version header, and no two contracts coexisting.
These count as [BREAK], for example:
- Removing or renaming an endpoint, a field, or a parameter.
- Changing the type, the units, or the meaning of an existing field.
- Making a previously optional parameter required.
- Changing a default behaviour in a way an existing client would observe.
Removals are just another [BREAK]: they get no cycle and no calendar of their own.
How you find out
- The changelog entry, with its label and its date.
- A migration letter with the complete
before → aftermap: old route → new route, old field → new field, old error code → new. ⭐ One single letter, even when a deploy consolidates several changes: thirteen loose notices are sorting work we would be handing to you. - The published migration guide, including a version written for a coding assistant to follow.
⛔ What this policy does NOT do, and why
Written in the negative on purpose, so it does not get proposed again as a novelty.
| mechanism | status | reason |
|---|---|---|
Version prefix in the path (v1, v2) |
retired | it promised two live contracts at once; with one integrator that is cost without benefit |
Contract version header (e.g. a dated Iris-Version) |
rejected | same reason: it is the window mechanic wearing different clothes |
Deprecation / Sunset headers (RFC 9745 / RFC 8594) |
noted as a future option | they are the right standard if there is ever more than one consumer. Today there is not, and a window nobody uses is ceremony |
| A minimum 90-day window before removal | repealed | it was the previous policy. See below |
A 308 redirect from the old path to the new |
rejected | it keeps the old path alive, which is exactly what the cut removes |
What this page used to say, not deleted in silence. Until 2026-09-20 this policy promised that «a backwards-incompatible change is never applied in place on
v1… it ships under a new version prefix (v2)», with a window of at least 90 days. It was in force and it was genuinely applied: the v1.6 consolidation completed that whole cycle and retireddenominacion/fechaDesde/fechaHasta, with its migration guide. The policy changed because the assumption behind it — several integrators on their own schedules — never came true.
Where to watch for changes
/docs— the live schema reference, generated from the running code.- Contract changelog — every contract change with its label and date, from 2026-09-17 onwards. It is the contract version.
Tarno runs on a single machine with manual operator start-up (see the SLA), so the operator can also contact you directly to coordinate a migration when needed.