Skip to content

v1.6 migration guide — contract consolidation

The v1.6 consolidation of the /v1 contract is now applied: the deprecation window closed and the three deprecated parameters were retired from /v1/brands. The estado parameter is now a validated 14-code enum. The strict-contract flag and the RFC 8594 signals (Deprecation/Link/Sunset) no longer exist: the strict contract is now unconditional.

This guide documents the old → new mapping that is now in force. The authoritative per-field schema is the live OpenAPI reference at /docs; this page describes the migration, not the schema.

In one sentence

  • The denominacion, fechaDesde and fechaHasta parameters were retired from /v1/brands. A request that still sends them does not fail: Zod discards them silently (200 with broader results), never a 400.
  • The estado parameter is validated against a closed 14-code vocabulary: an out-of-vocabulary value returns 400 validation_error unconditionally.
  • find-similar and oppositions lose date filtering (they never had the canonical fechaPresentacion*).
  • insights keeps date filtering under the canonical fechaPresentacionDesde / fechaPresentacionHasta.
  • Everything applies identically on REST and MCP (both share the same @iris/core schemas).

old → new mapping table

# Retired (old) Canonical (new) Surface Result now
BR-1 denominacion nombre GET /v1/brands + MCP search_brands tool discarded by Zod (200)
BR-2 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta GET /v1/brands discarded by Zod (200)
BR-3 fechaDesde / fechaHasta fechaPresentacionDesde / fechaPresentacionHasta the 5 GET /v1/insights/* aggregations + their MCP tools discarded by Zod (200)
BR-4 estado as a free string estado validated against the 14-code vocabulary GET /v1/brands (array) + GET /v1/insights/* (scalar) 400 validation_error if out of vocabulary

BR-1 — denominacion → nombre

denominacion was a lower-priority alias of nombre: both fed the same text engine. The rest of the contract was already standardized on nombre (insights, matchedFields, highlight), so the canonical name is nombre and denominacion was retired.

Field-scoped search is NOT removed. These stay intact:

  • q — general text search (the 4-channel engine). Its own semantics; unaffected.
  • nombre — text search scoped to the denominación field. The canonical.

BR-2 / BR-3 — fechaDesde / fechaHasta → fechaPresentacion*

The legacy pair fechaDesde / fechaHasta was retired. Use the canonical fechaPresentacionDesde / fechaPresentacionHasta on /v1/brands and on the five insight aggregations, which are reconciled internally onto the fecha_presentacion range.

BR-4 — estado to a closed vocabulary

estado is validated against the 14 codes of the trámite lifecycle (lifecycle order):

en_tramite, observacion_de_fondo, publicada, oposicion, concedida, registrada,
esperando_renovacion, rechazada, denegada, desistida, abandonada, anulada, caducado, vencida

On /v1/brands, estado is multi-valued (array): any element out of the vocabulary triggers 400 validation_error. On insights it is scalar. In-vocabulary → 200.

find-similar and oppositions — no date filtering

The endpoints GET /v1/brands/similar, GET /v1/brands/{nro}/similar and GET /v1/oppositions/open never had the canonical fechaPresentacion*; they only exposed the legacy fechaDesde / fechaHasta. With the legacy retired, they lose date filtering entirely (an accepted decision). Adding the canonical there is a future additive step (backlog). denominacion never existed in find-similar/insights, so its retirement is naturally scoped to /v1/brands.

Silent drop of the retired parameters

The retired parameters do not produce a 400: the querystrings are not .strict(), so Zod discards a straggling denominacion / fechaDesde / fechaHasta and serves the request with the remaining filters (200, potentially broader results). Consumers have already migrated, so this behavior exposes no new data and does not break corpus neutrality.

Consumer action

  1. Use nombre instead of denominacion.
  2. Use fechaPresentacionDesde / fechaPresentacionHasta instead of fechaDesde / fechaHasta on /v1/brands and on insights.
  3. Make sure any estado you send is in the 14-code vocabulary (otherwise 400 validation_error).

For the always-current per-field detail, see the live OpenAPI reference at /docs and Versioning & deprecation.