Report di validazione delle pipeline ETL

Deliverable D2.3.1: verifica e validazione QA/QC su acquisizione, pulizia e normalizzazione dei dataset raw

Questo capitolo documenta il framework e la metodologia di validazione delle pipeline ETL del Data Lake MAPS. Definisce i criteri di accettazione, le asserzioni di controllo dell'integrità temporale, la governance della qualità tramite i tag di OpenMetadata, la metodologia di riconciliazione territoriale e la validazione di contenuto a cura dei data steward. Lo sviluppo per-dataset e l'esecuzione sui dati di produzione sono a cura del team di sviluppo; la fonte autorevole dello stato di validazione di ciascun dataset è la dashboard ETL, descritta nella relazione di consegna.

Metodologia di validazione

Criteri di accettazione

Le pipeline ETL devono soddisfare cinque classi di criteri di accettazione. L'integrità temporale è il requisito principale per il layer di fondazione territoriale, poiché tutte le pipeline attributo dipendono dalla correttezza del grafo silver.territories.

Integrità temporale (pipeline di fondazione)

• Obiettivo: tutti i record territoriali in silver.territories e nelle tabelle correlate portano timestamp valid_from/valid_to validi derivati dagli eventi di variazione ISTAT; non esistono finestre temporali sovrapposte per la stessa entità; ogni entità attualmente attiva ha valid_to IS NULL
• Metrica: conteggio delle violazioni di integrità in territories, territory_identifiers, territory_names, territory_containments
• Soglia: PASS se 0 violazioni; FAIL in caso di qualsiasi violazione

Copertura

• Obiettivo: tutti i comuni italiani (7.904 al 2024) rappresentati in silver.territories con almeno un record attivo
• Metrica: (territori_con_record_attivo / totale_comuni_istat) × 100
• Soglia: FAIL se <99%, WARNING se 99–99,9%, PASS se 100%

Accuratezza

• Obiettivo: tutti i record in silver.territory_attributes portano un territory_id valido che risolve a una riga in silver.territories
• Metrica: (record_con_territory_id_valido / totale_record) × 100
• Soglia: FAIL se <99,9%

Tempestività

• Obiettivo: le pipeline di acquisizione completano l'esecuzione entro le finestre di schedulazione definite
• Metrica: durata del flow run come riportata da Prefect
• Soglia: <24h per le pipeline di fondazione e prioritarie

Lineage

• Obiettivo: tracciabilità completa dall'URL sorgente → file Bronze → record Silver
• Metrica: % dei record Silver con fonte, anno_rif compilati e una voce corrispondente in bronze.ingestion_log
• Soglia: 100%

Pipeline di validazione

Il framework di data quality di ogni pipeline viene eseguito come Flow 3 immediatamente dopo il flow di trasformazione. Si tratta di un framework custom che verifica i file Bronze tramite DuckDB e i record Silver tramite query SQL; i risultati sono persistiti nel log del run Prefect e l'esito complessivo viene scritto come tag Qualità su OpenMetadata. Un controllo fallito blocca il Flow 4 (registrazione dei metadati) per evitare la registrazione di lineage per dati incompleti.

Validazione delle pipeline di fondazione

Verifiche di integrità temporale

Dopo l'esecuzione delle quattro pipeline di fondazione in sequenza, le seguenti asserzioni SQL devono restituire zero righe o zero conteggi.

-- (1) Nessun duplicato attivo per lo stesso type_code e id territorio
SELECT type_code, COUNT(*) AS duplicati
FROM silver.territories
WHERE valid_to IS NULL
GROUP BY type_code, id
HAVING COUNT(*) > 1;

-- (2) Nessuna inversione di date (valid_from successivo a valid_to)
SELECT id FROM silver.territories
WHERE valid_to IS NOT NULL AND valid_from > valid_to;

-- (3) Ogni territorio ha almeno un identificatore
SELECT t.id FROM silver.territories t
LEFT JOIN silver.territory_identifiers ti ON ti.territory_id = t.id
WHERE ti.id IS NULL;

-- (4) Ogni comune attivo è contenuto in una provincia
SELECT t.id FROM silver.territories t
WHERE t.type_code = 'COM'
  AND t.valid_to IS NULL
  AND NOT EXISTS (
    SELECT 1 FROM silver.territory_containments tc
    WHERE tc.territory_id = t.id AND tc.container_type_code = 'PRO'
  );

Verifica della copertura

SELECT
  COUNT(*)             AS comuni_attivi,
  7904                 AS baseline_istat_2024,
  ROUND(COUNT(*) * 100.0 / 7904, 2) AS copertura_pct
FROM silver.territories
WHERE type_code = 'COM'
  AND valid_to IS NULL;

La tabella seguente riporta le soglie applicate dal framework alle metriche di copertura e integrità della fondazione territoriale. Sono criteri di accettazione, non risultati di produzione: lo stato di validazione di ciascun dataset è rilevabile dalla dashboard ETL (sincronizzazione last_sync del 12/06/2026), fonte autorevole dello stato per-dataset.

Metrica	Soglia PASS	Soglia FAIL
Comuni attivi	= 7.904 (baseline ISTAT 2024)	conteggio difforme con copertura <99%
Copertura	100%	<99% (WARNING tra 99% e 99,9%)
Violazioni temporali	0	qualsiasi violazione
Identificatori orfani	0	qualsiasi voce orfana
Violazioni contenimento	0	qualsiasi comune attivo privo di provincia

Validazione delle correzioni territoriali

Il framework verifica che le correzioni territoriali note siano riflesse in silver.territories e nelle tabelle correlate. La tabella elenca i casi e l'esito atteso secondo i criteri applicati; la verifica sui dati di produzione è tracciata dalla dashboard ETL.

Correzione	Chiave di ricerca (COD_CATASTO)	Esito atteso
Baranzate (MI) valid_to non aggiornato	A618	valid_to IS NULL
Castegnero (VI) alias ADM	C056	nome alias presente in territory_names

Validazione delle pipeline attributo

Le pipeline attributo risolvono gli identificatori sorgente in territory_id mantenuti dalla fondazione territoriale e popolano silver.territory_attributes. Il framework applica a ciascuna le stesse classi di criteri di accettazione (copertura, accuratezza, tempestività, lineage). La tabella riporta le soglie applicate, illustrate sulla pipeline di riferimento ADM Tabaccherie; lo stato di validazione effettivo dei singoli dataset è rilevabile dalla dashboard ETL.

ADM Tabaccherie

Metrica	Soglia
Copertura comunale	≥95%
Fallimenti di risoluzione	0%
Tempo di esecuzione	<24h
Completezza lineage	100%

Le stesse soglie si applicano alle ulteriori pipeline attributo man mano che il team di sviluppo le porta in produzione; l'avanzamento per-dataset è tracciato dalla dashboard ETL.

Benchmark di performance

Il criterio di tempestività fissa per le pipeline di fondazione e prioritarie una soglia di completamento del flow run inferiore a 24 ore, misurata da Prefect. La tabella riporta i volumi di dati attesi per le pipeline principali, che dimensionano l'elaborazione rispetto a tale soglia. I tempi di esecuzione effettivi sono registrati nei log dei flow run Prefect e non sono disponibili in forma consolidata al di fuori di tali log; lo stato di esecuzione per-dataset è rilevabile dalla dashboard ETL.

Pipeline	Record elaborati (attesi)
variazioni-amministrative (ingestion)	~500K eventi
province-regioni (transform)	~120 entità
comuni (transform)	~8.000 comuni × finestre temporali
territory-corrections	~20 patch
ADM Tabaccherie	~8.000 comuni

Problemi identificati e risoluzioni

Problema #1: Instabilità dei codici comunali nelle riorganizzazioni provinciali

Descrizione: i comuni che hanno cambiato codice ISTAT a seguito di eventi di Assegnazione Provinciale (AP) non potevano essere risolti solo tramite codice, producendo record duplicati o mancanti nelle implementazioni naive. Soluzione: il flow di trasformazione dei comuni utilizza un algoritmo union-find per raggruppare tutte le varianti di codice dello stesso comune fisico sotto un unico territory_id stabile, identificato dal codice catastale Belfiore (COD_CATASTO), invariante rispetto alle riorganizzazioni provinciali. Tutti i codici ISTAT storici vengono conservati come voci in silver.territory_identifiers con i relativi intervalli valid_from/valid_to. Stato: Risolto

Problema #2: Timeout nello scraping del portale ADM

Descrizione: il portale JSF/PrimeFaces ADM andava in timeout dopo 10 minuti sulle pagine che elencavano molti comuni per provincia. Soluzione: timeout aumentato a 30 minuti; implementato retry con backoff esponenziale nella utility rate_limiter. Stato: Risolto

Governance e tracciabilità in OpenMetadata

L'esito della validazione non resta confinato nei log dei flow run, ma viene pubblicato nel catalogo dati come tag, rendendo lo stato di qualità di ciascun dataset consultabile direttamente da OpenMetadata. La tracciabilità si fonda su una tassonomia di tag che classifica ogni entità lungo più dimensioni:

• Layer: collocazione nel pattern Medallion (bronze, silver, gold).
• AmbitoMacro, AmbitoMeso, AmbitoMicro: classificazione tematica gerarchica del contenuto del dataset, articolata su tre livelli di crescente granularità (circa 7 tag macro, 28 meso, 56 micro).
• Fonte: ente o sistema di origine del dato.
• Qualità: esito della validazione del Flow 3.
• ProfonditaStorica: estensione temporale della serie.
• Audience e Privacy: destinatari e classificazione di riservatezza.

Il tag Qualità è l'esito diretto del framework di data quality e assume quattro valori, due per ciascun layer validato: bronze-validato e bronze-in-revisione per i controlli sul file grezzo, silver-validato e silver-in-revisione per i controlli sui record EAV. Il valore validato viene scritto quando tutti i controlli del rispettivo layer superano le soglie definite; in caso contrario il dataset resta in-revisione e il Flow 4 non procede alla registrazione del lineage.

La scrittura del tag Qualità è in corso di estensione a tutti i flow di data quality. Allo stato attuale circa 13 dei 46 flow di data quality scrivono il tag su OpenMetadata; i restanti circa 33 devono ancora implementarne la scrittura. Il completamento di questa copertura è in capo al team di sviluppo e procede secondo il rollout per-dataset; la dashboard ETL è la fonte autorevole dello stato di validazione di ciascun dataset.

Riconciliazione territoriale e normalizzazione ai territori 2025

La validazione della serie storica richiede di confrontare osservazioni pubblicate sulla geografia amministrativa di anni diversi. Poiché i confini comunali italiani cambiano nel tempo, principalmente per fusione, un confronto diretto sugli identificatori territoriali fallisce in corrispondenza degli anni di variazione. La metodologia di riconciliazione proietta tutte le osservazioni storiche su una geografia di riferimento fissa — i comuni attivi al 31 dicembre dell'anno-obiettivo, attualmente il 2025 — riconducendo le varianti di codice di uno stesso comune fisico a un identificatore stabile tramite la chiusura transitiva delle catene di successione, e aggregando i valori dei comuni confluiti secondo il tipo di misura della variabile.

L'aggregazione segue cinque regole, scelte in base alla natura della grandezza e definite per colonna:

• sum (quantità estensive): i valori dei comuni confluiti si sommano. Si applica a popolazione, numero di imprese, abitazioni e in generale ai conteggi e ai totali.
• mean (grandezze intensive riferite alla popolazione): tassi, percentuali su popolazione e redditi medi si combinano come media dei valori dei predecessori pesata sulla loro popolazione alla data della fusione.
• mean_area (grandezze intensive riferite all'area): percentuali di uso e consumo di suolo si combinano come media pesata sulla superficie dei confini amministrativi.
• last (valori categoriali e amministrativi): per le etichette e le codifiche territoriali (zona altimetrica, zona climatica, codice NUTS3, classificazione morfologica) si assume il valore del comune con popolazione maggiore alla data della fusione.
• none (variabili non riconciliabili): per le grandezze il cui metodo di aggregazione non è ancora stabilito, o per cui la riconciliazione è metodologicamente inappropriata, il risultato è NULL per i comuni nati da fusione, con segnalazione all'utente; le osservazioni dei comuni non coinvolti in fusioni passano invariate.

La regola di aggregazione è un metadato di colonna, memorizzato in datastore.variable_definitions.aggregation_rule. Viene inferita in automatico da euristiche sul tipo e sul nome dell'attributo e completata e validata colonna per colonna dai data steward: è il passo che rende riconciliabile l'intera serie storica di un dataset. I pesi di popolazione provengono dalla vista materializzata gold.population_weights (ISTAT ASTER per il 2002–2018, ISTAT DEMO POS dal 2019, contigue e riferite al 1° gennaio); i pesi di superficie dalle geometrie dei confini amministrativi. Nell'applicazione corrente la metodologia gestisce le 348 estinzioni di comuni registrate dall'ISTAT dal 1991. La metodologia completa — catene di successione, build pluriennali, fonti dei pesi e limitazioni note — è descritta in gst-maps-pipelines/docs/reconciliation-methodology-it.md.

Validazione di contenuto a cura dei data steward

La verifica tecnica (capitolo 5) accerta che ogni fase abbia prodotto un risultato presente e strutturalmente corretto; la correttezza di contenuto del dato richiede invece un giudizio umano, affidato ai data steward e articolato su tre attività.

La prima è la validazione dei metadati di dataset e colonne in OpenMetadata — etichette, descrizioni, dimensioni e tag. In questa fase i data steward completano anche la definizione delle regole di aggregazione per la riconciliazione ai territori 2025, colonna per colonna, come descritto nella sezione precedente.

La seconda è la verifica della corrispondenza Bronze↔Gold: tramite il Datastore i data steward generano le tabelle Gold di una o più fonti e confrontano i valori nelle tabelle finali con quelli del file Bronze originale, accertando che la catena di acquisizione, pulizia e normalizzazione non abbia introdotto perdite o alterazioni. È la validazione QA/QC sull'acquisizione, pulizia e normalizzazione dei dataset raw che dà il nome a questo deliverable.

La terza è il ritorno verso lo sviluppo: i problemi rilevati nei dati o nelle funzionalità dell'applicazione sono segnalati su ClickUp e presi in carico dal team di sviluppo per la correzione. Il ciclo si chiude quando una nuova verifica conferma la correzione e lo stato del dataset viene aggiornato nella dashboard.

Raccomandazioni

Le raccomandazioni seguenti riguardano attività di rollout e di consolidamento in capo al team di sviluppo. Il framework di data quality, i criteri di accettazione, le asserzioni di integrità temporale, la tassonomia dei tag e la metodologia di riconciliazione sono già consegnati e operativi; quanto segue ne completa l'applicazione sui dati di produzione e ne irrobustisce l'esercizio.

Breve termine (rollout per-dataset)

1. Completare la scrittura del tag Qualità nei flow di data quality che ancora non lo producono (circa 33 dei 46), così da rendere visibile lo stato di validazione di tutti i dataset nel catalogo.
2. Aggiungere un vincolo FK a livello di database su silver.territory_attributes.territory_id per applicare l'integrità referenziale al layer di storage e non solo al layer applicativo.
3. Configurare gli alert Prefect (email o Slack) sui fallimenti delle pipeline di fondazione, in modo che le regressioni di qualità dei dati vengano rilevate prima dell'esecuzione delle pipeline downstream.

Medio termine (consolidamento)

1. Schedulare le verifiche automatiche di integrità temporale (le asserzioni SQL della sezione §2) come flow Prefect giornaliero.
2. Schedulare in Prefect il ricalcolo periodico della vista materializzata gold.population_weights, così che i pesi di popolazione restino allineati alle nuove estinzioni.
3. Implementare l'acquisizione incrementale per i dataset SITUAS per evitare il re-download completo ad ogni run della pipeline.

Lungo termine

1. Estendere i criteri di accettazione esposti in OpenMetadata oltre il tag Qualità binario, riportando come metriche di dataset i valori di copertura e integrità della fondazione territoriale e rendendo visibile lo stato di salute del grafo territoriale nel catalogo.
2. Integrare le verifiche di integrità temporale nella pipeline CI in modo che le regressioni nella logica di trasformazione vengano rilevate prima del deployment.

Conclusioni

La strategia di validazione del Data Lake MAPS tratta l'integrità temporale come il gate di qualità principale. Poiché ogni pipeline attributo risolve infine gli identificatori sorgente in valori territory_id mantenuti dalla fondazione territoriale, la correttezza di quella fondazione — espressa attraverso catene valid_from/valid_to coerenti e gerarchie di contenimento complete — è la condizione necessaria per qualsiasi asserzione di qualità downstream.

Quanto consegnato in materia di validazione è completo e operativo: il framework di data quality custom eseguito come Flow 3, i criteri di accettazione e le soglie per copertura, accuratezza, tempestività, integrità temporale e lineage, le asserzioni SQL di controllo, la tassonomia dei tag di OpenMetadata con il tag Qualità come esito della validazione, e la metodologia di riconciliazione territoriale che gestisce 348 estinzioni di comuni tramite la vista gold.population_weights. Restano in capo al team di sviluppo l'esecuzione sui dati di produzione e il rollout per-dataset, in particolare il completamento della scrittura del tag Qualità nei flow di data quality che ancora non lo producono. Coerentemente con la relazione di consegna, la fonte autorevole dello stato di validazione di ciascun dataset è la dashboard ETL, che ne garantisce la verificabilità nel tempo.