Documenti e dati

Dizionario dei dati per un CSV: come documentare ogni colonna

Un CSV può aprirsi senza errori e restare comunque difficile da interpretare. Scopri come documentare nomi, tipi, codici, valori mancanti, unità e date con un modello pratico.

Apification
Esempio di dizionario dei dati per CSV con colonne, tipi, codici e regole per i valori mancanti

Un CSV leggibile non è sempre interpretabile

Un file CSV può aprirsi correttamente in un foglio di calcolo e lasciare comunque senza risposta alcune domande fondamentali: che cosa rappresenta ogni colonna? Un valore come «3» è una quantità o un codice? Una cella vuota significa che il dato non è applicabile o che è sconosciuto? Il formato organizza i valori in righe e colonne, ma non spiega di per sé il significato di ogni campo né se debba essere compilato. La [Guida ai dati tabellari CSV di datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf) segnala che il CSV non include un meccanismo per indicare il tipo di dato di una colonna o se i suoi valori debbano essere obbligatori. Questa mancanza di contesto può indurre due gruppi a interpretare in modo diverso lo stesso insieme di dati.

Il dizionario dei dati risolve questa ambiguità fornendo una descrizione per ogni colonna e regole esplicite per interpretarla. Non sostituisce il CSV né corregge i suoi dati: accompagna la consegna affinché chi la riceve possa comprenderla e utilizzarla secondo criteri coerenti. È particolarmente utile quando il file passa tra reparti, viene integrato in un altro sistema o aggiornato frequentemente. L’obiettivo pratico è permettere a chi non ha partecipato alla creazione del file di riconoscere il significato di ogni valore e sapere come gestire le eccezioni.

  • Se una colonna contiene codici, non dare per scontato che il loro significato sia evidente.
  • Se un dato può mancare, specifica che cosa rappresenta ciascuna forma di assenza.
  • Se un numero ha un’unità, una valuta o una scala, documentala insieme al campo.
Un CSV leggibile non è sempre interpretabile

Che cosa documenta e che cosa resta escluso

Il dizionario descrive il contenuto: nomi delle variabili, significato, tipo o formato previsto, unità e, quando opportuno, valori codificati con le relative etichette. Può anche indicare se un campo ammette valori mancanti e come interpretare un valore nullo. Per esempio, non basta dire che «stato» usa dei codici: bisogna indicare che cosa rappresenta ciascun codice. Nella descrizione dei dizionari, il DANE include il nome della variabile, il tipo o formato e, per le categorie codificate, il codice e la relativa etichetta. La documentazione deve corrispondere alla struttura effettiva della tabella: ogni campo descritto corrisponde a una colonna e ogni osservazione o record occupa una riga.

Non confonderlo con un manifesto di consegna, che può identificare file, date o versioni ricevute, né con una guida all’esportazione, che spiega come è stato generato il file. Questi documenti possono integrarsi, ma rispondono a domande diverse. Il dizionario non è nemmeno il posto in cui ripetere le righe di dati o elencare ogni file di una cartella. Tenere separati questi obiettivi semplifica gli aggiornamenti: modifica la descrizione quando cambia una regola o un campo e aggiorna le informazioni di consegna quando cambia il pacchetto condiviso.

  • Dizionario: che cosa significa ogni colonna e come interpretarne i valori.
  • Manifesto: quali file fanno parte di una consegna.
  • Guida all’esportazione: come si ottiene o si prepara il file.
Che cosa documenta e che cosa resta escluso

Modello minimo per ogni colonna

Inizia con una riga di documentazione per ogni intestazione del CSV. Includi il nome esatto della colonna per collegare facilmente la scheda al file. Aggiungi una descrizione concreta, il tipo o formato previsto, l’unità se pertinente, i valori consentiti o il vocabolario utilizzato e l’indicazione se il campo ammette valori mancanti. Se ci sono regole aggiuntive, per esempio se un campo è calcolato a partire da altri, registrale. Una definizione utile chiarisce come interpretare il campo e non si limita a riformularne il nome. La [guida alle procedure per i registri amministrativi del DANE](https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf) descrive gli elementi di una scheda per variabile, come nome, tipo o formato, codice ed etichetta, quando pertinenti.

Evita di lasciare gli aspetti essenziali alla discrezione del lettore. «Data» è troppo generico se è importante sapere se si registra il giorno di creazione o quello di chiusura; «importo» è incompleto senza valuta o unità; «categoria» non chiarisce quali opzioni siano valide. Se l’insieme di dati non ha ancora una regola fissa, indicarla come da definire è meglio che presentare un’ipotesi come norma. Mantieni le descrizioni brevi, ma abbastanza dettagliate da permettere di prendere decisioni senza dover contattare chi ha prodotto il file.

  • nome_colonna: identico all’intestazione del CSV.
  • significato: che cosa rappresenta e, se utile, che cosa non rappresenta.
  • tipo/formato: per esempio testo, numero intero o data con formato definito.
  • unità: per esempio unità, chilogrammi o una valuta specificata.
  • valori consentiti: codici, etichette o vocabolario applicabile.
  • valori mancanti: se sono ammessi e come vengono codificati.
  • regola: origine o calcolo, se il campo è derivato.

Esempio fittizio: codici, valori nulli, date e calcoli

Considera un file fittizio per il monitoraggio degli ordini, privo di dati personali. Il campo «stato» potrebbe essere testo con i valori consentiti «aperto», «in_lavorazione» e «chiuso», oppure utilizzare codici numerici. Se si usano codici, il dizionario deve associare ciascuno alla propria etichetta, per esempio: 1 = aperto, 2 = in lavorazione, 3 = chiuso. L’esempio non stabilisce una convenzione universale: mostra perché la corrispondenza deve essere documentata e perché è utile mantenere la stessa codifica per uno stesso concetto nelle consegne correlate.

Per «data_chiusura», documenta che si tratta della data in cui l’ordine viene chiuso, il formato previsto e se il campo può restare vuoto finché l’ordine è aperto. Se l’ora è importante, specifica anche il fuso orario o la regola temporale adottata: non lasciare che lettori diversi la deducano autonomamente. Per «importo_totale», indica la valuta e specifica se il campo viene calcolato a partire da altri valori. Se una colonna calcolata prevede arrotondamenti o altre regole, descrivile in modo operativo. Questi dettagli rendono l’esempio interpretabile senza trasformarlo in una norma per insiemi di dati diversi.

  • stato: 1 = aperto; 2 = in lavorazione; 3 = chiuso.
  • data_chiusura: data di chiusura; valore mancante ammesso finché l’ordine non è chiuso.
  • importo_totale: importo espresso in una valuta specificata; annotare la regola di calcolo, se pertinente.
  • quantità: numero di unità; non confondere una quantità pari a zero con un dato mancante.

Definisci valori mancanti, unità e vocabolari

La distinzione tra zero, cella vuota e valore sconosciuto è fondamentale. Lo zero può essere un valore reale; una cella vuota può indicare un dato mancante; un codice come «-1» potrebbe rappresentare un dato non raccolto, se così è stato definito. Non sono equivalenti. La [Guida alla qualità dei dati aperti di datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf) indica che lo zero deve essere rappresentato come «0» e che un valore sconosciuto o non raccolto deve essere spiegato, specificando nel dizionario il codice utilizzato. Se gli spazi vuoti possono avere più interpretazioni, descrivile esplicitamente; anche la [Guida alla pubblicazione di dati aperti di Datos Argentina](https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf) raccomanda di chiarirle. Se indicano sempre un dato mancante, documenta questa regola senza inventare categorie aggiuntive.

Per i campi categoriali, elenca le opzioni valide e il loro significato e utilizza una codifica coerente per concetti equivalenti. Per i campi numerici, indica l’unità o la valuta: «12» non basta per sapere se si tratta di pezzi, ore o una somma di denaro. La [scheda dei dati tabellari CSV di datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf) raccomanda di documentare le unità associate ai valori numerici e di mantenere una codifica coerente. Per date e orari, chiarisci il formato e il fuso orario, quando pertinente, e descrivi quale evento registra il campo. Queste precisazioni riducono gli errori di lettura e integrazione, ma non garantiscono da sole che tutti i valori del CSV rispettino le regole: è comunque necessario controllare il file.

  • Distingui il valore zero, la cella vuota e il codice per un dato sconosciuto o non raccolto.
  • Spiega se i valori mancanti sono ammessi e in quali condizioni.
  • Indica unità, valuta, formato e fuso orario quando sono pertinenti.
  • Definisci le categorie e i codici con le rispettive etichette.

Controlla il CSV e il dizionario come un’unica consegna

Prima di condividere i file, confronta una per una le intestazioni del CSV con le schede del dizionario: cerca colonne non documentate, nomi non più aggiornati e campi descritti che non sono più presenti. Verifica poi che gli esempi e i valori consentiti corrispondano ai dati effettivi. Se il dizionario afferma che un campo ammette solo tre codici, controlla che i valori osservati corrispondano a quell’elenco oppure registra e risolvi l’eccezione. Esaminare insieme i due file permette di rilevare contraddizioni che potrebbero passare inosservate controllandoli separatamente.

È utile chiedere a qualcuno che non ha preparato i dati di esaminarli. Chiedigli di spiegare che cosa significa una colonna, come gestirebbe una cella vuota e quale unità assocerebbe a un numero. Se deve tirare a indovinare, migliora la documentazione. Conserva una copia modificabile per le revisioni future e collega ogni dizionario alla consegna specifica del CSV. Quando cambia lo schema o una regola di significato, aggiorna contemporaneamente la documentazione: non fare affidamento su una nota informale o sul nome di un file per ricostruire il contesto.

  • Verificare la corrispondenza esatta tra intestazioni e schede.
  • Confrontare codici, unità, formati ed esempi con i dati.
  • Cercare regole contraddittorie sui valori obbligatori e sui valori mancanti.
  • Registrare quale versione del dizionario accompagna ciascun CSV.
  • Chiedere a una persona estranea alla preparazione di interpretare alcuni campi.

Riferimenti e conservazione della documentazione

Queste guide supportano le raccomandazioni sulla struttura tabellare, le schede per variabile, i codici, le unità e i valori mancanti. Consulta le fonti per esaminarne le convenzioni e applicarle in base alle esigenze del tuo insieme di dati:

Conserva il CSV e il relativo dizionario insieme oppure in una struttura che renda inequivocabile quale documentazione corrisponde a ciascun file e a ciascuna versione. Apification Cloud consente di organizzare file e progetti in uno spazio versionato progettato per la condivisione; consente anche di creare e modificare file per l’ufficio con ONLYOFFICE all’interno di Cloud. Questo può essere utile per mantenere modificabile la documentazione insieme ai dati. Quando condividi i file, identifica chiaramente entrambi gli elementi e la consegna a cui appartengono. Lo strumento aiuta a organizzare e condividere i file; definire i significati e verificarne la coerenza resta responsabilità del gruppo.

  • Guida ai dati tabellari CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf
  • Scheda di consultazione: dati tabellari CSV, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf
  • Guida alla qualità dei dati aperti, datos.gob.es: https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf
  • Procedure per i registri amministrativi, DANE: https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf
  • Guida alla pubblicazione di dati aperti, Datos Argentina: https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf
  • Assegna ai due file nomi che ne rendano chiara la relazione.
  • Conserva una versione modificabile del dizionario insieme alla consegna corrispondente.
  • Usa la cronologia delle versioni per esaminare o recuperare versioni precedenti, quando necessario.

Domande frequenti

Il dizionario dei dati deve includere una riga per ogni valore del CSV?

No. Di norma documenta ogni colonna e le relative regole. Per una colonna codificata, è utile includere la corrispondenza tra codici ed etichette, ma non riprodurre tutti i record.

Come documento una cella vuota?

Indica se rappresenta un dato mancante e che cosa significa in quel campo. Se può avere più di un’interpretazione, descrivi ogni caso e come distinguerlo. Non equipararla automaticamente allo zero.

Posso usare un foglio di calcolo come dizionario?

Sì. Una tabella modificabile è un modo pratico per mantenere una scheda per ogni colonna. L’importante è definire chiaramente i campi e assicurarsi che la documentazione corrisponda alla versione del CSV consegnato.

Un dizionario garantisce che il CSV rispetti le sue regole?

No. Spiega le regole e facilita l’interpretazione, ma è necessario confrontare il file con la documentazione. La revisione congiunta aiuta a trovare discrepanze ed eccezioni.

Fonti e approfondimenti

Documentazione consultata per preparare questo articolo.

Scopri Apification

Articoli correlati

Torna al blog