Documents et données

Dictionnaire de données pour un CSV : documenter chaque colonne

Un CSV peut s’ouvrir sans erreur tout en restant difficile à interpréter. Découvrez comment documenter les noms, types, codes, valeurs manquantes, unités et dates à l’aide d’un modèle pratique.

Apification
Exemple de dictionnaire de données pour un CSV avec colonnes, types, codes et règles relatives aux valeurs manquantes

Un CSV lisible n’est pas toujours interprétable

Un fichier CSV peut s’ouvrir correctement dans un tableur et pourtant laisser des questions élémentaires sans réponse : que représente chaque colonne ? Une valeur telle que « 3 » est-elle une quantité ou un code ? Une cellule vide signifie-t-elle que la donnée ne s’applique pas ou qu’elle est inconnue ? Le format organise les valeurs en lignes et en colonnes, mais n’explique pas à lui seul la signification de chaque champ ni s’il doit être renseigné. Le [Guide des données tabulaires CSV de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf) indique que le format CSV ne comprend aucun mécanisme permettant de préciser le type de données d’une colonne ou si ses valeurs sont obligatoires. Ce manque de contexte peut amener deux équipes à interpréter différemment le même ensemble de données.

Le dictionnaire de données lève cette ambiguïté en décrivant chaque colonne et en définissant des règles d’interprétation explicites. Il ne remplace pas le CSV et ne corrige pas ses données : il accompagne le fichier afin que ses destinataires puissent le comprendre et l’utiliser selon des critères cohérents. Il est particulièrement utile lorsque le fichier circule entre différents services, est intégré à un autre système ou est mis à jour fréquemment. L’objectif pratique est qu’une personne n’ayant pas participé à la création du fichier puisse comprendre la signification de chaque valeur et savoir comment traiter une exception.

  • Si une colonne contient des codes, ne présumez pas que leur signification est évidente.
  • Si une donnée peut être manquante, précisez ce que signifie chaque forme d’absence.
  • Si un nombre a une unité, une devise ou une échelle, documentez-la avec le champ.
Un CSV lisible n’est pas toujours interprétable

Ce que le dictionnaire documente et ce qui n’en relève pas

Le dictionnaire décrit le contenu : noms des variables, signification, type ou format attendu, unités et, le cas échéant, valeurs codées avec leurs libellés. Il peut également préciser si un champ peut être absent et comment interpréter une valeur manquante. Par exemple, indiquer que le champ « état » utilise des codes ne suffit pas : il faut préciser ce que représente chaque code. Dans sa description des dictionnaires, le DANE mentionne le nom de la variable, son type ou format et, pour les catégories codées, le code et le libellé correspondant. La documentation doit correspondre à la structure réelle du tableau : chaque champ décrit correspond à une colonne, et chaque observation ou enregistrement occupe une ligne.

Ne confondez pas le dictionnaire avec un manifeste de livraison, qui peut recenser les fichiers, les dates ou les versions reçues, ni avec un guide d’exportation, qui explique comment le fichier a été généré. Ces documents peuvent se compléter, mais répondent à des questions différentes. Le dictionnaire n’est pas non plus l’endroit où répéter les lignes de données ou répertorier chaque fichier d’un dossier. Séparer ces objectifs facilite les mises à jour : modifiez la description lorsqu’une règle ou un champ change, et actualisez les informations de livraison lorsque le contenu partagé évolue.

  • Dictionnaire : ce que signifie chaque colonne et comment interpréter ses valeurs.
  • Manifeste : les fichiers qui font partie d’une livraison.
  • Guide d’exportation : la façon dont le fichier est obtenu ou préparé.
Ce que le dictionnaire documente et ce qui n’en relève pas

Modèle minimal pour chaque colonne

Commencez par créer une ligne de documentation pour chaque en-tête du CSV. Reprenez le nom exact de la colonne afin qu’il soit facile de faire le lien entre la fiche et le fichier. Ajoutez une description précise, le type ou format attendu, l’unité si nécessaire, les valeurs autorisées ou le vocabulaire utilisé, ainsi que l’indication précisant si le champ peut être absent. Ajoutez également toute règle complémentaire, par exemple si le champ est calculé à partir d’autres champs. Une définition utile clarifie l’interprétation au lieu de simplement reformuler le nom. Le [guide de procédures pour les registres administratifs du DANE](https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf) décrit les éléments d’une fiche par variable, comme le nom, le type ou le format, le code et, le cas échéant, le libellé.

Ne laissez pas les éléments essentiels à l’appréciation du lecteur. « Date » est trop général s’il est important de savoir si l’on enregistre la date de création ou de clôture ; « montant » est incomplet sans devise ni unité ; « catégorie » ne précise pas quelles options sont valides. Si l’ensemble de données ne repose pas encore sur une règle fixe, indiquez que celle-ci reste à définir au lieu de présenter une supposition comme une norme. Faites des descriptions brèves, mais suffisamment détaillées pour permettre de prendre des décisions sans consulter la personne qui a produit le fichier.

  • nom_colonne : identique à l’en-tête du CSV.
  • signification : ce que le champ représente et, si utile, ce qu’il ne représente pas.
  • type/format : par exemple, texte, entier ou date dans un format défini.
  • unité : par exemple, unités, kilogrammes ou devise précisée.
  • valeurs_autorisées : codes, libellés ou vocabulaire applicable.
  • absence : si elle est autorisée et comment elle est codée.
  • règle : origine ou calcul, lorsque le champ est dérivé.

Exemple fictif : codes, valeurs manquantes, dates et calculs

Prenons un fichier fictif de suivi de commandes, sans données personnelles. Le champ « état » pourrait être du texte comprenant les valeurs autorisées « ouvert », « en_cours » et « fermé », ou utiliser des codes numériques. Si des codes sont employés, le dictionnaire doit associer chacun à son libellé, par exemple : 1 = ouvert, 2 = en cours, 3 = fermé. Cet exemple ne définit pas une convention universelle : il montre pourquoi la correspondance doit être écrite et pourquoi il est préférable de conserver le même codage pour un même concept dans des livraisons liées.

Pour le champ « date_clôture », indiquez qu’il s’agit de la date de clôture de la commande, le format attendu et si le champ peut rester vide tant que la commande est ouverte. Si l’heure est importante, précisez également le fuseau horaire ou la règle temporelle utilisée ; ne laissez pas les différents lecteurs la déduire. Pour le champ « montant_total », indiquez la devise et si la valeur est calculée à partir d’autres données. Si une colonne calculée comporte un arrondi ou une autre règle, décrivez celle-ci de façon opérationnelle. Ces précisions permettent d’interpréter l’exemple sans en faire une norme pour d’autres ensembles de données.

  • état : 1 = ouvert ; 2 = en cours ; 3 = fermé.
  • date_clôture : date de clôture ; absence autorisée tant que la commande n’est pas fermée.
  • montant_total : montant dans une devise précisée ; noter la règle de calcul, le cas échéant.
  • quantité : nombre d’unités ; ne pas confondre une quantité égale à zéro avec une donnée manquante.

Définissez les absences, les unités et les vocabulaires

La distinction entre zéro, cellule vide et donnée inconnue est essentielle. Zéro peut être une valeur réelle ; une cellule vide peut signifier que la donnée est absente ; et un code tel que « -1 » peut représenter une donnée non obtenue, si cela a été défini ainsi. Ces cas ne sont pas équivalents. Le [Guide de la qualité des données ouvertes de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf) indique que zéro doit être représenté par « 0 » et qu’une valeur inconnue ou non obtenue doit être expliquée, en précisant le code utilisé dans le dictionnaire. Si les cellules vides peuvent être interprétées de plusieurs façons, décrivez explicitement ces interprétations ; le [Guide pour la publication de données ouvertes de Datos Argentina](https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf) recommande également de les expliciter. Si les cellules vides indiquent toujours une absence, documentez cette règle sans inventer de catégories supplémentaires.

Pour les champs catégoriels, énumérez les options valides et leur signification, et utilisez un codage cohérent pour les concepts équivalents. Pour les champs numériques, indiquez l’unité ou la devise : « 12 » ne suffit pas pour savoir s’il s’agit de pièces, d’heures ou d’une somme d’argent. La [fiche de données tabulaires CSV de datos.gob.es](https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf) recommande de documenter les unités associées aux valeurs numériques et de conserver un codage cohérent. Pour les dates et les heures, précisez le format et le fuseau horaire lorsque cela s’applique, et décrivez l’événement enregistré par le champ. Ces précisions réduisent les erreurs de lecture et d’intégration, mais ne garantissent pas à elles seules que toutes les valeurs du CSV respectent les règles : le fichier doit toujours être vérifié.

  • Distinguez la valeur zéro, la cellule vide et le code indiquant une donnée inconnue ou non obtenue.
  • Précisez si l’absence est autorisée et dans quelles conditions.
  • Indiquez l’unité, la devise, le format et le fuseau horaire lorsqu’ils sont pertinents.
  • Définissez les catégories et les codes avec les libellés correspondants.

Vérifiez le CSV et son dictionnaire comme un seul ensemble

Avant de partager les fichiers, comparez un à un les en-têtes du CSV et les fiches du dictionnaire : repérez les colonnes non documentées, les anciens noms et les champs décrits qui n’existent plus. Vérifiez ensuite les exemples et les valeurs autorisées par rapport aux données réelles. Si le dictionnaire indique qu’un champ n’accepte que trois codes, vérifiez que les valeurs observées figurent dans cette liste ou consignez et résolvez l’exception. Cette lecture conjointe permet de détecter les contradictions qui passent inaperçues lorsque chaque fichier est examiné séparément.

Il est utile de faire relire les fichiers par une personne qui n’a pas préparé les données. Demandez-lui d’expliquer la signification d’une colonne, la façon dont elle traiterait une cellule vide et l’unité qu’elle attribuerait à un nombre. Si elle doit deviner, améliorez la documentation. Conservez une copie modifiable pour les révisions ultérieures et associez chaque dictionnaire à la livraison du CSV correspondante. Si le schéma ou une règle de signification change, mettez la documentation à jour en même temps ; ne comptez pas sur une note informelle ou sur un nom de fichier pour reconstituer le contexte.

  • Vérifier que les en-têtes et les fiches correspondent exactement.
  • Comparer les codes, unités, formats et exemples aux données.
  • Rechercher les règles contradictoires concernant les champs obligatoires et les absences.
  • Noter la version du dictionnaire qui accompagne chaque CSV.
  • Demander à une personne n’ayant pas préparé les données d’interpréter quelques champs.

Références et conservation de la documentation

Ces guides étayent les recommandations concernant la structure tabulaire, les fiches par variable, les codes, les unités et les absences. Consultez les sources pour examiner leurs conventions et les appliquer en fonction des besoins de votre ensemble de données :

Conservez le CSV et son dictionnaire ensemble ou dans une structure permettant de savoir sans ambiguïté quelle documentation correspond à chaque fichier et à chaque version. Apification Cloud permet d’organiser des fichiers et des projets dans un espace versionné conçu pour le partage ; il permet également de créer et de modifier des fichiers bureautiques avec ONLYOFFICE dans Cloud. Cela peut aider à conserver la documentation modifiable avec les données. Lors du partage, identifiez clairement les deux éléments ainsi que la livraison à laquelle ils appartiennent. L’outil aide à organiser et à partager les fichiers ; la définition de leur signification et la vérification de leur cohérence restent de la responsabilité de l’équipe.

  • Guide des données tabulaires CSV, datos.gob.es : https://datos.gob.es/sites/default/files/doc/file/guia_csv_vf.pdf
  • Aide-mémoire : données tabulaires CSV, datos.gob.es : https://datos.gob.es/sites/default/files/doc/file/cheat_sheet_csv_vf.pdf
  • Guide de la qualité des données ouvertes, datos.gob.es : https://datos.gob.es/sites/default/files/doc/file/guia_calidad_de_datos_abiertos.pdf
  • Procédures pour les registres administratifs, DANE : https://www.dane.gov.co/files/sen/registros-administrativos/cooperacionBID/peru/peru_procedimientos.pdf
  • Guide pour la publication de données ouvertes, Datos Argentina : https://datosgobar.github.io/paquete-apertura-datos/pdf/anexo-II-guia-abiertos.pdf
  • Nommez les deux fichiers de façon à rendre leur relation claire.
  • Conservez une version modifiable du dictionnaire avec la livraison correspondante.
  • Utilisez l’historique des versions pour consulter ou restaurer d’anciennes versions si nécessaire.

Questions fréquentes

Le dictionnaire de données doit-il inclure une ligne pour chaque valeur du CSV ?

Non. En règle générale, il documente chaque colonne et ses règles. Pour une colonne codée, il est utile d’indiquer la correspondance entre les codes et les libellés, mais il ne faut pas reproduire tous les enregistrements.

Comment documenter une cellule vide ?

Indiquez si elle signifie une absence et ce que celle-ci représente dans le champ concerné. Si plusieurs interprétations sont possibles, décrivez chaque cas et précisez comment les distinguer. Ne l’assimilez pas automatiquement à zéro.

Puis-je utiliser un tableur comme dictionnaire ?

Oui. Un tableau modifiable est un moyen pratique de conserver une fiche par colonne. L’essentiel est de définir clairement les champs et de faire correspondre la documentation à la version du CSV livrée.

Un dictionnaire garantit-il que le CSV respecte ses règles ?

Non. Il explique les règles et facilite l’interprétation, mais il faut comparer le fichier à la documentation. La vérification conjointe aide à repérer les divergences et les exceptions.

Sources et lectures

Documentation consultée pour préparer cet article.

Découvrez Apification

Articles associés

Retour au blog