Vai al contenuto

Perché questa guida

Molti dati pubblicati si rivelano difficili da usare solo quando li si apre: colonne spostate, totali mescolati ai dettagli, date scritte in tre modi. Chi li riusa deve prima ripulirli, e a volte rinuncia. Il problema non riguarda il contenuto ma il modo in cui il file è stato preparato, e si può prevenire con poche regole.

Questa guida è per chi in un ente ha i dati in un foglio di calcolo o in un gestionale, deve pubblicarli e non programma. Spiega cos'è un CSV, dà 15 regole per prepararlo e dice come esportarlo da Excel o LibreOffice.

Perché il CSV

  • La tabella è la forma più comune per scambiare dati, e si ottiene in molti modi: fogli di calcolo, esportazioni da gestionali e database, tabelle HTML.

  • Su dati.gov.it, il portale nazionale, oltre 45 mila dataset su circa 74 mila hanno una risorsa in CSV: è il formato più presente (novembre 2026).

  • Sul portale europeo sono quasi 300 mila: più numerosi sono solo i servizi di mappa WMS e WFS (novembre 2026).

  • È conciso e si lascia leggere sia dalle persone sia dai programmi. I dati sono disposti in tabella: i valori sono separati da un carattere, le righe da un'interruzione di riga.

  • Per aprirlo non serve un programma specifico: basta un editor di testo, disponibile su tutti i sistemi operativi.

Il suo limite

Un CSV non dice se una colonna contiene numeri o testo, né se un valore è obbligatorio. Per questo è facile che ci finiscano valori mancanti o tipi mescolati.

Il rimedio sta in tre cose: preparare bene il file (le regole), controllarlo (gli strumenti) e accompagnarlo con una descrizione delle colonne (il dizionario dei dati).

Cosa copre la guida

Le regole e gli strumenti di questa guida riguardano la forma del file: struttura, tipi, coerenza interna. Non dicono se i valori sono giusti: un file senza errori di formato può contenere un numero di prestiti sbagliato.

Le Linee guida AgID distinguono sei livelli di validazione, dalla coerenza con i requisiti strutturali al confronto con i dati di altri fornitori: i controlli descritti qui si fermano, in sostanza, ai primi due, cioè alla struttura e alla coerenza all'interno del dataset. Controllare il file non basta: AgID raccomanda di garantire almeno accuratezza, coerenza, completezza e attualità dei dati (raccomandazione 8).

Nel modello a 5 stelle il CSV arriva a 3 stelle, il livello minimo richiesto dalle Linee guida AgID. La quarta richiede RDF, un modo di descrivere i dati collegandoli fra loro, e SPARQL, il linguaggio per interrogarli. Valori uniformi e codici standard non fanno salire di stella, ma preparano quel passaggio.

Schema, licenza e metadati rispondono in parte ai principi FAIR (Findable, Accessible, Interoperable, Reusable): i metadati alla reperibilità, licenza e schema al riuso. Per chi pubblica dati sul web, il riferimento del W3C (World Wide Web Consortium) sono le Data on the Web Best Practices.

La guida e le norme

Questa guida è una buona pratica volontaria, non un atto normativo. Il CSV non è obbligatorio in sé: è un modo per rispettare gli obblighi qui sotto. Ultimo controllo dei riferimenti: 7 novembre 2026.

Obblighi di legge. Ogni norma ha i propri destinatari: controlla quali si applicano al tuo ente.

Regole tecniche, nelle Linee guida AgID (determinazione 183/2023):

  • formato aperto e leggibile meccanicamente, di almeno 3 stelle: il CSV le raggiunge (requisito 2);
  • metadati conformi al profilo italiano (DCAT-AP_IT) o, per i dati territoriali, alle Linee guida del Repertorio nazionale dei dati territoriali (RNDT) (requisiti 15 e 16), da inserire e tenere aggiornati su dati.gov.it o nel RNDT (requisiti 29 e 30);
  • licenza CC BY per i nuovi dati aperti nativi, cioè prodotti dalle amministrazioni; una licenza diversa da CC BY 4.0 o CC0 va motivata formalmente (requisiti 20 e 21).

Buona pratica: le regole di questa guida, che dettagliano ciò che le norme lasciano aperto. Dove riprendono l'Allegato B delle Linee guida AgID, sono indicazioni e non requisiti.

Quando il CSV non basta. I dati dinamici e le serie di dati di elevato valore vanno resi disponibili anche attraverso API, interfacce con cui un programma interroga i dati (requisiti 5 e 7; Regolamento di esecuzione (UE) 2023/138). Il CSV resta utile per lo scaricamento in blocco.

Come adottarla in un ente

Quella che segue è una proposta, non una procedura prevista da una norma.

Le Linee guida AgID raccomandano di affidare al Responsabile per la transizione digitale (RTD) un gruppo di lavoro sull'apertura dei dati (raccomandazione 4): quel gruppo può adottare questa guida come riferimento interno, citandone una versione precisa, con numero e DOI, come spiegato in Partecipa.

La guida può entrare anche nei contratti. Il CAD chiede di prevedere nei capitolati che riguardano formazione, raccolta e gestione di dati clausole che ne consentano l'utilizzazione (art. 52, comma 3). Le Linee guida AgID raccomandano un approccio «open by design» fin dalla progettazione, con clausole contrattuali sulla proprietà del dataset e sulla sua fruibilità nel tempo, compreso l'uso di formati aperti (par. 6.1.2).

Bozza di clausola, da adattare e da far rivedere a chi scrive i capitolati

I dati tabellari prodotti nell'ambito del contratto sono consegnati in formato CSV secondo quanto descritto dalla RFC 4180, dalle raccomandazioni dell'Allegato B delle Linee guida AgID (determinazione 183/2023) e dalle 15 regole della «Guida pratica alla pubblicazione di dati in CSV», versione [numero], e corredati di dizionario dei dati.

Al posto di [numero] scrivi la versione della guida che vuoi adottare, per esempio 1.0.1: quella corrente è indicata in fondo a ogni pagina, e il suo DOI nella pagina Partecipa.