Quando un CRM alimenta un ERP, un negozio invia ordini alla logistica o un'applicazione interna pubblica eventi per altri sistemi, l'integrazione dipende da qualcosa di più di un URL, una coda o un file condiviso. Dipende dal fatto che tutte le parti interpretino i dati allo stesso modo nel tempo. I contratti di dati per le integrazioni trasformano questa aspettativa in regole esplicite, verificabili e governabili.
Il loro obiettivo non è documentare un'interfaccia una sola volta, bensì evitare che una modifica apparentemente piccola —rinominare un campo, ammettere un nuovo stato o modificare un'unità monetaria— provochi errori silenziosi, rielaborazioni o decisioni aziendali errate. Sono particolarmente utili quando intervengono team diversi, applicazioni di terze parti e distribuzioni con calendari indipendenti.
Che cos'è un contratto di dati e quale problema risolve
Un contratto di dati definisce l'accordo operativo tra chi produce informazioni e chi le consuma. Si applica a una risposta di servizio, un evento, un file periodico, una tabella condivisa o un messaggio in una coda. Descrive che cosa viene fornito, che cosa significa, a quali condizioni è valido e come evolverà.
Per esempio, un messaggio d'ordine con orderId, status e amount deve precisare se l'importo è espresso in unità o centesimi, quale valuta si applica, quali stati sono ammessi, se un ordine annullato può avere un importo pari a zero e se lo stesso messaggio può arrivare più di una volta. Senza queste regole, due sistemi possono accettare tecnicamente lo stesso JSON e, tuttavia, agire in modo incompatibile.
Il contratto riduce tre rischi frequenti:
- Interruzioni dirette: un consumatore non riesce a deserializzare, validare o elaborare un dato modificato.
- Errori semantici: il formato sembra corretto, ma cambia il significato di un campo o di una regola aziendale.
- Dipendenze invisibili: un produttore non sa che un campo, un valore o un comportamento viene usato da altri consumatori.
Documentazione, schema e contratto operativo
La documentazione spiega come dovrebbe funzionare un'integrazione. Uno schema formalizza parte di questa spiegazione: struttura, nomi, tipi, campi obbligatori e, a seconda della tecnologia, vincoli. Entrambi sono necessari, ma non bastano per gestire un'integrazione in modo sicuro.
Il contratto operativo riunisce lo schema con decisioni che possono essere riesaminate e testate: proprietario, consumatori noti, politica di compatibilità, versionamento, regole semantiche, qualità minima, gestione degli errori e procedura di modifica. Può essere rappresentato con OpenAPI, AsyncAPI, JSON Schema, Avro, Protobuf, SQL o un'altra specifica, ma lo strumento non sostituisce tali decisioni.
Un contratto utile dovrebbe includere almeno:
- Identità e ambito: nome, scopo, canale, produttore, responsabile e classificazione della sensibilità.
- Struttura: campi, tipi, cardinalità, obbligatorietà, formati ed esempi validi.
- Semantica: significato, unità, fuso orario, valuta, catalogo di valori e regole di calcolo.
- Qualità: unicità, intervalli, relazioni tra campi, freschezza attesa e ordinamento quando rilevante.
- Operatività: frequenza, limiti di dimensione, ordine di consegna, tentativi ripetuti, conservazione e canale per le segnalazioni.
- Evoluzione: versione, modifiche compatibili, modifiche che richiedono coordinamento e periodo di ritiro.
Compatibilità: valutare le modifiche con una prospettiva esplicita
La terminologia della compatibilità può variare tra i team. Per evitare decisioni errate, è opportuno adottare la consueta prospettiva di lettura degli schemi, utilizzata da numerosi registri degli schemi: la compatibilità con le versioni precedenti significa che il nuovo schema o consumatore può leggere dati prodotti con lo schema precedente; la compatibilità con le versioni successive significa che lo schema o consumatore precedente può leggere dati prodotti con il nuovo schema. La compatibilità completa richiede entrambe le direzioni.
Questa definizione non consente di dedurre il comportamento reale osservando soltanto una regola astratta. Deve essere verificata con il formato, il serializzatore, lo schema di lettura e l'implementazione concreta del consumatore. Aggiungere un campo facoltativo con valore predefinito, per esempio, può essere compatibile con le versioni precedenti se la nuova versione sa colmare la sua assenza leggendo dati vecchi. Ma un consumatore precedente potrà leggere il nuovo messaggio solo se la sua tecnologia e implementazione ignorano campi sconosciuti o se il suo schema di lettura risolve correttamente quel campo tramite un valore predefinito. Non va presunto senza un test.
Prima di approvare una modifica, ponete domande concrete: la nuova versione può elaborare messaggi già archiviati? La versione precedente può continuare a elaborare messaggi emessi durante una distribuzione graduale? Che cosa accade ai consumatori esterni che non si aggiornano allo stesso ritmo? La risposta deve derivare da test rappresentativi, non soltanto dall'etichetta di compatibilità del registro.
Come regola pratica, tendono a essere modifiche a minor rischio l'aggiunta di campi realmente facoltativi, l'estensione di metadati non interpretati o la correzione delle descrizioni. Tendono invece a richiedere una nuova versione e coordinamento l'eliminazione o la ridenominazione di campi, la modifica dei tipi, la riduzione degli intervalli, l'alterazione delle unità, la reinterpretazione dei valori null o l'introduzione di valori di enumerazione che attivano una logica diversa. Mantenere temporaneamente un campo obsoleto e pubblicare una data di ritiro offre una transizione più sicura rispetto alla sua eliminazione immediata.
Progettazione in base al tipo di scambio
Lo stesso principio assume forme diverse a seconda del meccanismo. Negli eventi, identificate il fatto avvenuto, l'istante aziendale, l'origine, l'identificatore dell'evento e l'entità interessata. Dichiarate se l'evento è immutabile, se può arrivare fuori ordine e se esistono eventi di correzione.
Se la consegna avviene almeno una volta, il consumatore necessita di una strategia verificabile per rilevare o tollerare i duplicati. Può usare un identificatore dell'evento salvato in un registro di deduplicazione, una chiave aziendale con operazioni idempotenti, un vincolo nello storage o un meccanismo equivalente concordato. Una chiave di idempotenza è un'opzione frequente, ma non un requisito universale. L'importante è definire quali duplicati sono attesi, per quanto tempo vengono rilevati e quale risultato deve produrre la loro rielaborazione.
Nelle risposte sincrone dei servizi, il contratto deve distinguere tra dati aziendali, errori funzionali e guasti tecnici. È preferibile definire codici, struttura dell'errore, campi sicuri per la diagnostica e condizioni per i tentativi ripetuti. Nei caricamenti periodici, specificate il cutoff temporale, il fuso orario, se il file contiene un caricamento completo o incrementale, la chiave di riconciliazione e il comportamento in presenza di record ripetuti o mancanti.
Test di contratto prima e dopo la produzione
I test di contratto automatizzano la verifica che produttore e consumatore rispettino l'accordo. In fase di sviluppo, validate esempi validi e non validi rispetto allo schema e alle regole semantiche rilevanti. Includete casi limite: valori null consentiti, valori sconosciuti, decimali, date con fuso orario e combinazioni di campi dipendenti.
Nell'integrazione continua, la modifica del contratto deve essere confrontata con l'ultima versione pubblicata. Il controllo può bloccare modifiche incompatibili, richiedere una nuova versione o richiedere l'approvazione del responsabile. È inoltre opportuno eseguire consumatori di riferimento o test concordati dai consumatori critici su dati di test prodotti dalla nuova versione.
Prima della produzione, testate la coesistenza tra le versioni che esisterà effettivamente durante la distribuzione. Dopo la pubblicazione, osservate i tassi di validazione fallita, i messaggi inviati in quarantena, gli errori di deserializzazione, il ritardo di elaborazione e la proporzione di valori sconosciuti. Registrate identificatori tecnici, versione del contratto, tipo di errore e origine; evitate di includere dati personali, segreti o payload completi quando non sono indispensabili per la diagnosi.
Governance delle modifiche, eccezioni e tracciabilità
Un flusso leggero ed esplicito evita che il contratto diventi un documento dimenticato. Il produttore propone la modifica con la relativa motivazione, l'impatto previsto, un esempio del prima e del dopo, la classificazione della compatibilità e il piano di ritiro. I responsabili dei consumatori interessati riesaminano la semantica e i test. Un proprietario designato approva, pubblica la versione e comunica la finestra di adozione.
Anche le eccezioni devono essere definite. Se arriva un valore fuori intervallo, non sempre è opportuno rifiutare l'intero caricamento: può essere inviato in quarantena, contrassegnato per revisione o accettato con un indicatore di qualità, in base al rischio aziendale. Per valori di catalogo sconosciuti, stabilite se il consumatore debba ignorarli, conservarli, applicare un comportamento sicuro o interrompere il processo. Distinguete attentamente tra campo assente, campo null e valore vuoto: possono esprimere situazioni diverse.
Infine, mantenete un registro versionato di contratti, decisioni di compatibilità, approvazioni, date di deprecazione e prove dei test. Questa tracciabilità consente di rispondere a chi ha modificato che cosa, perché è stato considerato sicuro e quali consumatori dovevano adattarsi. Così, l'evoluzione smette di dipendere da verifiche manuali e diventa una disciplina tecnica verificabile.