Diseño de Contratos de Datos

¿Qué hace Diseño de Contratos de Datos?

Cuándo usarlo

• Un upstream (servicio, evento, API, archivo) alimenta pipelines posteriores y un cambio podría romperlos silenciosamente.
• Definir la interfaz entre un equipo/sistema productor y el almacén de datos.
• Agregar validación de esquema/calidad en el límite de ingesta.
• NO lo uses para cambios internos de modelo a modelo dentro de un proyecto dbt (usa tests + handling-schema-evolution).

Lo que especifica un contrato

• Esquema: campos, tipos, nulabilidad y valores permitidos.
• Semántica: qué significa cada campo y su unidad/grano.
• Garantías: frescura/SLA, expectativas de volumen, unicidad de claves.
• Propiedad: quién lo produce y a quién contactar.
• Versionado + política de cambios: cómo se comunican los cambios disruptivos.

Flujo de trabajo

- [ ] Escribe el contrato como un esquema versionado y verificado en el repositorio (no conocimiento tribal)
- [ ] Hazlo cumplir en el límite de ingesta (validar al llegar)
- [ ] Clasifica los cambios: aditivos (seguros) vs disruptivos (necesitan nueva versión)
- [ ] Ante una violación, rechaza/pon en cuarentena y alerta al productor
- [ ] Versiona y comunica los cambios disruptivos con antelación

1. Hazlo explícito y versionado. Almacena el contrato como código (JSON Schema, esquema Avro/Protobuf o una especificación YAML) junto al pipeline, revisado como cualquier API.
2. Hazlo cumplir en el límite. Valida los datos entrantes contra el contrato al llegar; rechaza o pon en cuarentena las violaciones en lugar de cargarlos.
3. Clasifica los cambios. Campos aditivos/opcionales = compatibles hacia atrás. Eliminar campos, renombrar, endurecer tipos/nulabilidad = disruptivo → nueva versión.
4. Falla ruidosamente hacia el productor, no silenciosamente río abajo.

Patrones

Contrato como JSON Schema (validado en la ingesta):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["order_id", "amount", "ordered_at"],
  "properties": {
    "order_id": { "type": "string" },
    "amount": { "type": "number", "minimum": 0 },
    "ordered_at": { "type": "string", "format": "date-time" },
    "coupon": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Punto de validación — valida cada registro al ingerir; redirige los fallos a una ubicación de cuarentena con el motivo y alerta al equipo productor. Esto convierte una rotura silenciosa río abajo en una señal inmediata y con responsable en el origen.

Registro de esquemas (Kafka/Avro) — haz cumplir la compatibilidad (BACKWARD) en el momento de publicación para que los productores no puedan enviar un esquema incompatible.

Errores comunes

• Contrato solo como documentación — si no se aplica en código, se desvía y rompe silenciosamente.
• Aplicarlo en lo profundo del almacén de datos — detecta las violaciones en el límite, antes de que los datos malos se propaguen.
• Sin versionado — cada cambio se convierte en una emergencia; versiona y depreca con gracia.
• additionalProperties sin restricción cuando se necesita rigurosidad — campos inesperados se cuelan; establécela en false donde corresponda.
• Sin propietario — un lote rechazado sin a quién llamar detiene el pipeline.
• Cambios disruptivos sin tiempo de aviso — coordina productor/consumidor mediante esquemas versionados y una ventana de desaprobación.