Modèle pour les dépôts CNIG de standards

Ce dépôt contient les fichiers nécessaires pour démarrer la création d'un dépôt pour un standard, il est conforme à ce qui est demandé pour un schéma Table Schema.

Utiliser ce template

• Si vous créez votre dépôt sur GitHub, il vous suffit d'appuyer sur le bouton vert "Use this template". Consultez la documentation pour plus d'infos ;

Fichiers disponibles

Ce dépôt contient un ensemble de fichiers utiles pour un dépôt d'un schéma Table Schema.

• CHANGELOG.md contient la liste des changements entre les différentes versions de votre schéma ;
• exemple-valide.csv est un fichier CSV d'exemple conforme par rapport au schéma décrit dans schema.json ;
• LICENSE.md est le fichier de licence du dépôt. Nous recommandons d'utiliser la Licence Ouverte, cette licence est recommandée par l'administration française pour le partage de données et de documents ;
• README.md est le fichier que vous lisez actuellement. À terme, il devra présenter votre schéma ;
• requirements.txt liste les dépendances Python nécessaires pour effectuer des tests en intégration continue sur votre dépôt ;
• schema.json est le schéma au format Table Schema.

Intégration continue

Ce dépôt est configuré pour utiliser de l'intégration continue, si vous utilisez GitHub. À chaque commit, une suite de tests sera lancée via GitHub Actions afin de vérifier :

• que votre schéma est valide à la spécification Table Schema ;
• que vos fichiers d'exemples sont conformes au schéma.

Si vous n'utilisez pas GitHub, vous pouvez lancer ces tests sur votre machine ou sur un autre service d'intégration continue comme Gitlab CI, Jenkins, Circle CI, Travis etc. Consultez la configuration utilisée dans .github/workflows/test.yml.

Localement, voici la procédure à suivre pour installer l'environnement de test et lancer les tests :

# Création d'un environnement virtuel en Python 3
python3 -m venv venv
source venv/bin/activate

# Installation des dépendances
pip install -r requirements.txt

# Test de la validité du schéma
frictionless validate --type schema schema.json

# Test de la conformité des fichiers d'exemples
frictionless validate --schema schema.json exemple-valide.csv

Étapes à suivre

Nous détaillons ci-dessous les étapes que nous vous conseillons de suivre après avoir créé votre dépôt Git, tout en utilisant les fichiers d'exemples.

• Décrire votre schéma dans le fichier schema.json en respectant la spécification Table Schema. Le fichier d'exemple comprend des valeurs d'exemples pour toutes les métadonnées possibles. Notez que les champs d'exemple ne comprennent qu'une petite partie des types, formats et contraintes disponibles, référez-vous à la documentation pour toutes les valeurs possibles. Si certaines métadonnées ne sont pas nécessaires pour votre projet, vous pouvez les supprimer. Pour vérifier que votre schéma est conforme, vous pouvez utiliser l'outil tableschema en ligne de commande : tableschema validate schema.json
• Modifier le fichier d'exemple CSV avec des données conforme à votre schéma. L'outil frictionless permet de vérifier que vos fichiers sont conformes au schéma en ligne de commande frictionless validate --schema schema.json exemple-valide.csv
• Modifier le fichier CHANGELOG.md pour indiquer la publication initiale
• Modifier le fichier README.md, en supprimant tout son contenu tout d'abord. Au sein de plusieurs paragraphes, vous indiquerez le contexte, les modalités de production des données, le cadre juridique, la finalité, les cas d’usage etc. Consultez plusieurs schémas sur schema.data.gouv.fr pour découvrir quelles informations sont pertinentes à indiquer
• Vérifier que la licence ouverte vous convient. Si vous devez utiliser une autre licence, modifiez le fichier LICENSE.md et indiquez la licence dans le fichier schema.json, dans la clé licenses

Documentation

Pour vous aider dans la construction de votre dépôt, nous vous recommandons de vous référer à :

• Le guide à destination des producteurs de schéma
• La documentation de schema.data.gouv.fr
• La spécification Table Schema