2026-09-23 migration guide — the contract cut
⭐ This is the guide for the CURRENT contract. On the day of the cut, the
/v1prefix stops responding and no old URL survives: not in the server, not in the parity harness, not in the load scripts, not in the documentation. Every endpoint changes URL at once, with no redirect and no grace period.What is NOT repeated here is the schema. The authoritative field-by-field inventory is the OpenAPI reference generated from the schemas the server actually uses:
https://docs.tarno.cl(in the repo,contract/openapi.generated.yaml). Duplicating it here would create a second source that drifts — which is exactly what this whole phase exists to fix. This page describes the migration (theold → newmap), not the schema.The record of every change, with its
[BREAK]/[BEH]/[ADD], is in the contract changelog. The notice to the single consumer — the Tarno app — is one letter, not several.
In one sentence
On the day of the cut, /v1 stops responding and the whole contract moves at once to: unprefixed
routes in English, field names in English, one envelope shape, one pagination, one error
body, one sort vocabulary — and labels stop being header-negotiated and arrive as a
three-language object. Event collapse becomes the default.
No redirect, no version header, no grace period. What breaks is done once and announced once (the single letter).
The three maps, complete
The three maps are copied from the contract register (CHANGELOG-CONTRACT.md, entries 38-04..38-14
and their retouches) — not reconstructed from the diff.
1 · Route map — REST (old → new)
The ones that disappear have no direct replacement: they fall into a filter or an expansion, noted on each row.
| old (stops responding) | new | disappearance |
|---|---|---|
GET /v1/brands |
GET /trademarks |
— |
POST /v1/brands/batch |
GET /trademarks?applicationNumber=a,b,c (up to 100) |
the batch becomes a filter |
GET /v1/brands/similar?q= |
POST /trademarks/search with similarTo |
similarity becomes a search engine |
GET /v1/brands/{n}/similar |
POST /trademarks/search with similarToTrademark |
ídem |
GET /v1/oppositions/open |
POST /trademarks/search with oppositionWindow: "open" |
the opposition window is a filter, not a route |
GET /v1/brands/{n} |
GET /trademarks/{applicationNumber} |
— |
GET /v1/brands/{n}/report |
GET /trademarks/{applicationNumber}?expand=… |
⭐ the report stops being a route: it is the detail with expand= |
GET /v1/brands/{n}/opposition |
GET /trademarks/{n}/annotations?family=opposition |
⭐ the opposition timeline was always a filter over annotations |
| (only inline in the mark) | GET /annotations/{id} · POST /annotations/search · GET /trademarks/{n}/annotations |
⭐ the annotation becomes its own resource |
GET /v1/personas |
GET /parties (+ GET /parties/{id}, GET /parties/{id}/trademarks) |
— |
GET /v1/insights/filings-over-time |
GET /insights/trademarks?groupBy=filedMonth |
the 5 routes fuse into one with groupBy |
GET /v1/insights/by-estado |
GET /insights/trademarks?groupBy=status |
ídem |
GET /v1/insights/by-class |
GET /insights/trademarks?groupBy=niceClass |
ídem |
GET /v1/insights/by-holder |
GET /insights/trademarks?groupBy=holder |
ídem |
GET /v1/insights/by-representante |
GET /insights/trademarks?groupBy=representative (+ POST /insights/trademarks/search) |
ídem |
GET /v1/feriados · GET /v1/feriados/cobertura |
GET /holidays |
coverage always travels in meta.coverage |
GET /v1/freshness |
GET /system/freshness |
operational stuff moves under /system |
GET /v1/sync-runs |
GET /system/sync-runs |
ídem |
GET /v1/watch* |
/watchlists · /watchlists/{id} · /watchlists/{id}/items · /watchlists/{id}/hits · /watchlists/{id}/deliveries |
the old style is retired entirely. ⚠ The /watchlists routes were retired too, on 2026-10-04: watching is now /watch/applications and /watch/hits (guide) |
NEW routes (replace nothing; nothing to migrate): GET /sections · GET /sections/{code} ·
GET /legal-norms · GET /legal-norms/{id} · GET /nice-classes · GET /system/coverage ·
GET /system/vigilance-horizon · GET /system/me · GET /health (root, no API key).
Filters. A single English set, the same shape in /trademarks, /trademarks/search and
/insights: q, applicationNumber, niceClass, status, signType, holder, representative,
taxId, filedFrom/filedTo, expiresFrom/expiresTo, registeredFrom/registeredTo,
publishedFrom/publishedTo, relation=current|former|all, similarTo, similarToTrademark,
oppositionWindow, facets, and since 2026-09-23 goodsAndServices (citedNorm/article/letter belong to annotations: on trademarks, 400). expand=parties,annotations,encumbrances,classes,norms only on GET /trademarks/{n}
(⛔ no fields=). holder/representative/taxId are lists (OR inside the parameter).
2 · Field map — (old → new)
Copied from the [BREAK] entry of 38-07 (the wire-vocabulary layer), plus the parties fields of
38-06.
| today (retired) | from the cut |
|---|---|
nroSolicitud / nroRegistro |
applicationNumber / registrationNumber |
denominacion |
denomination |
estado / tipoSigno |
status / signType |
fechaPresentacion / fechaPublicacion / fechaRegistro / fechaVencimiento |
filedOn / publishedOn / registeredOn / expiresOn |
seccion / seccionNombre / seccionEtiqueta / seccionTipo |
section / sectionName / sectionLabel / sectionFamily |
seccionActo / seccionActoNombre / seccionActoEtiqueta |
act / actName / actLabel |
observacion / observacionCompleta |
observation / observationDerived |
personas / personasHistoricas / anotaciones / gravamenes |
parties / formerParties / annotations / encumbrances |
clases / clasesHistoricas / clase / descripcion |
classes / formerClasses / number / goodsAndServices |
titulares / representantes |
holders / representatives |
renovaciones / ultimaRenovacion |
renewals / lastRenewalOn |
ventanaOposicion |
oppositionWindow |
estadoDerivado / estadoDesactualizado |
⚠ since 2026-09-23 (D11): the derived state travels in status (derivedStatus was withdrawn); INAPI's literal in statusInapi, only when it differs; the flag in statusStale, in every view |
fecha / nombre / pais / rol / identificador |
date / name / country / role / taxId |
variantes |
duplicates |
vigencia / soloVigentes |
relation / liveOnly |
traduccion / descripcionEtiqueta / imagenUrl |
translation / imageDescription / imageUrl |
holiday fecha / nombre / tipo / origen |
date / name / type / origin |
parties (the person becomes an entity with a role — 38-06):
| today | from the cut |
|---|---|
tipo / tipoOrigen |
kind (natural|legal|unknown) / kindSource (tax_id|suffix|manual, now nullable) |
nombre |
name |
identificador |
taxId |
pais |
country |
observacion |
jurisdictionClause |
nombrePublicado |
publishedName |
revision (boolean) |
review ({ reason }, the reason in code) |
region / comuna / regionNombre / comunaNombre |
territory ({ regionCode, regionName, communeCode, communeName, unknownCommune }) |
marcasTotal |
trademarkCount |
⚠ What does NOT change name, now or in a later pass:
- ~~
categoria/ambito(37D) keep their name~~ — ⛔ no longer:[BREAK]of 2026-09-23. The rule of the cut is that contract LABELS (field names) are English while VALUES may stay Spanish; seven Spanish labels were left and were renamed at once, on REST and MCP:categoria/categoriaEtiqueta→category/categoryLabel,ambito/ambitoEtiqueta→scope/scopeLabel,eventoId→eventId(annotations),titular→holders(each item of the trademark list and search),observacion→observation(in the mark'sparties[]) andfilters.clase→filters.niceClass(watchlists). And the mark'sparties[].kindnow publishes the/partiesvocabulary (natural|legal|unknown), notjuridica/desconocido. Exact table inCHANGELOG-CONTRACT.md. protectionDescriptionkeeps its name.- Code VALUES stay in Spanish.
statusis still"en_tramite",signType"mixta",classes[].status"concedida". Translating the codes to English (pending,word,granted…) is a later pass, not done yet. - INAPI literals (section codes
M5/A07T, the annotation text, the published spelling, the jurisdiction clause, the RUT) are not translated: the field name is translated, never the value.
3 · Tool map — MCP (old → new)
Copied from the [BREAK] entry of 38-11 (names aligned with the manifest, no alias and no window)
and from plans 38-05/38-06.
| today (retired) | from the cut |
|---|---|
search_brands / get_brands_batch |
list_trademarks (the batch is a filtered collection) |
find_similar_brands |
search_trademarks with similarTo / similarToTrademark |
get_open_oppositions |
search_trademarks with oppositionWindow: "open" |
get_brand_detail |
get_trademark |
get_brand_report |
get_trademark with expand= |
get_brand_opposition |
list_trademark_annotations (family=opposition) |
search_personas |
list_parties + get_party + list_party_trademarks |
insights_filings_over_time |
get_trademark_insights (groupBy=filedMonth) |
insights_by_estado |
get_trademark_insights (groupBy=status) |
insights_by_class |
get_trademark_insights (groupBy=niceClass) |
insights_by_holder |
get_trademark_insights (groupBy=holder) |
insights_by_representante |
get_trademark_insights (groupBy=representative) |
get_feriados / get_feriados_cobertura |
list_holidays |
get_freshness / get_sync_runs |
get_system_freshness / list_sync_runs |
watch_register |
create_watchlist |
watch_list |
list_watchlists |
watch_get |
get_watchlist |
watch_patch |
update_watchlist |
watch_delete |
delete_watchlist |
watch_list_hits |
list_watchlist_hits |
watch_list_deliveries |
list_watchlist_deliveries |
watch_list_items |
list_watchlist_items |
watch_add_item |
add_watchlist_item |
watch_remove_item |
remove_watchlist_item |
⚠ 2026-10-04: the ten
*_watchlist*tools in the right-hand column were retired in turn. They are replaced bywatch_application,unwatch_application,list_watched_applicationsandlist_similarity_hits; the map is in the Vigilancia guide.
NEW tools (nothing to migrate) — there are 14: explain_section_code · get_annotation · get_legal_norm · get_party · get_section · get_system_coverage · get_system_me · get_vigilance_horizon · list_legal_norms · list_nice_classes · list_party_trademarks · list_sections · search_annotations · search_trademark_insights.
⚠
get_system_coveragewas listed here as a rename of alist_system_coveragethat never existed. It is new: day-by-day ingest coverage arrived with the cut.
Additive: the catalogs become MCP resources (iris://catalogs/states, sections,
nice-classes, holidays/{year}), plus three prompts (availability_check, case_history,
weekly_watch) and a real version (2026-09-23) with the four rules in the server instructions.
The minor maps, also copied
Error codes (38-04)
| old | new | where |
|---|---|---|
fuera_de_cobertura |
out_of_coverage |
422 on the calendar |
cobertura_no_declarada |
coverage_not_declared |
503 on the calendar |
invalid_input |
validation_error |
MCP, all tools |
invalid_input |
batch_too_large |
the batch cap (now a 422, not a validation failure) |
Headers (38-04)
| old | new | note |
|---|---|---|
X-Request-Id |
X-Correlation-ID |
accepted from the client and returned on EVERY response |
X-Quota-Limit |
RateLimit-Limit |
— |
X-Quota-Remaining |
RateLimit-Remaining |
— |
X-Quota-Reset |
RateLimit-Reset |
⛔ also changes its VALUE: from an absolute instant to seconds remaining |
Retry-After is kept. ETag + If-None-Match (304) on every individual object; catalogs declare
Cache-Control.
sort tokens (38-12 + the 38-07 retouch)
⭐ Sort tokens are published ONLY in English. The retouch retired the Spanish aliases and renamed the status family.
| retired token | replacement |
|---|---|
relevancia |
relevance |
recientes |
filedOn:desc |
antiguas |
filedOn:asc |
estado / estado:asc / estado:desc |
status / status:asc / status:desc |
fechaActualizacion:asc / fechaActualizacion:desc |
retired with no replacement (it sorted by OUR pipeline's date, not an INAPI fact) |
The six fields that survive, each asc|desc: status, filedOn, denomination, expiresOn,
registeredOn, publishedOn — plus relevance. A token not listed is a 400 validation_error.
The SHAPE changes — what is not migrated by renaming
These are not name equivalences: they are shape changes a consumer has to wire up afresh.
(a) The envelope — ONE shape for every collection
📌 HISTORY — from 2026-09-20 to 2026-09-23 there were TWO envelopes. The trademark collections (
GET /trademarks,POST /trademarks/search, the batch,GET /parties/{id}/trademarks) used{ items, nextCursor, dataAsOf, estimatedTotal }(the batch,{ items, notFound, dataAsOf }). Since the 2026-09-23 evening[BREAK]there is one envelope, no exception — see § «2026-09-23 · single envelope».
{ "results": [ /* … */ ], "limit": 20, "next": "eyJvIjoyMH0", "hasMore": true, "total": 14,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" } }
It replaces ten envelopes, six paginations and three limit defaults in EVERY collection. The names
data, items, nextCursor and the bare array cease to exist. An individual resource responds as
a flat object, no wrapper, with freshness in headers (Iris-Data-As-Of, Iris-Coverage-Through).
totalonly travels when it is exact and cheap; where counting costs a scan, the key is absent. The search estimate travels asmeta.estimatedTotal(a lower bound), never astotal.- ⛔ No parameter changes the TYPE of a response.
?envelope=is retired: the four endpoints that returned a bare array by default now always return the envelope, just like MCP. This is the first time REST and MCP agree on this.
(b) Pagination — a single cursor
limit (default 20, max 100) + an opaque keyset cursor. offset is retired. A
stray ?offset= is a 400 validation_error that names the replacement. Over 10 M annotations the
offset is slow and lies about the total; the cursor is cut at the cap instead of offering a page nobody
can defend. A cursor issued for a different sort degrades to page one, not to a false page.
(c) The label — from negotiated string to a THREE-language object
seccionEtiqueta/seccionActoEtiqueta/categoriaEtiqueta (now categoryLabel)/ambitoEtiqueta (now scopeLabel)/renovacion.etiqueta
were a string negotiated by Accept-Language. Now each label is a LocalizedString with the
three languages at once, null where there is no translation:
{ "code": "registered",
"label": { "es-CL": "Registrada", "en": "Registered", "pt-BR": "Registrada" },
"source": { "label": "(R) Registrada" } }
- Header negotiation (
Accept-Language) is retired (an MCP agent sends no headers, and a response that depends on a header cannot be cached). - The response is identical with any
Accept-Languageand with none.
(d) Event collapse — becomes the DEFAULT (38-08)
Before, an annotation with copies of the same fact (Estado Diario and the record page publishing the same
thing) was returned one per row unless you asked ?dedupe=true. Now collapse is the default:
each fact is returned once, and whoever wants the copies asks with dedupe=false. Collapse is
logical: it never deletes a row — the copies stay published in duplicates[].
Each annotation gains two always-present fields: versionsOfFact (how many rows describe this SAME
fact) and versionsDiffer (true when another version exists that is neither identical nor contained).
The notice is neutral: it says THAT another version exists and HOW to ask for it, never WHICH one
says it (provenance leaves the contract). Guarantee: renewals/lastRenewalOn are identical
with dedupe=true and with dedupe=false.
(e) Errors — RFC 9457, a single body
Content-Type: application/problem+json, the same body in REST, in the jobs service and in MCP:
{ "type": "https://api.tarno.cl/problems/validation_error",
"title": "Request validation failed", "status": 400,
"detail": "`offset` was retired from the contract…", "code": "validation_error",
"requestId": "74c953c7-…", "errors": [ { "field": "offset", "code": "custom", "detail": "…" } ] }
code is what a client compares, and it is always in English. title/detail are for humans and
can change without being a [BREAK]; changing a code is one. requestId is the same value as
X-Correlation-ID. A 5xx does not carry internal detail to the client.
| status | means |
|---|---|
| 400 | validation — the request is malformed or a parameter is out of range |
| 404 | does not exist — the resource is not there, or is not yours (uniform across tenants) |
| 422 | business rule — the request is VALID and still cannot be served |
(f) The "no value" semantics on the mark (38-05)
The detail and the report declared the same fields with two null semantics (one omitted them, the
other gave them null). null wins: the eleven application scalars (registrationNumber,
status, signType, filedOn, expiresOn, publishedOn, registeredOn, translation,
imageDescription, protectionDescription, imageUrl) are always present, null when they have
no value. ⚠ The exception is kept: category/scope (formerly categoria/ambito, and their labels) keep being omitted when
"we don't know" (5.5 % of marks).
What to do: if you distinguished "nroRegistro" in obj from obj.nroRegistro === null, now only
the latter happens for those eleven. ?? defaultValue keeps working; Object.hasOwn(...) on them is
now always true. INAPI's '0' sentinel is still not published (before omitted, now null).
(g) The person becomes parties — one entity with a role (38-06)
Holder, applicant, representative and opponent are the same entity with a role where it intervenes
— and the same party stops appearing three times. territory is typed (codes WITH their names,
unknownCommune as its own field; null = foreign party). trademarkCount does not filter: people
with no marks keep showing up with their zero.
2026-09-23 · single envelope — the [BREAK] that closes the contract's loose ends
One incompatible change, dated 2026-09-23 (evening), recorded in CHANGELOG-CONTRACT.md:
| before | after |
|---|---|
trademarks: { items, nextCursor, dataAsOf, estimatedTotal, facets, mode } |
the common envelope: { results, limit, next, hasMore, meta } — meta.dataAsOf, meta.coverageThrough, meta.estimatedTotal, meta.facets, meta.mode |
batch: { items, notFound, dataAsOf } |
the same envelope, meta.notFound, exact total, next: null |
facets.clase · facets.estado |
meta.facets.niceClass · meta.facets.status |
matchedFields[].field: nombre/titular/representante/rut |
denomination/holder/representative/taxId |
highlight.field: "nombre" |
highlight.field: "denomination" |
kindSource on the trademark: rut/sufijo |
tax_id/suffix (as in /parties) |
an unknown parameter was ignored (200) |
400 validation_error, one errors[] entry per key; MCP: input error |
?envelope=, expand on the trademark list: ignored |
400 |
GET /trademarks/{n}: dedupe default false |
default true (also on GET /trademarks/{n}/annotations, which now accepts it) |
| the batch ignored the other filters | it APPLIES them; meta.notFound = only what does not exist; limit/cursor/sort/minScore/q/denomination/facets with the batch → 400 |
catalogs without Cache-Control (except /holidays) |
catalog Cache-Control on /nice-classes, /sections, /legal-norms and their objects |
| — | new goodsAndServices filter (goods-and-services text) |
sort=status by INAPI's literal |
by the published (derived) status |
Action for the consumer (checklist)
- Change the URL base: drop the
/v1prefix and apply the route map (§1). No redirect: an old URL responds with absence, not a301. - Apply the field map (§2) to everything you deserialize, and the tool map (§3) to every MCP call.
- Rewrite collection reads against the
results[]envelope (§a) and the cursor (§b): out withdata,items,nextCursor, the bare array andoffset— in EVERY collection, trademarks included. - Stop negotiating
Accept-Language: labels come in a three-language object (§c). - Assume collapse by default (§d): if you need the copies, ask with
dedupe=false. - Migrate error bodies to RFC 9457 and the codes/headers of the minor maps.
- Fix
sortliterals to the six English fields (§sort). - Verify against the generated reference:
https://docs.tarno.cl.
To run it with an assistant step by step, use migracion-38-prompt.md.
Map sources: CHANGELOG-CONTRACT.md 38-04..38-14 + retouches ·
contract/openapi.generated.yaml (the generated reference, not duplicated here).