Deprecar un campo en una API de multas: cómo se avisa

Retirar una propiedad de una respuesta es una línea de código. Avisarlo decide si el cambio será una migración ordenada o un incidente en la flota que consume esos datos. La diferencia rara vez está en la fecha elegida: está en si el aviso llegó a tiempo a un lugar donde alguien pudiera verlo.

Llamamos deprecar un campo a declarar que una propiedad de la respuesta —el importe de un acta, su estado, el código de la jurisdicción— dejará de sostenerse, abriendo un plazo para reemplazarla. No es borrarla: durante ese plazo el campo sigue viajando. La dificultad aparece al buscar dónde poner el aviso: los mecanismos estandarizados de HTTP hablan de recursos y un campo no es un recurso.

Tres cambios que se anuncian igual y duelen distinto

Bajo la misma palabra conviven situaciones diferentes:

• el campo desaparece de la respuesta;
• el campo sigue presente pero deja de actualizarse;
• el campo conserva el nombre y cambia de significado.

El primero rompe temprano: un cliente estricto falla al validar o no encuentra el valor. El segundo rompe en silencio: el dato sigue ahí y sólo envejece. El tercero es el peor porque no falla nada: estado decía si el acta estaba paga y ahora describe la etapa del expediente, y la integración informa otra cosa con el mismo nombre.

El aviso tiene que decir cuál de los tres es. Si el importe pasará a ser nulo antes de desaparecer —como en un acta que todavía no tiene monto—, esa etapa intermedia también forma parte del contrato, con la precisión de null, ausente o cero.

Deprecation y Sunset hablan del recurso

RFC 9745 define el campo de respuesta Deprecation, cuyo valor indica cuándo el recurso fue o será declarado obsoleto; esa fecha puede estar en el futuro. RFC 8594 define Sunset, con el momento en que se espera que el recurso deje de responder. Las dos aplican al recurso que devolvió la respuesta, no a una propiedad suya.

Lo aprovechable para un campo está en el enlace. RFC 9745 registra una relación deprecation hacia documentación pensada para que la lea una persona, y RFC 8594 una relación sunset hacia la información sobre la política de retiro. El encabezado fecha el recurso entero; qué propiedad se retira vive en el documento enlazado.

Marcar todo el endpoint como obsoleto porque cambia una propiedad le avisa a la flota que su consulta de infracciones entera caduca: si el recurso sigue vigente, la señal es documental, no de transporte.

Dónde vive el aviso y qué dice

El esquema declara la intención

OpenAPI declara obsoletas operaciones, parámetros y encabezados, pero una propiedad de la respuesta se marca en el esquema. Ahí deprecated es una anotación del vocabulario de metadatos de JSON Schema 2020-12: indica que conviene dejar de usar esa propiedad y que puede llegar a eliminarse. No cambia la validación ni compromete el retiro.

Eso la vuelve necesaria e insuficiente: un generador de clientes o una prueba de contrato pueden leerla y advertir antes del despliegue, pero quien escribió su parser a mano copiando una respuesta de ejemplo con dos actas no vuelve a mirar la especificación.

El contenido mínimo del anuncio

Un aviso accionable incluye:

• el campo, con su ruta completa dentro de la respuesta;
• cuál de los tres cambios se aplica;
• el reemplazo y cómo se traduce el valor viejo al nuevo;
• desde cuándo rige el aviso y desde cuándo el cambio;
• qué ocurre con quien no llegue a la fecha.

Un aviso sin reemplazo no es una deprecación: es un retiro con preaviso, y conviene nombrarlo así. Si no hay sucesor porque la jurisdicción dejó de publicar el dato, decilo: el consumidor necesita cambiar su proceso, no su parser.

Saber quién todavía lo lee

Acá está la parte incómoda: una respuesta no revela qué propiedades usó el cliente, porque el servidor observa la consulta, no el consumo. Que baje el tráfico agregado tampoco prueba desuso, porque una flota que barre sus patentes una vez por mes sigue dependiendo del campo.

Hay maneras de convertir esa suposición en evidencia: pedir que la solicitud nombre los campos que quiere, para que el uso quede declarado; versionar el contrato por consumidor; y probar la respuesta sin el campo contra los fixtures de cada cliente. Ninguna reemplaza al aviso directo: con una lista de consumidores acotada, preguntar es lo más barato y lo único que devuelve un plazo negociado.

La fecha se cumple o se corre, pero se dice

El día del cambio, el equipo debería poder volver atrás. Un retiro irreversible no es una deprecación sino una migración, y necesita otra preparación. Si el plazo se extiende, eso también se anuncia: una fecha que se mueve en silencio enseña a ignorar la siguiente.

Después del apagado queda el registro: qué campo, qué fecha se anunció, qué fecha se aplicó y qué lo reemplazó. Ese historial permite explicar meses después por qué el informe de multas de marzo y el de agosto no dicen lo mismo sobre la misma acta, un problema emparentado con cómo versionar una respuesta.

Antes de publicar el anuncio, verificá que el campo sucesor ya esté disponible y documentado; que la especificación marque el viejo; que la fecha sea sostenible; y que exista forma de revertir. Si alguna falta, el aviso genera trabajo en el consumidor sin ofrecerle una salida.

Metodología

Alcance

Comunicación del retiro o cambio de una propiedad dentro de una respuesta de API de infracciones, con foco en el anuncio y su verificación, no en la estrategia de versionado ni en la implementación del cambio.

Unidad de análisis

Un campo del contrato público y el ciclo que va del anuncio a la fecha efectiva, con sus consumidores conocidos.

Cobertura

Señales estandarizadas de HTTP para deprecación y retiro con sus relaciones de enlace, y la anotación `deprecated` de OpenAPI y de JSON Schema 2020-12; no cubre políticas contractuales ni acuerdos de nivel de servicio de un proveedor concreto.

Limitaciones

• Los plazos razonables dependen del ciclo de despliegue de cada consumidor y no se derivan de las especificaciones citadas.
• Las señales de transporte describen recursos; el detalle por campo queda en documentación y esquema, cuya lectura por parte del cliente no puede garantizarse.
• La nota no evalúa herramientas de diff de esquemas ni portales de desarrolladores específicos.

Fuentes

• RFC 9745 — Deprecation HTTP Response Header Field — RFC Editor (consultada el 2026-08-29)
• RFC 8594 — Sunset HTTP Header Field — RFC Editor (consultada el 2026-08-29)
• OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el 2026-08-29)
• JSON Schema Validation 2020-12 — JSON Schema (consultada el 2026-08-29)

Preguntas frecuentes

¿Deprecar un campo es lo mismo que eliminarlo?

No. Deprecar es declarar que el campo dejará de sostenerse y abrir un plazo para reemplazarlo; durante ese plazo la respuesta lo sigue incluyendo. Eliminarlo es el final del proceso, no su comienzo.

¿Puedo usar el encabezado Deprecation para avisar sobre un solo campo?

RFC 9745 define esa señal para un recurso, no para una propiedad. Marcar el endpoint completo cuando sólo cambia un campo le avisa al consumidor que toda su integración caduca. Para un campo, el aviso pertenece a la documentación enlazada y a la especificación.

¿Alcanza con marcar el campo como deprecated en la especificación?

En JSON Schema 2020-12, `deprecated` es una anotación: dice que conviene dejar de usar la propiedad y que puede llegar a eliminarse, sin cambiar la validación ni comprometer el retiro. Un generador de clientes o un test de contrato pueden leerla y advertir antes del despliegue; quien escribió su parser a mano copiando una respuesta de ejemplo, no. Es necesario, pero no suficiente.

¿Cómo sé qué clientes siguen usando el campo?

La respuesta no revela qué propiedades consumió el cliente, así que el uso hay que declararlo o probarlo. Ayudan la selección explícita de campos en la solicitud, el contrato versionado por consumidor y las pruebas contra fixtures de cada cliente. Cuando la lista de consumidores es acotada, preguntar sigue siendo lo más barato.

Notas relacionadas