Contratos de datos: acuerda la forma antes de conectar dos sistemas

La mayoría de las fallas de integración no son caídas. La conexión funciona, los datos fluyen y, en algún punto más adelante, un reporte sale mal, un cliente aparece dos veces o un asistente de IA responde con una fecha corrida un día. Los dos sistemas nunca estuvieron en desacuerdo sobre si hablar. Estaban en desacuerdo sobre lo que los datos significan.

Un contrato de datos resuelve eso antes de que se mueva el primer registro. Es un acuerdo escrito y versionado entre el sistema que produce los datos y los sistemas que los consumen, y se hace cumplir en el código. Lo que ganas son integraciones que fallan el primer día, de forma visible y en un solo lugar, en vez de desviarse durante meses.

Qué cubre un contrato de datos

Un contrato útil responde las preguntas que las integraciones suelen dejar sin resolver:

• Esquema. Cada campo, su tipo y su formato. “Monto” es un decimal en una moneda definida, no un texto que a veces trae una coma.
• Campos obligatorios y opcionales. Qué campos deben venir siempre, cuáles pueden venir vacíos y qué significa vacío: desconocido, no aplica y cero son tres cosas distintas.
• Identificadores. Qué ID es la llave estable de cada registro, quién lo emite y si puede cambiar alguna vez. Los correos y los nombres no son IDs.
• Fechas y zonas horarias. Cada fecha lleva su zona horaria, o el contrato fija una (UTC es lo habitual). También dice qué registra cada fecha: cuándo pasó el evento, cuándo se ingresó o cuándo se modificó por última vez.
• Enumeraciones. La lista completa de valores permitidos para estados, tipos y etapas, y qué debe hacer quien consume cuando encuentra un valor que no conoce.
• Versionado. Cómo se numeran los cambios, cuáles son compatibles (agregar un campo opcional) y cuáles rompen (renombrar, quitar o cambiar el significado de un campo).
• Dueño. Quién es responsable del contrato, a quién hay que avisar antes de un cambio y con cuánta anticipación.

El formato importa menos que el hábito. JSON Schema, OpenAPI, modelos tipados en el código o una tabla bien mantenida sirven, siempre que el contrato viva junto al código y ambos lados lo puedan leer.

Pruebas de contrato: el acuerdo, verificado en cada cambio

Un contrato que solo vive en un documento se va a romper en el siguiente sprint. Las pruebas de contrato lo convierten en algo que un pipeline puede verificar. Las pruebas del productor confirman que lo que emite cumple el contrato. Las del consumidor confirman que maneja cada forma válida, incluidos los campos opcionales vacíos y los valores de enumeración que nunca ha visto. Cuando cualquiera de los dos lados cambia, el build falla antes de que el cambio llegue a producción, que es el momento más barato para enterarte.

Falla de forma visible en la frontera

Toda integración tiene una frontera: el punto donde los datos de afuera entran a tu sistema. Ahí es donde se debe hacer cumplir el contrato. Un registro que no cumple se rechaza o se pone en cuarentena en ese punto, con un error claro que nombra la fuente, el registro y el campo.

La alternativa es aceptarlo en silencio. A un ID faltante se le pone un valor por defecto, un estado desconocido se mapea a “otro”, una fecha sin zona horaria se lee como hora local. Cada decisión parece inofensiva. Juntas, riegan errores en cada reporte, tablero y modelo que lee esos datos, donde son mucho más difíciles de rastrear. Un rechazo visible en el borde cuesta minutos; un error silencioso descubierto semanas después cuesta una investigación.

Por qué la IA depende de esto

Un asistente de IA o un modelo de puntuación es tan confiable como el contexto que le das. Si “cerrado” significa ganado en un sistema y perdido en otro, el modelo va a razonar con total seguridad sobre una contradicción. Si las fechas mezclan zonas horarias, su respuesta a “qué pasó ayer” está mal para una parte de los datos. Los modelos no señalan estos problemas; los disimulan.

Los contratos de datos son la forma más barata de darle a la IA un contexto consistente: la forma, el significado y la identidad de cada registro quedan resueltos antes de que el modelo lo lea. Es el mismo trabajo de normalización que describimos en IA con tus datos, hecho explícito y exigible.