Proposer un jeu de données

Un jeu de données qui tient dans un ou plusieurs tableaux entre au Lexicon sans une ligne de code : un dossier, une fiche qui le décrit, et les tableaux en CSV. La commande ./lexicon contribute relit ce dossier comme le fera un mainteneur d'OSFarm et dit, en français et ligne à l'appui, ce qui reste à corriger.

En bref

1. Installer l'outil sur son poste.
2. Préparer le tableau et l'enregistrer en CSV.
3. Remplir la fiche dataset.yml.
4. Vérifier avec ./lexicon contribute, corriger, recommencer.
5. Proposer le dossier une fois la réponse [ OK ] obtenue.

1. Installer l'outil

Il faut Git et Docker. L'outil est le dépôt du Lexicon lui-même ; son premier lancement construit une image, ce qui prend quelques minutes.

git clone https://github.com/osfarm/lexicon.git
cd lexicon
cp .env.dist .env
./lexicon new releves_sol --tabular

La dernière commande affiche le modèle de fiche pour un jeu nommé releves_sol. Le nom du jeu est en minuscules, sans accent ni espace.

2. Préparer le tableau

Créer le dossier du jeu dans data/contributions/ et y enregistrer le tableau depuis le tableur : « Enregistrer sous », format CSV, encodage UTF-8, séparateur virgule.

data/contributions/releves_sol/
├── dataset.yml      la fiche
└── releves.csv      le tableau

• La première ligne donne le nom des colonnes, en minuscules, sans accent ni espace : insee_code, pas « Code INSEE ».
• Une colonne identifie chaque ligne : jamais vide, jamais deux fois la même valeur.
• Les dates s'écrivent 2026-09-30, les nombres avec un point (12.5), les oui/non true ou false.
• Une case vide veut dire « pas de valeur » : elle est acceptée partout, sauf dans la colonne qui identifie les lignes.

id,insee_code,measured_on,value
r1,17387,2026-09-01,12.5
r2,28085,2026-09-02,
r3,33063,2026-09-02,14

3. Remplir la fiche

Enregistrer le modèle sous data/contributions/releves_sol/dataset.yml, puis remplacer chaque texte d'exemple. La fiche dit ce qu'est le jeu, d'où il vient, sous quelle licence, et ce que contient chaque colonne.

description: Relevés d'humidité des sols par commune
author: Camille Martin, GAEC des Prés
source:
  name: Relevés de sondes capacitives
  url: https://exemple.org/sondes
  provider: GAEC des Prés
  licence: Licence Ouverte 2.0
  licence_url: https://www.etalab.gouv.fr/wp-content/uploads/2017/04/ETALAB-Licence-Ouverte-v2.0.pdf
  date: 2026-09-30
tables:
  - file: releves.csv
    key: id
    columns:
      id: text
      insee_code: text
      measured_on: date
      value: number
    pivots:
      insee_code: commune

Les types de colonnes

Les liens avec les autres jeux

Sous pivots, on dit qu'une colonne porte un identifiant partagé : insee_code: commune. Le jeu est alors relié aux autres, par exemple sur la page d'une commune.

4. Vérifier

./lexicon contribute releves_sol

Chaque ligne « à corriger » nomme le fichier, la colonne et les cases en cause. Les lignes « à savoir » ne bloquent pas. La commande compte ce qui reste :

  à corriger : La fiche garde pour « author » le texte du modèle, « Prénom Nom, organisme » : le remplacer.
  à corriger : « releves.csv », colonne « value » : 2 valeurs ne sont pas un nombre, avec un point pour les
               décimales (ligne 2 « 12,5 », ligne 5 « abc »).
  à corriger : « releves.csv » : 1 valeur de « id » revient plusieurs fois (r2).
[ NOK ] releves_sol : 3 points à corriger avant de proposer le jeu.

Corriger, relancer la commande, jusqu'à cette réponse :

[  OK ] releves_sol peut être proposé (releves.csv → registered_releves_sol). Un mainteneur le construit
        et le publie avec ./lexicon ship releves_sol

Dans un navigateur

Le plus simple est de passer par la page web, sur votre poste : on y dépose son tableau tel qu'il est (CSV, Excel ou LibreOffice) et la fiche se remplit toute seule. Les colonnes sont reconnues et renommées, leur type est deviné, les dates et les nombres sont remis en forme, la colonne qui identifie chaque ligne est choisie. Il reste à vérifier ce qui a été reconnu et à dire d'où vient le jeu.

./lexicon contribute --web

Ouvrir ensuite http://localhost:8787. La page ne répond que sur votre poste et n'envoie rien ; Ctrl-C l'arrête.

Ce que la commande dit de la fiche

Ce qu'elle dit d'un tableau

Ce qu'elle signale sans bloquer

Ce qu'elle ne vérifie pas

• Que les identifiants des colonnes de lien existent : un code de commune inconnu n'est vu qu'à la construction du jeu, par le mainteneur.
• Que les valeurs sont justes : elle lit leur forme, pas leur sens.
• Que la licence écrite est bien celle de la source : c'est à vous de le dire.

5. Proposer

Quand la commande répond [ OK ], envoyer le dossier par une demande de fusion sur le dépôt du Lexicon, ou le transmettre à un mainteneur d'OSFarm. Le mainteneur relit le jeu, le construit et le publie ; il apparaît alors au catalogue, avec votre nom dans les crédits.

Ce qu'un tableau ne sait pas faire

Télécharger sa source, transformer les données, porter une géométrie, se lier à un autre jeu par une clé étrangère. Pour cela il faut écrire une source de données en Ruby : voir le guide du dépôt.