Un identifiant de commande s’appelle order_id. L’équipe qui produit la donnée le renomme id, adapte son export et relance ses tests. Tout passe. Dans l’équipe finance, le traitement qui attend encore order_id échoue.
Les deux équipes n’ont pas testé la même chose. La première a vérifié sa nouvelle version. La seconde dépendait de la précédente. Une donnée peut être valide et avoir cessé d’être compatible avec ses consommateurs.
C’est un problème auquel les data contracts peuvent répondre. Encore faut-il préciser ce que l’on garantit, qui s’engage et à quel endroit un changement incompatible sera bloqué. Un fichier YAML rangé dans un dépôt ne protège aucun tableau de bord à lui seul.
Nous allons partir de ce cas, construire un contrat de données minimal et reproduire trois situations : un doublon détecté, un renommage incompatible et une erreur d’unité qui passe malgré les tests. L’atelier téléchargeable a été exécuté sur des données synthétiques pour préparer cet article.
Qu’est-ce qu’un data contract, concrètement ?
Un data contract, ou contrat de données, formalise les attentes entre une équipe qui fournit des données et celles qui les utilisent. Il peut préciser la structure, le sens des champs, les règles de qualité, les responsabilités et les conditions de mise à disposition.
Prenons un export de commandes. Le contrat précise qu’une ligne représente une commande, que son identifiant est présent et unique, que son montant est exprimé en euros TTC hors livraison, et qu’une équipe identifiée répond des changements. Les consommateurs peuvent alors construire leur traitement à partir d’engagements explicites.
L’Open Data Contract Standard, ODCS propose un format ouvert pour décrire ces informations. Le standard et l’outil qui exécute les contrôles sont deux choses distinctes. Dans notre exemple, le contrat utilise ODCS 3.2.0 et son exécution repose sur Data Contract CLI 1.2.1.
Cette version de l’outil est figée pour rendre l’atelier reproductible ; ce n’est pas une recommandation de rester indéfiniment sur cette version. La documentation du format explique notamment la différence entre le schéma, les règles de qualité et les métadonnées.
Ce que cela change par rapport à des tests de qualité classiques
Des tests existants peuvent déjà vérifier l’unicité d’une clé ou l’absence de valeurs nulles. Il serait inutile de les présenter comme insuffisants par nature. Le gain du contrat dépend surtout de la coordination et du moment du contrôle.
Si le test s’exécute seulement après le chargement dans le reporting, il détecte un incident déjà arrivé chez le consommateur. S’il s’exécute sur une version candidate avant sa publication, il peut empêcher la diffusion du lot défectueux. Si une comparaison vérifie aussi l’évolution du contrat, elle peut repérer un changement qui invalide les engagements précédents.
Il faut donc distinguer trois questions :
- Le contrat est-il correctement écrit ? Un validateur vérifie sa structure.
- Les données respectent-elles les règles de cette version ? Des contrôles examinent les données réellement fournies.
- Le changement reste-t-il compatible avec les engagements précédents ? Une comparaison entre versions et une revue des usages répondent à cette question.
Ces vérifications se complètent. Un contrat valide ne prouve pas que les données sont bonnes. Des données conformes à une nouvelle version ne prouvent pas que les traitements existants continueront à fonctionner.
Dans une organisation où les producteurs et consommateurs partagent déjà ces règles et ces contrôles, l’apport peut être modeste. Le contrat devient plus utile quand plusieurs équipes évoluent à des rythmes différents et que les incidents viennent de changements non coordonnés.
Trois cas d’usage pour un département data
1. Protéger le reporting commercial d’un changement applicatif
Une application de vente alimente les indicateurs de chiffre d’affaires. L’équipe applicative veut renommer un identifiant ou supprimer un statut. L’équipe analytics utilise encore ces champs dans ses modèles et ses jointures.
Le contrat permet de rendre cette dépendance visible dans la revue de changement. La vérification doit porter sur l’interface réellement publiée aux consommateurs, par exemple une vue d’export, et pas nécessairement sur toutes les tables internes de l’application.
Si le changement est voulu, une solution consiste à maintenir temporairement une interface compatible, puis à ouvrir une nouvelle version avec une date de migration convenue. Changer simplement le numéro du contrat ne migre aucun consommateur.
Le gain à mesurer : combien de ruptures sont détectées avant diffusion, combien d’incidents atteignent encore le reporting et combien de temps les équipes consacrent à leur résolution. Il faut aussi compter l’effort de maintenance des versions et des validations.
2. Éviter un chiffre d’affaires multiplié par cent
Un montant passe des euros aux centimes. Son nom reste identique et ses valeurs restent numériques. Les tests de présence et d’unicité peuvent rester verts alors que les indicateurs deviennent faux.
Le contrat doit expliciter l’unité et la définition métier, mais il faut traduire les attentes critiques en contrôles exécutables : quelques transactions de référence, un rapprochement avec un total indépendant ou une règle de cohérence adaptée au métier. Une simple limite maximale peut laisser passer une partie des erreurs et rejeter des commandes légitimes.
Le gain attendu : rendre les changements de sens discutables et testables. Il ne vient pas du YAML seul. Cette démarche complète celle des modèles sémantiques pour partager les indicateurs, qui traite la définition des mesures utilisées en analyse.
3. Sécuriser les fichiers d’un fournisseur
Un distributeur reçoit des stocks par fichier. Il veut éviter qu’un doublon de référence, une colonne absente ou un lot incomplet remplace les dernières données utilisables.
Lorsqu’il ne contrôle pas le système du fournisseur, le département data ne peut pas garantir un blocage chez le producteur. Il peut en revanche tester le lot reçu dans une zone temporaire, le mettre en quarantaine si nécessaire et déclencher une alerte avant sa consommation interne.
Conserver le dernier lot valide peut être un choix acceptable, à condition de rendre son ancienneté visible et de définir une durée limite avec le métier. Des données anciennes peuvent elles aussi conduire à une mauvaise décision.
Le gain à mesurer : le nombre de lots rejetés à bon escient, les faux rejets, le délai de correction et l’âge des données effectivement utilisées. La fréquence annoncée dans une documentation doit être reliée à une surveillance effective des arrivées ; notre atelier local ne teste pas cette fraîcheur.
Tutoriel : tester un contrat de données sur un fichier CSV
L’exemple est volontairement petit : trois commandes fictives, aucun compte cloud et aucune donnée client. Il utilise Python 3.12 et l’extension DuckDB de Data Contract CLI. La documentation des fichiers locaux décrit ce mode d’exécution.
1. Télécharger l’atelier et installer l’outil
Téléchargez puis décompressez l’archive de l’atelier. Ouvrez un terminal dans le dossier extrait, celui qui contient commandes.csv et commandes.odcs.yaml.
Sur macOS ou Linux, avec Python 3.12 installé :
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install 'datacontract-cli[duckdb]==1.2.1'
datacontract --version
L’installation télécharge des dépendances. Sous Windows, l’activation de l’environnement virtuel utilise une commande différente ; le README de l’archive donne l’équivalent PowerShell.
2. Lire le fichier et son contrat
Notre fichier contient deux commandes du même client. C’est normal : c’est l’identifiant de commande qui doit être unique.
order_id,customer_id,total_amount_eur
CMD-001,CLI-01,49.90
CMD-002,CLI-01,25.00
CMD-003,CLI-02,12.50
Le contrat complet est inclus dans l’archive. Son bloc de schéma contient notamment :
schema:
- name: commandes
properties:
- name: order_id
logicalType: string
required: true
unique: true
- name: customer_id
logicalType: string
required: true
- name: total_amount_eur
logicalType: number
required: true
description: Montant TTC en euros, hors frais de livraison.
Ici, required impose l’absence de valeurs manquantes et unique interdit les doublons de commande. La description du montant renseigne le lecteur ; elle ne crée aucun test sur l’unité monétaire. Pour les CSV, l’outil lit les valeurs selon les types du contrat : une valeur impossible à convertir peut provoquer une erreur de lecture. Il ne faut pas assimiler cela à une vérification du type natif d’une colonne de base de données. Attributs effectivement contrôlés.
Les chemins de fichiers sont relatifs au dossier depuis lequel la commande est lancée. C’est pourquoi il faut rester dans le dossier de l’atelier.
3. Vérifier la référence puis détecter un doublon
datacontract lint commandes.odcs.yaml
datacontract test commandes.odcs.yaml
datacontract test commandes-doublon.odcs.yaml
Lors de notre exécution du 28 septembre 2026, les deux premières commandes ont renvoyé un code de sortie 0. Le test du fichier de référence a exécuté sept contrôles.
Le fichier de démonstration avec doublon ajoute une seconde ligne portant CMD-001. Son test échoue avec un code 1. C’est le signal qu’un pipeline peut utiliser pour arrêter la publication du lot. Il faut configurer cet arrêt : afficher un message d’erreur sans interrompre l’étape suivante ne suffit pas.
4. Comparer deux versions qui passent chacune leurs tests
La deuxième version remplace order_id par id, dans le contrat comme dans le CSV. Exécutez :
datacontract test commandes-v2.odcs.yaml
datacontract breaking commandes.odcs.yaml commandes-v2.odcs.yaml
Le premier appel réussit, le second échoue. Nous avons obtenu respectivement les codes 0 et 1. La comparaison signale notamment la suppression de order_id comme une erreur de compatibilité. C’est précisément la différence entre tester une version et protéger ceux qui dépendent de la précédente.
Dans cette commande, un niveau ERROR provoque un code 1, mais un WARNING conserve un code 0. La politique de revue doit donc traiter aussi les avertissements pertinents pour vos usages. Le comparateur ne connaît pas tous vos consommateurs. Fonctionnement de la comparaison.
5. Reproduire une erreur que ce contrat ne détecte pas
datacontract test commandes-centimes.odcs.yaml
Ce dernier fichier contient 4990 à la place de 49.90, avec le même nom de colonne et la même description en euros. Le test réussit. Nous l’avons vérifié : toutes les règles présentes restent satisfaites.
C’est une limite du contrat que nous avons écrit, pas une preuve que les montants sont corrects. Avant de connecter ce contrôle à une chaîne financière, il faudrait ajouter une référence métier capable de vérifier la conversion et le périmètre du montant. L’atelier montre un mécanisme et ses limites, pas une validation de production.
Où placer ces contrôles dans votre chaîne de données ?
Pour un flux que vous maîtrisez, une séquence utile est : produire une version candidate dans une zone temporaire, contrôler ses données, comparer le contrat avec la dernière version publiée, puis rendre le lot accessible si les contrôles et la revue sont satisfaits.
La comparaison doit utiliser une référence publiée conservée séparément. Comparer le contrat modifié avec lui-même rendrait ce contrôle inutile. Dans une CI Git, cela peut être la version du contrat de la branche principale, à condition qu’elle représente bien l’interface en production.
Le passage de la zone temporaire à la zone consommable doit être explicite. Selon la plateforme, il peut s’agir d’une promotion de table, d’un changement de vue ou d’une publication de fichiers validés. Si les consommateurs lisent déjà le lot avant le contrôle, vous avez un dispositif de détection après exposition.
Prévoyez aussi le destinataire de l’alerte, le comportement en cas d’échec et le processus d’exception. Un blocage systématiquement contourné par l’équipe n’est plus une protection fiable. Les responsabilités se travaillent avec les équipes propriétaires des produits data, pas seulement dans l’outil de validation.
Par quel périmètre commencer ?
Choisissez un échange qui a déjà un producteur identifié, un consommateur important et des conséquences compréhensibles en cas de rupture. Décrivez quelques engagements réellement utiles : grain, clé, champs indispensables, unité des montants, rythme de livraison et contact responsable.
Faites ensuite rejouer une anomalie connue et un changement de schéma volontaire. Vérifiez que l’alerte arrive au bon endroit et que le lot défectueux ne devient pas visible. Mesurez le coût du contrôle sur un volume représentatif : requêtes supplémentaires, durée, stockage temporaire et charge de maintenance. Notre fichier de trois lignes ne permet aucune conclusion sur ces coûts à grande échelle.
Je commencerais par un flux critique et un désaccord concret entre producteur et consommateur. Cela permet de juger l’intérêt du contrat sur une décision réelle : publier, corriger ou organiser une migration. Le nombre de contrats écrits est un indicateur d’activité ; le nombre de ruptures évitées et le temps de résolution renseignent davantage sur leur utilité.
Si votre équipe souhaite cadrer ce premier périmètre, Nymphar peut vous accompagner dans la définition des engagements, des contrôles et des responsabilités.
