Schema Registry and event governance

Questa lezione del binario ml-tabellare affronta il punto in cui i dati smettono di essere un dettaglio tecnico e diventano un contratto tra team: lo Schema Registry è lo strumento che rende quell’evoluzione sicura.

L’idea in una frase

Lo Schema Registry è il contratto condiviso che permette a producer e consumer di far evolvere il formato degli eventi senza rompersi a vicenda.

La procedura in sei passi

1. Registra la prima versione dello schema nel Registry prima di pubblicare il topic.
2. Imposta la compatibilità della subject su BACKWARD come default.
3. Aggiungi nuovi campi solo con un valore di default esplicito.
4. Esegui il check di compatibilità in CI a ogni modifica dello schema.
5. Verifica i consumer critici in staging prima della release in produzione.
6. Depreca i campi obsoleti con un periodo di transizione invece di rimuoverli subito.

Il problema da risolvere

Un campo viene rinominato in produzione e tre consumer smettono di leggere gli eventi, anche se il topic è online e il cluster è sano. La fragilità non è nel broker, è nel contratto tra producer e consumer. Schema Registry serve a far evolvere gli eventi senza trasformare ogni release in un rischio sistemico. La lezione lo tratta come scelta operativa: non quante definizioni conosci, ma quale decisione cambia quando il dato diventa più affidabile.

In un sistema di streaming il broker può essere sano mentre i dati smettono di scorrere. Kafka non conosce il significato dei byte che trasporta: per lui un evento è una sequenza opaca. La struttura la conoscono il producer che scrive e il consumer che legge, e quando i due si disallineano nessun alert del cluster te lo segnala.

Il problema concreto è governare l’evoluzione: aggiungere un campo, rinominarlo, cambiarne il tipo o rimuoverlo senza far cadere i consumer in produzione. Una lezione utile separa il segnale dal rumore, dichiara la baseline di lettura e indica quale azione diventa più difendibile dopo l’analisi. La domanda guida non è “quale metrica calcolo” ma “quale decisione dovrà essere presa grazie a questo controllo”. Una policy di compatibilità ha valore solo se riduce l’incertezza su una release; se non cambia alcuna scelta, è documentazione.

Schema Registry: how it works

Schema Registry is a separate service that stores Avro (or Protobuf, JSON Schema) schemas and assigns a schema_id to each version. The producer serializes including only the schema_id, non lo schema intero, e così risparmia banda. Il consumer recupera lo schema corretto dal Registry e deserializza.

Questo sposta il contratto fuori dal codice e dentro un artefatto condiviso. Lo Schema Registry non è un archivio tecnico: è il punto in cui l’organizzazione decide quali cambiamenti sono sicuri per l’ecosistema eventi. Governance applicata vuol dire compatibilità backward e forward, naming, ownership, versioning e regole di deprecazione, tutto ancorato a uno schema che vive in produzione invece che a un documento Word.

Compatibility types

Compatibility	Meaning	When to use it
BACKWARD	New consumers can read old data	Add optional fields
FORWARD	Old consumers can read new data	Remove optional fields (with default)
FULL	Both directions	Add fields with default
NONE	No guarantee	Only when you know what you're doing

La regola pratica è tenere BACKWARD come default sicuro. Aggiungi campi con un valore di default e i vecchi consumer continuano a funzionare. Non rimuovere mai campi senza un periodo di transizione: è il modo più rapido per rompere chi legge a valle senza accorgertene finché i dati non sono già spariti.

Esempio: evoluzione di uno schema Avro

// V1: schema iniziale
{"type": "record", "name": "Purchase", "fields": [
    {"name": "user_id", "type": "int"},
    {"name": "amount", "type": "double"}
]}

// V2: aggiunta campo opzionale (BACKWARD compatibile)
{"type": "record", "name": "Purchase", "fields": [
    {"name": "user_id", "type": "int"},
    {"name": "amount", "type": "double"},
    {"name": "discount_code", "type": ["null", "string"], "default": null}
]}

I messaggi vecchi senza discount_code vengono letti con discount_code = null e i consumer non si rompono. I nuovi messaggi includono il campo. È evoluzione senza downtime, ed è esattamente il tipo di cambiamento che una policy BACKWARD lascia passare in automatico.

Un caso operativo da seguire

Il caso tipico è un team che aggiunge un campo agli eventi di pagamento senza rompere antifrode, BI e riconciliazione contabile. La decisione passa da regole di compatibilità, valori di default, versioning e test sui consumer critici. La domanda non è “qual è la definizione corretta di compatibilità” ma “quale release diventa meno rischiosa se il contratto è governato bene”.

Observed evidence	Cautious interpretation	Recommended action
Il campo nuovo passa il check di compatibilità	Backward garantito solo per chi ha un default	Verificare che ogni consumer critico tolleri il null
Un solo consumer fallisce dopo la release	Forse legge con uno schema più vecchio del previsto	Controllare la versione effettiva in produzione
La compatibilità è impostata su NONE	Nessuna garanzia, ogni cambiamento è un azzardo	Riportare la subject a BACKWARD prima di scalare

La lettura è prudente per costruzione: un check verde dice che lo schema è compatibile secondo la regola scelta, non che ogni consumer in produzione la stia rispettando.

Governance: who produces what

Con Schema Registry puoi costruire un catalogo di eventi aziendali: quali eventi esistono, chi li produce, chi li consuma, qual è lo schema corrente. Strumenti come Confluent Control Center o DataHub leggono dal Registry e generano un grafo di lineage automatico. La governance smette di essere un documento e diventa un artefatto vivo derivato dagli schemi in produzione.

Il valore pratico è che la responsabilità diventa esplicita. Quando sai chi possiede un evento sai anche chi deve approvare un cambiamento di schema e chi avvisare prima di una deprecazione. Senza questo livello, ogni modifica diventa una scommessa su quali team a valle se ne accorgeranno e quando.

Errori tipici da evitare

Il primo errore è trattare lo Schema Registry come etichetta tecnica invece che come criterio di scelta: presenti un grafico di compatibilità senza dire quale release abilita e quale rischio resta aperto. Il dato sembra preciso ma non guida alcuna azione.

Il secondo errore è cambiare la definizione di compatibilità senza dichiararlo. Spostare una subject su NONE per far passare una modifica scomoda toglie la rete di protezione proprio quando serve di più. Il terzo è rimuovere o rinominare campi senza periodo di transizione: i consumer vecchi cercano il campo che non esiste più e falliscono in silenzio. Per ridurre questi rischi, ogni cambiamento di schema dovrebbe portare con sé tre cose: la regola di compatibilità applicata, l’elenco dei consumer critici verificati e un confronto con la versione precedente.

Verdetto: tieni BACKWARD come default, aggiungi campi solo con default e tratta ogni rimozione come una migrazione con transizione, non come una modifica.

References:

• Confluent. (2024). “Schema Registry Documentation.” docs.confluent.io.
• Narkhede, N. (2017). “Schemas, Contracts, and Compatibility.” Confluent Blog.

L’esempio che fa da riferimento

Confluent, fondata nel 2014 dagli ingegneri che avevano creato Kafka in LinkedIn, ha portato lo Schema Registry al centro della propria piattaforma con supporto ad Avro, Protobuf e JSON Schema. Neha Narkhede ha descritto nel 2017 come schemi, contratti e regole di compatibilità separino l’evoluzione sicura dei dati dalla rottura dei consumer. Da allora la combinazione di registro centralizzato, identificativo di schema per messaggio e check BACKWARD in pipeline è diventata la pratica standard per governare gli eventi in produzione. La lezione di quel percorso è netta: il contratto vive nel registro, non nella memoria dei team.

Domande per verificare la lezione

1. Quale campo stai aggiungendo allo schema e quale default garantisce la compatibilità BACKWARD?
2. Quali consumer critici hai verificato prima di pubblicare la nuova versione dello schema?
3. Quale regola di compatibilità è impostata sulla subject e perché è quella giusta?
4. Come gestisci la deprecazione di un campo senza fermare i consumer esistenti?