Skip to content

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; /docs is the authoritative schema. The two are not duplicated.

✅ This policy has been in force since 2026-09-23. That day the v1 prefix stopped answering, in a single deploy and with no redirect. Integrators got it through the migration letter, with the full before → after guide.

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.version is 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-revision and the ETag. info.x-revision is 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. The ETag of GET /docs/openapi.json identifies its exact content: send If-None-Match and a 304 tells 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

  1. The changelog entry, with its label and its date.
  2. A migration letter with the complete before → after map: 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.
  3. 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 retired denominacion / 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.