Data Contracts: What They Are, Why They Matter, and How to Use Them

Introducción

Hola a todos, soy Jochen, de Ansbach, cerca de Núremberg. Hoy vamos a hablar de Data Contracts, un tema que se ha puesto muy de moda. Veremos qué es un Data Contract, repasaremos algunos ejemplos, exploraremos las herramientas que puedes usar y comentaremos por qué los Data Contracts se han vuelto tan importantes.

Trabajo en Entropy Data, un spin-off de INNOQ. Nuestro negocio principal es desarrollar software para gestionar productos de datos con Data Contracts, una plataforma de gestión de metadatos. Además mantenemos dos herramientas open source: el Data Contract Editor, una interfaz web para trabajar con Data Contracts, y la Data Contract CLI, para probarlos.

Vengo de la ingeniería de software: Java es mi lengua materna. Hace unos cinco años nos metimos de lleno en el mundo de los datos, preguntándonos cuál sería la siguiente gran cosa en IT. El cloud ya estaba hecho, las arquitecturas orientadas a eventos también, y el Domain-Driven Design estaba por todas partes. Concluimos que los datos y la IA serían lo de mayor impacto. Eso nos llevó al Data Mesh y, al final, a traducir al alemán el libro Data Mesh de Zhamak Dehghani para O'Reilly.

¿Dónde están vuestras APIs?

Viniendo del mundo del software, lo primero que preguntábamos siempre a la gente de datos era: «¿Dónde están vuestras APIs?». Y la respuesta siempre era: «Mira en el catálogo de datos». Así que mirábamos, y al principio no encontrábamos nada, y cuando encontrábamos algo, no lo entendíamos.

Entonces PayPal publicó la primera plantilla de Data Contract. Nos gustó la idea, pero pensamos que podía parecerse más a OpenAPI/Swagger. Hicimos una propuesta y acabamos uniendo fuerzas para crear el proyecto BITOL dentro de la Linux Foundation, donde hoy gobernamos y hacemos evolucionar el Open Data Contract Standard (ODCS).

Formo parte del Technical Steering Committee. Así que si falta algo o algo no tiene sentido, dínoslo y lo podemos mejorar.

Un documento YAML, como OpenAPI pero para datos

Un Data Contract es, sorpresa, un documento YAML. ¿Por qué YAML? Por Kubernetes: en Kubernetes todo es YAML. Y OpenAPI/Swagger también es un documento YAML. Describe qué caracteriza a un conjunto de datos que quiero compartir con otros.

En un contexto de Data Mesh tienes un equipo responsable de un conjunto de datos, el equipo donde los datos se originan, por ejemplo en un microservicio, un sistema ERP o un dominio de negocio. Ese equipo asume la propiedad del producto de datos que se comparte con otros equipos. Los demás equipos quieren acceder a él para analítica, para construir servicios, aplicaciones de IA o productos de datos agregados.

El Data Contract define la interfaz hacia los consumidores. Es relevante cuando intercambias datos entre equipos y unidades organizativas. Importante: se trata de una relación de uso, no de un pipeline ETL. Otros equipos acceden a mis datos o los consumen. Conceptualmente es una dependencia de uso, algo distinto de los pipelines de datos clásicos.

Y para los desarrolladores de software que se ponen nerviosos al ver una tabla de base de datos: no me refiero en absoluto a exponer directamente la base de datos Oracle o Postgres. Siempre hay una capa anticorrupción, una vista, que desacopla el modelo de datos del sistema operacional.

El Open Data Contract Standard (ODCS)

ODCS es hoy, creo, el estándar del sector en el que todo el mundo ha convergido. Collibra, OpenMetadata, IBM: todos los grandes proveedores de metadatos están adoptando ODCS. Por favor, si introduces Data Contracts, no inventes un formato propietario. Usa ODCS para aprovechar el ecosistema y las herramientas, y para seguir siendo interoperable con capas de metadatos y catálogos de datos.

El año pasado se creó también la Open Data Product Specification (ODPS) en la Linux Foundation. Un producto de datos es el sistema o módulo que produce los datos, con input ports, un pipeline, pruebas, metadatos y documentación, y que al final ofrece un conjunto de datos a través de un output port con un Data Contract concreto. El producto de datos es el sistema; el contrato es la especificación de interfaz del conjunto de datos final.

Dos formas de construir Data Contracts

Data first es el enfoque más habitual. Ya tienes una tabla o un esquema en tu data warehouse. Ahora quieres añadirle un contrato: documentarlo, describirlo, especificar atributos de calidad, para que tus consumidores entiendan qué es ese conjunto de datos. Pones un contrato encima de datos que ya existen.

Contract first es menos frecuente, pero muy potente. Partes de las necesidades de tus usuarios de negocio y de tus consumidores. ¿Qué datos necesitan realmente? ¿Cómo debería ser el modelo de datos para cubrir sus casos de uso? Después diseñas el producto de datos para que encaje con esas necesidades. Así salen productos de datos más pequeños y enfocados, en lugar de tablas con 10.000 columnas porque nadie quería tirar nada.

Un apunte importante: los usuarios no saben leer ni escribir YAML. Vamos a ver herramientas que lo hacen mucho más accesible, incluidas plantillas de Excel.

Ejemplo guiado: un Data Contract de pedidos

Veamos un ejemplo concreto. En una tienda online, un equipo de Checkout gestiona los datos de pedidos y clientes. Un equipo de Recomendaciones quiere construir un modelo de machine learning. Así que hacemos un taller contract-first con Sophia, la data scientist:

«Como data scientist, quiero todos los pedidos de la tienda online de los últimos cinco años, para saber qué artículos o categorías compra junto un mismo cliente y poder construir un modelo de recomendación para la tienda y para los emails de marketing.»

La propiedad es la parte más difícil. ¿Qué equipo asume la responsabilidad de proporcionar el conjunto de datos de pedidos? Esta pregunta se lleva muchas veces el 50 % del trabajo. Hemos cancelado talleres porque nadie quería hacerse cargo del producto de datos. Sin propiedad, todo lo demás (semántica, calidad, niveles de servicio) sobra.

Esquema, semántica y ejemplos

El corazón de un Data Contract es el modelo de datos. Defines esquemas con tablas y columnas. Pero no es solo información técnica: también incluye los nombres y descripciones de negocio que usaría una persona del negocio. ¿Dicen «Order ID», «Bestellnummer» o «número de pedido»? Recogemos tanto el nombre técnico como el de negocio.

Esa descripción semántica es algo que la IA no te puede generar. Solo la consigues hablando con tus expertos de dominio, escuchando cómo hablan entre ellos y anotándolo. Esa es la mejor fuente de buenos metadatos.

Los ejemplos son clave. En los talleres escribimos ejemplos ligeramente equivocados a propósito, porque a la gente le encanta corregir. Un experto de dominio dirá: «¿Cuatro decimales? Eso no puede ser». Y ahí descubres si los importes se guardan en dólares, en euros, como enteros en céntimos o como doubles. Las preguntas típicas que siempre han dado dolores de cabeza.

Si nadie corrige tus ejemplos, es que tu audiencia se ha dormido.

Reglas de calidad

Las reglas de calidad se pueden recoger al principio como texto plano, una descripción de lo que esperan los consumidores. Por ejemplo: «La fecha de entrega no debería estar a más de 20 días vista». Captura primero las expectativas de negocio, en lenguaje natural.

Después conviértelas en consultas SQL. La IA te puede ayudar con eso. Lo esencial es capturar la lógica de negocio. Una vez que tienes el SQL, puedes usarlo para verificar la calidad de tus productos de datos y conjuntos de datos, algo parecido a lo que hacen herramientas como Great Expectations.

La historia de John y el filtro de consentimiento

Una hora después de empezar el taller, John, el product owner del equipo de Checkout, se acuerda de repente: «Perdón, no os podemos dar todos los pedidos. Hay una restricción de consentimiento: solo un 80 % de los pedidos tiene el consentimiento de cookies para uso analítico».

Sophia, la data scientist, responde: «Sin problema, el machine learning es difuso de todas formas, con un 80 % me vale». Pero esa información tiene que entrar en el Data Contract, dentro de las limitaciones. Este conjunto de datos está aprobado para uso analítico, pero no sirve para KPIs financieros, porque solo representa alrededor del 80 % de la facturación.

Este tipo de limitaciones sencillamente no se ven cuando miras la tabla en el data warehouse. Necesitas los metadatos del contrato para recogerlas.

Las condiciones de uso son cada vez más importantes, sobre todo para la IA. Poder decirle a un agente qué puede y qué no puede hacer con un conjunto de datos, y para qué fines es adecuado, resulta crítico para la gobernanza. También puedes enlazar políticas estándar como el RGPD, políticas de clasificación de datos o reglas para datos de marketing.

Niveles de servicio y garantías no funcionales

Un Data Contract también puede incluir aspectos no funcionales: disponibilidad, latencia, horario de soporte, retención y garantías de backup. En cada sesión alguien pregunta: «¿Puedo usar este conjunto de datos para mi microservicio operacional?». La respuesta: define las garantías en el contrato y deja que el consumidor decida si le bastan para su caso de uso.

Nadie construiría una tienda online que dependa de un sistema con solo un 99,8 % de disponibilidad. Como mínimo, añadiría una capa anticorrupción o un desacoplamiento asíncrono. La información de SLA del contrato ayuda a los consumidores a tomar esa decisión.

Por qué el nombre está mal y por qué se quedó

Una cosa que un Data Contract no contiene son las partes, es decir, los consumidores. Tenemos al owner, pero no a quién consume. En derecho mercantil, un contrato es una declaración vinculante bilateral. Ese carácter bilateral aquí no existe. En realidad es una especificación de interfaz.

En términos jurídicos se parece más a una invitatio ad offerendum, una invitación a hacer una oferta. ¿Y por qué se llama entonces «contract»? Porque PayPal acuñó el término primero y el nombre se quedó. Es pegadizo. Se recuerda bien. Simplemente no es técnicamente correcto.

La relación bilateral se gestiona aparte, mediante agreements en las herramientas, con fecha de inicio, fecha de fin y gestión del ciclo de vida. Ahí es donde vive la relación 1:1 entre proveedor y consumidor.

Productos de datos y Data Contracts

Un producto de datos tiene una parte privada y una parte pública. Por dentro hay pipelines, código de transformación, tablas intermedias, tablas en bruto y pruebas. Al final expones un conjunto de datos concreto para que lo consuman otros equipos: esa es la parte pública, el output port.

El Data Contract describe exactamente ese output port. El producto de datos es el sistema que vive en la plataforma; el contrato es la interfaz que describe cómo son los datos y qué garantías los acompañan. Están fuertemente acoplados.

Data Contract Editor

El Data Contract Editor es una aplicación web open source que puedes desplegar en local como contenedor Docker. Puedes escribir YAML directamente, pero también usar formularios para introducir condiciones de uso, información de servidores y definiciones de esquema. Ofrece modelado visual de datos, tipo modelado ER, parecido a Innovator u otras herramientas a las que la gente está acostumbrada.

Al final produce YAML. Puedes previsualizarlo en HTML, validarlo y lanzar pruebas para verificar que el producto de datos que hay detrás del contrato se ajusta a sus definiciones.

Plantilla de Excel: de Excel no te escapas

Creamos una plantilla de Excel porque al menos tres clientes nos dijeron: «Todo genial, pero nosotros hemos introducido Excel para trabajar con la gente de negocio». Como informáticos, costaba aceptarlo. Pero para mucha gente Excel sigue siendo la mejor experiencia de usuario. Lo puedes mandar por correo. Y los datos de origen muchas veces ya están en Excel.

La plantilla cumple el estándar y convierte a YAML y desde YAML en ambos sentidos. De Excel no te vas a librar, así que al menos que sea un buen Excel.

Data Contract CLI e integración en el pipeline

La Data Contract CLI toma toda la información del YAML (tipos de campo, formatos, reglas de calidad en SQL o Great Expectations), se conecta a la base de datos y verifica que los datos cumplen las garantías del contrato. Ejecuta sentencias SQL para cada aspecto e informa de si pasa o falla.

Integrar esto en tu pipeline de despliegue, por ejemplo en un workflow de GitHub Actions, te da mucha más confianza en tus datos. Puedes reaccionar rápido cuando algo se pone en rojo. Y los consumidores pueden ejecutar las mismas comprobaciones en sus input ports antes de lanzar sus pipelines.

La CLI habla con todas las grandes plataformas de datos (BigQuery, Snowflake, Databricks, Postgres y más) y puede importar y exportar en distintos formatos.

Comunicación, confianza y descubribilidad

Comunicación: los Data Contracts te dan un formato estructurado para juntar a las personas, productores y consumidores, y hablar de requisitos de datos, conocimiento de dominio y semántica. Guían la conversación por los aspectos importantes: condiciones de uso, SLAs, reglas de calidad. No subestimes esta faceta de transformación del negocio dentro de la organización.

Confianza: los datos solo se usan cuando los consumidores creen que son correctos y completos. La confianza se pierde con facilidad: después de que el pipeline se rompa por tercera vez, la gente deja de creer en los datos. Ya conoces el clásico: un KPI, tres valores distintos. ¿Cuál es el bueno? Los Data Contracts ayudan con una semántica clara y comprobaciones de calidad automatizadas.

Descubribilidad: cuando recoges los Data Contracts y las especificaciones de productos de datos en un sitio central, obtienes una visión muy potente de todos los datos disponibles en tu organización. A diferencia de los catálogos de datos tradicionales, que escanean cada tabla en bruto e intermedia, un marketplace de datos construido sobre productos de datos muestra solo conjuntos gestionados y curados que están pensados para consumirse: muchos menos artefactos y mucha más calidad.

Los agentes necesitan datos corporativos y gobernanza

Los clientes de IA (ChatGPT, Claude, sistemas de agentes autónomos) pueden responder «¿A qué distancia está la Luna de la Tierra?» sin datos corporativos. Pero para tareas de negocio con sentido necesitan acceso a los datos de tu organización: clientes, pedidos, finanzas.

Para que eso funcione de forma segura, los agentes necesitan varias herramientas:

• Búsqueda: descubrir qué productos de datos existen (datos de clientes, pedidos, etc.).
• Evaluación: valorar si la semántica y los modelos de datos encajan con la pregunta.
• Consulta: a partir del esquema, una IA puede escribir SQL automáticamente y consultar los datos.
• Gobernanza: controlar qué agentes tienen acceso, verificar la identidad (contexto de usuario frente a cuenta de servicio), aplicar las condiciones de uso y las políticas globales, y ejecutar comprobaciones de seguridad.

Esta es exactamente la arquitectura que implementamos con nuestro servidor MCP de Entropy Data. Un agente hace una pregunta de negocio, el servidor MCP busca en el marketplace de datos, recupera el Data Contract con todos sus metadatos, evalúa el esquema, solicita acceso y genera el SQL. El Data Contract, con sus condiciones de uso, sus reglas de calidad y su semántica, se convierte en la capa de gobernanza que hace que todo esto sea seguro y controlado.

Demo en vivo: un agente de IA se encuentra con los Data Contracts

En la demo le pregunto a Claude: «¿Quiénes son nuestros mejores clientes?». El servidor MCP de Entropy tiene tres herramientas: search, fetch y query. Claude extrae un término de búsqueda, busca en el marketplace de datos, encuentra los productos de datos que encajan y recupera el contrato completo, incluidos el esquema y los metadatos.

A partir del esquema, con campos como «Total Spend» y «Average Order Value», genera SQL automáticamente, consulta los datos y devuelve la respuesta. Todo gobernado a través del Data Contract: el control de acceso, las condiciones de uso y las garantías de calidad se aplican de principio a fin.