Data Contracts: Definire gli Accordi tra Chi Produce e Chi Consuma i Dati
Ogni pipeline di dati ha un nemico silenzioso: il cambiamento non annunciato a monte. Il gestionale esporta di nuovo l'archivio, qualcuno rinomina una colonna, un prezzo cambia unità di misura, e a valle la dashboard continua a girare — mostrando numeri che significano un'altra cosa. Nessun job rosso, nessun errore: solo dati diversi.
Il data contract serve a spostare quel problema da "scoperto per caso tre settimane dopo" a "bloccato nel repository di chi produce il dato". Non è burocrazia: è la differenza tra accorgersi di un cambio schema in dieci secondi e scoprirlo durante la chiusura mensile.
Cos'è un data contract, in pratica
Un data contract è un accordo esplicito e verificabile tra chi produce un dato e chi lo consuma. Descrive almeno:
- Schema: nomi dei campi, tipi, nullabilità.
- Semantica: cosa significa ogni campo, in quale unità è espresso, in quale fuso orario.
- Granularità e chiave: cosa rappresenta esattamente una riga.
- Freschezza: entro quando il dato è disponibile e con quale regolarità.
- Qualità: i vincoli che devono valere sempre (unicità, range, valori ammessi).
- Versionamento: come e quando lo schema può cambiare, e con quale preavviso.
La parola decisiva è verificabile. Se il contratto è un documento in una cartella condivisa, non è un contratto: è un'intenzione. Per servire a qualcosa deve essere leggibile da una macchina e controllato automaticamente — nel repository di chi produce il dato, al momento dell'ingestione e dopo il caricamento nel data warehouse.
La differenza con un dizionario dati è tutta qui:
| Aspetto | Dizionario dati | Data contract |
|---|---|---|
| Scopo | Documentare | Vincolare |
| Chi lo mantiene | Spesso chi consuma | Chi produce, con l'accordo di chi consuma |
| Verifica | Manuale, quando ci si ricorda | Automatica in CI e a runtime |
| Quando cambia | Si aggiorna dopo | Serve una nuova versione concordata |
Perché conviene, anche in un team piccolo
Il beneficio non è "avere più documentazione". È spostare il punto in cui il guasto diventa visibile:
- Fail fast, a monte. Un test che fallisce nel repository del produttore costa minuti. Un numero sbagliato in una riunione di budget costa giorni.
- Disaccoppiamento reale. Chi consuma può cambiare la propria pipeline senza paura, perché sa cosa può aspettarsi e cosa no.
- Meno riunioni. Le regole sono scritte e testate, non ricordate a voce da qualcuno che era in quella call di otto mesi fa.
- Migrazioni negoziate. Se il contratto prevede una procedura di deprecazione, il cambiamento diventa un piano invece di un incidente.
- Onboarding più rapido. Un nuovo collega legge il contratto e capisce il dato senza doverlo dedurre dal codice.
Il costo è reale: qualcuno deve scrivere e mantenere il contratto. Per questo conviene applicarlo a un numero piccolo di dataset critici, non a tutto.
Anatomia di un contratto: un esempio
Un contratto vive bene in un file di testo versionato insieme al codice. Ecco un esempio semplificato per una tabella di vendite proveniente da un gestionale:
# contracts/vendite_gestionale.yaml (esempio)
contract:
name: vendite_gestionale
version: 1.2.0
owner: team-dati-retail
producer: gestionale-erp
consumer:
- data-warehouse
- analytics-negozi
sla:
freschezza: entro le 07:00 ora locale, ogni giorno
disponibilita: quasi tutti i giorni del mese
primary_key: [id_scontrino, riga]
granularita: una riga per riga di scontrino
schema:
- name: id_scontrino
type: string
nullable: false
- name: data_vendita
type: timestamp
timezone: Europe/Rome
nullable: false
- name: codice_articolo
type: string
nullable: false
- name: quantita
type: integer
nullable: false
constraints: {min: 1}
- name: prezzo_unitario_eur
type: decimal(10,2)
nullable: true
note: nullo per le righe in omaggio
Quattro dettagli fanno la differenza tra un contratto utile e un file decorativo:
- Owner e producer sono espliciti. Si sa chi chiamare.
- La granularità è dichiarata. "Una riga per riga di scontrino" chiarisce subito cosa significano i conteggi a valle.
- La semantica è scritta. Il fuso orario e le note sui valori nulli evitano ore di debug.
- La versione è un numero. Non un campo libero, ma qualcosa che si può confrontare e confrontare di nuovo al momento dell'ingestione.
Compatibilità: cosa si può cambiare senza rompere
Quando si parla di contratti, tre parole ricorrono spesso e vale la pena chiarirle senza gergo:
- Backward compatible: il consumatore vecchio riesce a leggere il dato nuovo.
- Forward compatible: il consumatore nuovo riesce a leggere il dato vecchio (tipicamente perché ignora i campi che non conosce).
- Full compatible: valgono entrambe.
Da qui discende una tabella pratica dei cambiamenti:
| Cambiamento | Effetto tipico |
|---|---|
| Aggiungere un campo opzionale | Sicuro |
| Aggiungere un campo obbligatorio senza valore di default | Rompe |
| Rinominare un campo | Rompe |
| Allargare un tipo (es. intero più capiente) | In genere sicuro |
| Restringere un tipo o accorciare una stringa | Rompe |
| Eliminare un campo | Rompe, dopo un periodo di deprecazione |
| Cambiare unità o semantica a parità di nome e tipo | Rompe in silenzio |
L'ultima riga è il vero motivo per cui esistono i data contract.
Il caso peggiore: il cambiamento silenzioso
Immagina che prezzo_unitario_eur passi da IVA esclusa a IVA inclusa. Nome identico, tipo identico, nessun test di schema si accorge di niente. I margini calcolati a valle diventano però numeri privi di senso, e nessuno riceve un alert.
Contro questo tipo di deriva servono invarianti di business: relazioni che devono valere tra i campi, indipendenti da come sono formattati. Un esempio classico è il totale di riga che deve tornare:
-- Invariante di business: il totale riga deve essere coerente (esempio)
select count(*) as righe_incoerenti
from vendite
where abs(prezzo_unitario_eur * quantita - totale_riga_eur) > 0.05;
La soglia 0.05 è solo un esempio: va scelta in base agli arrotondamenti del sistema di origine. L'importante è che il controllo esista e che fallisca in modo rumoroso. Accanto a questo, controlli di plausibilità sulle distribuzioni (il prezzo medio giornaliero che si sposta oltre una soglia rispetto ai giorni precedenti) intercettano cambi semantici che nessun confronto di schema può vedere.
Dove far rispettare il contratto
Un contratto scritto ma non applicato è peggio di nessun contratto, perché crea fiducia ingiustificata. I punti di controllo sensati sono quattro.
1. Nel repository del produttore (CI). Il produttore esporta lo schema del dato e lo confronta con il contratto a ogni commit. Un errore blocca la build prima che il dato arrivi a qualcuno.
2. Al confine di ingestione. Prima di scrivere nella tabella di destinazione, si valida. Qui serve un controllo minimo e veloce:
# checks/schema_vendite.py — esempio minimale
REQUIRED = [
'id_scontrino',
'data_vendita',
'codice_articolo',
'quantita',
'prezzo_unitario_eur',
]
def colonne_mancanti(df, richieste=REQUIRED):
return [c for c in richieste if c not in df.columns]
Il controllo qui sopra verifica solo la presenza delle colonne. I controlli di tipo e di vincolo dipendono dallo stack: si possono fare con uno schema JSON, con i test del data warehouse, con una libreria di data quality o con poche query SQL scritte a mano. L'importante è che girino prima che il dato sia considerato valido.
3. Con la quarantena invece dello scarto. Una riga che viola il contratto non dovrebbe sparire: dovrebbe finire in una tabella di quarantena con il motivo, così è recuperabile e ispezionabile.
-- Quarantena: le righe fuori contratto restano tracciabili (esempio)
insert into ingest_quarantena (sorgente, riga_raw, motivo, rilevato_il)
select 'vendite_gestionale', riga_raw, 'quantita < 1', now()
from staging_vendite
where quantita < 1;
Qui c'è un trade-off da decidere esplicitamente: si fallisce tutto il batch, o si quarantena e si prosegue? Una regola ragionevole è fallire se la quota di righe non conformi supera una soglia, quarantenare altrimenti. La soglia va scelta, documentata nel contratto e ritarata nel tempo.
4. Dopo il caricamento. I controlli a valle verificano gli invarianti di business e la freschezza: il dato è arrivato entro l'orario previsto? Le chiavi sono uniche? I range sono rispettati? È qui che si intercettano i problemi che nascono dall'incontro tra due fonti, non dalla singola fonte.
Versionare e deprecare senza fermare nessuno
Un contratto senza politica di versione è una promessa che si rompe alla prima urgenza. Lo schema di versionamento più leggibile è quello a tre livelli, applicato ai dati:
- Patch: correzioni che non toccano schema né semantica (una descrizione più chiara, un vincolo documentato meglio).
- Minor: aggiunte retrocompatibili (un campo opzionale, un nuovo valore ammesso).
- Major: cambiamenti che rompono i consumatori (rinomina, rimozione, cambio di unità).
Per i cambiamenti major, la sequenza che funziona è quella in tre tempi, la stessa che si usa nelle migrazioni di schema: si espande (si aggiunge il nuovo campo accanto al vecchio), si migra (i consumatori passano al nuovo, mentre entrambi esistono), si contrae (si rimuove il vecchio quando nessuno lo legge più). Il punto critico è l'ultimo passaggio: serve sapere chi legge ancora il vecchio campo. Senza una misura dell'utilizzo reale, la contrazione diventa una scommessa.
Chi scrive il contratto, e dove vive
Il contratto dovrebbe vivere nel repository di chi produce il dato ed essere rivisto dai consumatori, non il contrario. Se lo scrive solo chi consuma, diventa un requisito che il produttore subisce; se lo scrive solo chi produce, spesso descrive il sistema di origine e non i bisogni a valle.
Nella pratica il nodo è organizzativo, non tecnico. Portare un contratto a un fornitore o a un team interno significa presentarlo come uno strumento che evita incidenti a entrambi, non come un controllo. Un modo efficace è partire da un solo dataset, quello che ha causato più problemi negli ultimi mesi, e mostrare quante volte sarebbe servito.
Cosa non aspettarsi dai data contract
Vale la pena essere chiari sui limiti:
- Non sostituiscono i test sui dati. Il contratto dice cosa deve valere; i test verificano se vale davvero sui dati reali. Sono due cose diverse e complementari.
- Non garantiscono che il dato sia corretto. Garantiscono che il dato è quello che dichiara di essere. Un dato sbagliato ma conforme al contratto resta sbagliato.
- Non vanno applicati a tutto. Su dataset esplorativi o temporanei, il costo di manutenzione supera il beneficio. Meglio pochi contratti solidi che venti contratti abbandonati.
- Non risolvono i problemi di comunicazione tra team. Li rendono visibili, che è già molto.
Conclusione
Un data contract è un modo per rendere esplicito e verificabile ciò che oggi è implicito: cosa promette chi produce il dato e cosa può pretendere chi lo consuma.
I punti chiave:
- Il valore non sta nel documento, ma nel fatto che sia leggibile da una macchina e controllato automaticamente.
- Il contratto deve descrivere schema, semantica, granularità, freschezza, qualità e versionamento: senza la semantica, la deriva silenziosa resta invisibile.
- Esistono cambiamenti sicuri (aggiungere un campo opzionale) e cambiamenti che rompono (rinominare, restringere, cambiare unità a parità di nome).
- I controlli vanno collocati in CI, al confine di ingestione, in quarantena e dopo il caricamento.
- Versionamento a tre livelli e ciclo espandi-migra-contrai rendono le evoluzioni pianificabili invece che traumatiche.
- Meglio iniziare da un dataset critico e da un contratto scritto da chi produce, rivisto da chi consuma.