Connaissances
Qu'est-ce qu'un Data Contract ?
Un Data Contract est un document qui définit la propriété, la structure, la sémantique, la qualité et les conditions d'utilisation des données échangées entre un Data Producer et ses Data Consumers. Voyez-le comme une API, mais pour les données.
Pourquoi des Data Contracts ?
Les organisations peinent à obtenir de bonnes métadonnées. Leurs pipelines de données restent fragiles et cassent au moindre changement en amont, la communication entre Data Producers et Data Consumers est défaillante, et les Data Engineers croulent sous des demandes contradictoires. Les Data Contracts résolvent ces problèmes en rendant explicites les attentes portant sur les données, selon ces dimensions :
- Propriété : la responsabilité de fournir des données correctes
- Schéma : noms de colonnes, types de données, structure
- Sémantique : descriptions et signification métier
- Qualité : règles de validation, fraîcheur, complétude
- Conditions d'utilisation : droits d'usage, SLA, politiques d'accès
Les Data Contracts sont avant tout un outil de communication : ils formalisent une compréhension partagée de la façon dont les données doivent être structurées et interprétées. Producteur et consommateur peuvent les rédiger ensemble, avant même que le produit de données ne soit implémenté : c'est l'approche contract-first. En développement comme en production, ils servent ensuite de base à la génération de code, aux tests, à la validation des schémas, aux contrôles qualité, au monitoring et à la gouvernance automatisée, afin de garantir que les produits de données respectent les attentes convenues.
Open Data Contract Standard (ODCS)
L'Open Data Contract Standard (ODCS) est le standard ouvert qui permet de définir des Data Contracts dans un format YAML lisible par une machine. Développé à l'origine chez PayPal sous le nom de Data Contract Template, il est aujourd'hui piloté par Bitol, un projet Linux Foundation AI & Data.
Voici un exemple simplifié de Data Contract 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"
Pour approfondir la spécification complète, les exemples et l'outillage, rendez-vous sur datacontract.com.
Outillage
La Data Contract CLI est un outil en ligne de commande open source dédié aux Data Contracts. Elle vérifie et valide les contrats, se connecte aux sources de données pour exécuter des tests de schéma et de qualité, détecte les changements cassants dans vos pipelines CI/CD et exporte vers de nombreux formats.
Le Data Contract Editor d'Entropy Data est un éditeur accessible depuis le navigateur pour rédiger des Data Contracts, avec aperçu et validation en temps réel.
Gérer vos Data Contracts avec Entropy Data
Entropy Data est une plateforme web qui vous permet de gérer en self-service vos produits de données, vos Data Contracts et vos accords d'utilisation des données. Une API événementielle assure une intégration fluide avec n'importe quelle plateforme de données, et chaque modification est consignée dans une piste d'audit.
Au programme : un catalogue de produits de données, des workflows de demande et d'approbation pour les accords d'utilisation, la gestion automatisée des permissions et la visualisation de votre Data Mesh sous forme de carte interactive.
Commencer gratuitement, ou explorer la démo interactive.