Conocimiento

¿Qué es un Data Contract?

Diagrama de un Data Contract con el proveedor de datos, el Data Contract y el consumidor de datos

Un Data Contract es un documento que define la propiedad, la estructura, la semántica, la calidad y las condiciones de uso del intercambio de datos entre un Data Producer y sus consumidores. Piensa en una API, pero para datos.

¿Por qué Data Contracts?

A las organizaciones les cuesta mantener buenos metadatos y sufren pipelines de datos frágiles que se rompen con cualquier cambio aguas arriba, una comunicación deficiente entre Data Producers y Data Consumers, y equipos de datos desbordados por peticiones que compiten entre sí. Los Data Contracts resuelven estos problemas fijando expectativas explícitas sobre los datos en estas dimensiones:

  • Propiedad: quién responde de que los datos sean correctos
  • Esquema: nombres de columnas, tipos de datos, estructura
  • Semántica: descripciones y significado de negocio
  • Calidad: reglas de validación, frescura, completitud
  • Condiciones de uso: derechos de uso, SLA, políticas de acceso

Los Data Contracts son una herramienta de comunicación: expresan un entendimiento común sobre cómo deben estructurarse e interpretarse los datos. Se pueden redactar de forma conjunta entre el proveedor y el consumidor, incluso antes de implementar el producto de datos, lo que se conoce como enfoque contract-first. En desarrollo y en producción sirven de base para la generación de código, las pruebas, la validación de esquemas, los controles de calidad, la monitorización y la gobernanza computacional, de modo que los productos de datos cumplan lo acordado.

Open Data Contract Standard (ODCS)

El Open Data Contract Standard (ODCS) es el estándar abierto para definir Data Contracts en un formato YAML legible por máquinas. Nació en PayPal como Data Contract Template y hoy lo gobierna Bitol, un proyecto de Linux Foundation AI & Data.

Este es un ejemplo simplificado de un Data Contract en ODCS: 

apiVersion: v3.1.0
kind: DataContract
id: orders
name: Orders
version: 1.0.0
status: active
description:
  purpose: "Provides order and line item data for analytics and reporting"
  usage: "Used by analytics team for sales analysis and business intelligence"
  limitations: "Contains only the last 2 years of data"
  customProperties:
    - property: "sensitivity"
      value: "secret"
      description: "Data contains personally identifiable information"
  authoritativeDefinitions:
    - url: "https://entropy-data.com/policies/gdpr-compliance"
      type: "businessDefinition"
      description: "GDPR compliance policy for handling customer data"
schema:
  - name: orders
    physicalType: TABLE
    description: All historic web shop orders since 2020-01-01. Includes successful and cancelled orders.
    properties:
      - name: order_id
        logicalType: string
        description: The internal order id for every orders. Do not show this to a customer.
        businessName: Internal Order ID
        physicalType: UUID
        examples:
          - 99e8bb10-3785-4634-9664-8dc79eb69d43
        primaryKey: true
        classification: internal
        required: true
        unique: true
      - name: customer_id
        logicalType: string
        description: A reference to the customer number
        businessName: Customer Number
        physicalType: TEXT
        examples:
          - c123456789
        required: true
        unique: false
        logicalTypeOptions:
          minLength: 10
          maxLength: 10
        authoritativeDefinitions:
          - type: definition
            url: https://example.com/definitions/sales/customer/customer_id
        tags:
          - pii:true
        classification: internal
        criticalDataElement: true
      - name: order_total
        logicalType: integer
        description: The order total amount in cents, including tax, after discounts.
          Includes shipping costs.
        physicalType: INTEGER
        examples:
          - "9999"
        quality:
          - type: text
            description: The order_total equals the sum of all related line items.
        required: true
        businessName: Order Amount
      - name: order_timestamp
        logicalType: timestamp
        description: The time including timezone when the order payment was successfully
          confirmed.
        physicalType: TIMESTAMPTZ
        businessName: Order Date
        examples:
          - "2025-03-01 14:30:00+01"
      - name: order_status
        businessName: Status
        description: The business status of the order
        logicalType: string
        physicalType: TEXT
        examples:
          - shipped
        quality:
          - type: library
            description: Ensure that there are no other status values.
            metric: invalidValues
            arguments:
              validValues:
                - pending
                - paid
                - processing
                - shipped
                - delivered
                - cancelled
                - refunded
            mustBe: 0
    quality:
      - type: library
        metric: rowCount
        mustBeGreaterThan: 100000
        description: If there are less than 100k rows, something is wrong.
  - name: line_items
    physicalType: table
    description: Details for each item in an order
    properties:
      - name: line_item_id
        logicalType: string
        description: Unique identifier for the line item
        physicalType: UUID
        examples:
          - 12c9ba21-0c44-4e29-ba72-b8fd01c1be30
        logicalTypeOptions:
          format: uuid
        required: true
        primaryKey: true
      - name: sku
        logicalType: string
        businessName: Stock Keeping Unit
        description: Identifier for the purchased product
        physicalType: TEXT
        examples:
          - 111222333
        required: true
      - name: price
        logicalType: integer
        description: Price in cents for this line item including tax
        physicalType: INTEGER
        examples:
          - 9999
        required: true
      - name: order_id
        required: false
        primaryKey: false
        logicalType: string
        physicalType: UUID
        relationships:
          - type: foreignKey
            to: orders.order_id
servers:
  - server: production
    environment: prod
    type: postgres
    host: aws-1-eu-central-2.pooler.supabase.com
    port: 6543
    database: postgres
    schema: dp_orders_v1
team:
  name: sales
  description: This data product is owned by the "Sales" team
  members:
    - username: john@example.com
      name: John Doe
      role: Owner
  authoritativeDefinitions:
    - type: slack
      url: https://slack.example.com/teams/sales
roles:
  - role: analyst_us
    description: Read access for analytics to US orders
  - role: analyst_eu
    description: Read access for analytics to EU orders
slaProperties:
  - property: availability
    value: 99.9%
    description: Data platform uptime guarantee
  - property: retention
    value: "1"
    unit: year
    description: Data will be deleted after 1 year
  - property: freshness
    value: "24"
    unit: hours
#    element: orders.order_timestamp # enable this to check freshness with Data Contract CLI
    description: Within 24 hours of order placement
  - property: support
    value: business hours
    description: Support only during business hours
price:
  priceAmount: 0
  priceCurrency: USD
  priceUnit: monthly
tags:
  - e-commerce
  - transactions
  - pii
customProperties:
  - property: dataPlatformRole
    value: role_orders_v1
contractCreatedTs: "2025-01-15T10:00:00Z"

Consulta la especificación completa, más ejemplos y las herramientas disponibles en datacontract.com.

Herramientas

La Data Contract CLI es una herramienta de línea de comandos open source para trabajar con Data Contracts. Analiza y valida contratos, se conecta a las fuentes de datos para ejecutar pruebas de esquema y de calidad, detecta cambios incompatibles en tus pipelines de CI/CD y exporta a distintos formatos.

El Data Contract Editor de Entropy Data es un editor en el navegador para redactar Data Contracts con vista previa y validación en tiempo real.

Gestiona tus Data Contracts con Entropy Data

Entropy Data es una plataforma web para gestionar productos de datos, Data Contracts y acuerdos de uso de datos en modo self-service. Una API basada en eventos permite integrarla con cualquier plataforma de datos, y cada cambio queda registrado en una pista de auditoría.

Captura de pantalla de un Data Contract en Entropy Data

Incluye un catálogo de productos de datos, flujos de solicitud y aprobación de acuerdos de uso, gestión automatizada de permisos y una visualización de tu Data Mesh como mapa interactivo.

Empieza gratis o explora la demo interactiva.