import pandas as pd

Schema Registry e governance degli eventi

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, e questa lezione lo tratta come scelta operativa: non quante definizioni conosci, ma quale decisione cambia quando il dato diventa più affidabile.

Il problema da risolvere

In un sistema di streaming il broker può essere perfettamente sano mentre i dati smettono di scorrere. Kafka non sa nulla del significato dei byte che trasporta: per lui un evento è una sequenza opaca. Chi conosce la struttura è 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 che già girano in produzione. Una lezione utile su questo tema deve separare il segnale dal rumore, dire rispetto a quale baseline interpretare un cambiamento e indicare 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 nessuna scelta, è documentazione.

Schema Registry: come funziona

Schema Registry è un servizio separato che memorizza gli schemi Avro (o Protobuf, JSON Schema) e assegna un schema_id a ogni versione. Il producer serializza includendo solo lo 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.

Tipi di compatibilità

Compatibilità	Significato	Quando usarla
BACKWARD	I nuovi consumer possono leggere dati vecchi	Aggiungere campi opzionali
FORWARD	I vecchi consumer possono leggere dati nuovi	Rimuovere campi opzionali (con default)
FULL	Entrambe le direzioni	Aggiungere campi con default
NONE	Nessuna garanzia	Solo quando sai cosa fai

La regola pratica è che BACKWARD resta il 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 fino a quando 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

Prendi un team che deve aggiungere un nuovo campo agli eventi di pagamento senza rompere antifrode, BI e riconciliazione contabile. La decisione non passa da una semplice modifica al payload: 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”.

Evidenza osservata	Lettura prudente	Azione consigliata
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: chi produce cosa

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 un’etichetta tecnica invece che come criterio di scelta: si presenta un grafico di compatibilità senza dire quale release abilita e quale rischio resta aperto. Il dato sembra preciso ma non guida nessuna azione.

Il secondo errore è cambiare definizione di compatibilità senza dichiararlo. Spostare una subject su NONE per far passare una modifica scomoda significa togliere la rete di protezione proprio quando serve di più. Il terzo è rimuovere o rinominare campi senza periodo di transizione: i consumer vecchi continuano a cercare 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.

Checkpoint

1. Quale release concreta dovrebbe diventare meno rischiosa grazie alla governance degli schemi?
2. Quale unità di analisi rende il problema misurabile: il topic, l’evento, lo schema o il consumer group?
3. Quale baseline useresti per leggere un cambiamento di schema senza valutarlo in isolamento?
4. Quale assunzione, se falsa, romperebbe un consumer nonostante il check verde?
5. Quale controllo presenteresti a uno stakeholder prima di mettere in produzione un nuovo campo?

Riepilogo

Schema Registry e governance degli eventi diventano utili quando producono una decisione più chiara, non quando aggiungono terminologia. La forma corretta del ragionamento è sempre la stessa: quale decisione cambia, quale segnale osservi, rispetto a quale baseline lo interpreti, quale rischio resta e quale azione segue. Una policy di compatibilità ben scelta non garantisce che nessun consumer si rompa mai, ma rende il rischio visibile e discutibile prima della release invece che dopo.

---

Riferimenti:

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