Focus : Construire un schéma TableSchema
PrécédentEtape 4 : Phase de promotion et de maintienSuivantIntégrer un schéma de données à schema.data.gouv.fr
Dernière mise à jour
Cet article vous a-t-il été utile ?
Guides de data.gouv.fr
Dernière mise à jour
Cet article vous a-t-il été utile ?
La pertinence de la mise en place d'un standard de données réside dans son adéquation entre les capacités de sa mise en oeuvre par les producteurs de données et les outils permettant l'automatisation des jeux de données valides par rapport à cette spécification.
Cette standardisation doit permettre de faciliter la mise en relation des jeux de données issus de différents producteurs.
Un des formats privilégiés pour les standards de données est le (Comma Separated Values, valeurs séparées par des virgules). Il s'agit d'un format de données "à plat", adéquat pour les structures de données simples.
Cependant, ce format simple ne dispose pas de spécifications contraignant la saisie des données. Pour cela un schéma en Json est ajouté dont la structure est défini par le standard . TableSchema permet d'indiquer les formats des données attendus, de spécifier des contraintes (types de valeurs, cardinalité) et de documenter les différents champs composant le schéma.
L'outil de validation utilisé pour vérifier la conformité d'un fichier csv au standard auquel il fait référence s'appuie sur la structure tabulaire des données. Elles peuvent donc être contenues dans un tableur numérique au format .xls, .xlsx ou .ods ou dans un fichier texte au format .csv, .txt ou autre.
La question du séparateur utilisé pour séparer deux champs de données dans un fichier .csv n'est donc pas essentielle. Cependant, certains outils se basent sur la valeur de ce séparateur pour traiter et publier des jeux de données. Nous vous proposons donc un certain nombre de recommandations afin de favoriser la généralisation d'un usage contribuant à l'interopérabilité des données produites.
Bien que de nombreux jeux de données en CSV utilisent le point-virgule comme séparateur de champs, il a été décidé de privilégier le séparateur virgule car plus conforme à l'esprit du format csv.
Les tableurs numériques courants (Excel et Calc) peuvent produire et lire des fichiers csv. Lors de l'enregistrement d'un fichier créé avec l'outil Calc, l'utilisatrice ou utilisateur doit spécifier le format d'encodage des données ainsi que le séparateur de champs. Lorsque le séparateur de champs retenu est la virgule, il est recommandé d'utiliser les guillemets double " comme séparateur de chaîne de caractères. De cette manière, si une virgule est présente à l'intérieur d'une cellule elle ne sera pas considérée comme un séparateur de champs.
Lors de l'ouverture d'un fichier csv dans Calc, une fenêtre modale propose plusieurs options permettant de spécifier un caractère de séparation et un encodage des données.
Dans Excel, il faut aller dans l'onglet données et sélectionner l'option Fichier texte pour accéder à l'assistant d'import des données.
Pour faciliter la lecture des fichiers publiés en CSV il est recommandé d'y associer dans les outils de publication le type MIME ou Content-Type "text/csv".
Chaque ligne du fichier doit avoir le même nombre de champs, ce qui signifie que lorsqu'une cellule est vide elle doit quand même être présente soit avec la valeur Null, soit avec des crochets vides [] dans le cas des champs de type tableau (array), soit laissée vide mais apparaître à l'export avec 2 virgules qui se suivent ,, .
Ce standard dispose des types de données suivants :
string : s'applique pour toutes les chaînes de caractères
number : s'applique pour les chiffres et nombres contenant éventuellement des décimales
integer : s'applique pour les chiffres et nombres entiers
boolean : s'applique pour indiquer que la valeur d'un champs ne peut être égale qu'à "vrai" ou "faux" (ou "1" et "0" ou "oui" ou "non")
object : s'applique pour les données de type objet
array : s'applique pour les tableaux de données
Les types de données peuvent être assortis de formats de données facilitant l'automatisation de leur validation.
Pour déclarer un format de données dans un schéma JSON il est possible d'utiliser différentes propriétés permettant de le caractériser :
name : le nom du champ
title : le titre du champ
description : la description des valeurs attendues dans ce champ
format : le format du champ
type : le type du champ
Il est également possible de contraindre les valeurs autorisées dans ce champ à l'aide de plusieurs proriétés :
required : indique l'obligation de la présence d'une valeur pour ce champ dans toutes les lignes du fichier
unique : indique que chaque valeur de ce champ à l'intérieur du fichier doit être unique
minLength : indique la taille minimale des valeurs de ce champ
maxLength : indique la taille maximale des valeurs de ce champ
minimum : indique la valeur minimum autorisée pour ce champ (par exemple pour une date on peut indiquer une année en deça de laquelle les valeurs ne sont pas autorisées)
maximum : indique la valeur maximale autorisée pour ce champ
pattern : indique une expression régulière à laquelle doivent être conforme les valeurs de ce champ (par exemple pour un numéro SIRET on peut indiquer ^\\d{14}$ ce qui signifie que les valeurs de ce champ doivent contenir exactement 14 chiffres)
enum : indique une liste de valeurs autorisées pour ce champ
Le champ permettant d'indiquer le numéro SIRET d'une collectivité est spécifiée de la manière suivante :
Le champ permettant d'indiquer la date de publication d'un enregistrement du jeu de données est spécifié de la manière suivante :
Les informations ci-dessous décrivent les différents types de champs disponibles dans la spécification TableSchema.
Pour le type string, les formats de données suivants sont disponibles :
default : n'importe quelle chaîne de caractère
email : une adresse email valide.
motif de validation :
uri : une URI valide
binary : une chaîne de caractère encodées en base 64 représentant des données binaires.
uuid : une chaîne de caractère représentant un identifiant unique.
Description : Les valeurs décimales doivent utiliser le point afin d'être plus facilement exploitables par les tableurs numériques.
Type : number
Exemple : 3900.50
Type : date
Exemple : 2017-10-15
Format : "%Y-%m-%d"
Nommage : abreviation-du-schemaDate
Type : datetime
Exemple : 1997−07−16T19:20:00
Type : datetime
Exemple : 1997−07−16T08:30/17:30
Description : horaires indiquant les heures d'ouverture d'un service ou d'un commerce. Ce type de données permet de préciser les différents horaires d'ouverture pour les différents jours de la semaine. Il s'agit donc d'un type de données multi-valeur au sein duquel le nom du jour de la semaine est abrégé et suivi par les heures d'ouvertures. Les abréviations pour les jours sont en anglais (Mo, Tu, We, Th, Fr, Sa, Su) et les horaires sont sous la forme HH:MM
Type : string (chaîne de caractères)
Exemple : Mo 08:15-13:15; Tu 03:15-06:15; We 03:15-09:30; Th 02:30-07:15; Fr 01:30-05:45; Sa 00:30-05:00; Su 02:45-08:30
Nommage : abreviation-du-schemaHoraires
La possibilité est laissée de décrire les points de géolocalisation d'une donnée à l'intérieur d'un champ unique (geopoint) ou à l'aide de 2 champs (latitude et longitude).
Type : number
Exemple : 48.563433
Nommage : abreviation-du-schemaLat
Type : number
Exemple : 2.572875
Nommage : abreviation-du-schemaLon
Type : number
Exemple : "48.563433, 2.572875"
Nommage : abreviation-du-schemaGeo
Description : ce type de données permet de décrire la forme géographique d'un équipement. La forme est décrite à l'aide de paires de coordonnées, séparées par un espace vide et chaque paire séparée par une virgule. La description d'une ligne est exprimée à l'aide de 2 ou plus paires de points séparés par des virgules. La description d'un polygone est exprimée par 4 ou plus paires de points séparés par des virgules dont la dernière est identique à la première.
Type : string
Exemple : "48.563433 2.572875, 49.234933 2.134432, 49.885311 2.134003, 48.974635 2.1134567, 48.563433 2.572875"
Ce type de champ permet de décrire l'adresse postale d'un équipement. Il est décomposé entre 3 champs permettant de distinguer et de faciliter le tri à l'intérieur des informations de voirie, de code postal et de commune. Le numéro et le nom de la voie sont séparés par une virgule.
Description : ce type de champs permet de saisir le numéro et le nom de la voie
Type : string
Exemple : 34, rue de Latresne
Nommage : abreviation-du-schemaVoie
Description : ce type de champs permet de saisir le code postal (ou le code INSEE) de la commune
Type : number
Exemple : 45800
Nommage : abreviation-du-schemaCodePostal
Description : ce type de champs permet de saisir le nom de la commune
Type : string
Exemple : Saint-Jean-de-Braye
Nommage : abreviation-du-schemaCommune
Afin d'unifier la description des données au travers des différentes thématiques abordées par le propositions de standard de données, il est fortement recommandé de rendre obligatoire la présence d'un certains nombre de champs.
Ceux-ci contribuent à la portabilité des données (qui produit la donnée) ou à leur fiabilité (quand a été produite la donnée).
Pour l'identification des autorités publiques à l'origine de la production et de la publication des jeux de données, il est recommandé d'indiquer le nom et le numéro de SIRET sur chaque ligne de chaque jeu de données.
Description : ce champs permet de saisir le nom de l'autorité publique responsable de la production des données
Type : string
Exemple : Conseil départemental de la Creuse
Nommage : abreviation-du-schemaColl
Par exemple
Description : ce champ permet d'indiquer le numéro d'identification de l'autorité publique au sein de la base nationale des établissements.
Type : string
Exemple : 21330063500017
Motif : ^\d{14}$
Nommage : nom-ou-abreviation-du-schemaCollSiret
Par exemple :
Pour faciliter la réutilisation et la mise à jour des données, il est recommandé de fournir aux réutilisatrices et réutilisateurs potentiels des dates de première publication et de dernière modification pour chaque entité du jeu de données.
Ces informations au format Date avec horaire peuvent correspondre à la date de première publication et faire apparaître les dates de dernière modification pour l'ensemble des lignes ou en cas de mise à jour partielle pour une ligne de données particulière.
Il est également recommandé d'y associer un champ permettant de décrire la raison ayant entraîné une mise à jour des données depuis leur publication.
Description : ce champs permet de décrire la date de première publication de la donnée
Type : datetime
Exemple : 2020-05-11T14:08:32Z
Nommage : nom-ou-abreviation-du-schemaPublicationDate
Par exemple :
Description : ce champs permet de décrire la date de dernière modification de la donnée
Type : datetime
Exemple : 2020-05-11T14:08:32Z
Nommage : nom-ou-abreviation-du-schemaModificationDate
Par exemple :
Description : ce champs permet de décrire la raison d'une modification de la donnée depuis sa publication initiale
Type : string
Exemple : changement dû à un aléa de livraison
Nommage : nom-ou-abreviation-du-schemaModificationInfo
Par exemple :
Les fichiers doivent, sauf exception et autant que possible, respecter les règles de nommage suivantes :
AAAAMMJJ_idProducteur_nom-du-fichier.extension
AAAAMMJJ : Date de création du fichier
nom-du-fichier Chaîne de caractères dont les termes, en minuscules non accentuées, sont séparés par un tiret du milieu
.extension : Si les règles de formatage sont respectées, l'extension est .csv
Les 3 éléments constitutifs de la chaîne principale avant l'extension sont assemblés en un seul tenant et séparés par un tiret du bas.
Exemple : '20180314_213502388_prenoms-nouveaux-nes-rennes-2017.csv'
Afin d'uniformiser les fichiers produits dans le cadre de schémas de standardisation, il est recommandé de normaliser les intitulés des champs composant chaque standard.
La règle générale préconisée est l'utilisation de l'écriture camelCase où chaque mot composant l'intitulé du champ est écrit avec une majuscule à l'exception du premier.
En complément il est recommandé d'utiliser un préfixe (mot complet ou abréviation) pour l'ensemble des champs d'un standard.
En conséquence, pour le standard des menus, les intitulés des champs sont préfixés par le mot menu suivi des intitulés à proprement dit. Par exemple :
menuCollNom
menuRestaurantIdType
menuRepasType
Aucun caractère accentué ou spécial ne doit être utilisé dans l'intitulé d'un champ. Il est également préconisé de ne pas dépasser 50 caractères pour l'intitulé d'un champ et d'utiliser le singulier pour les mots composant l'intitulé du champ.
Pour garantir la conformité des jeux de données, il est demandé aux producteurs de s'assurer que la structure, les champs et les contenus attendus sont effectivement respectés.
De fait, les fichiers tabulaires doivent, autant que possible, contenir :
Toutes les colonnes, y compris celles dont les cellules ne sont pas renseignées, dans le bon ordre, et avec des en-têtes correctement nommées sur la première ligne ;
Autant de lignes que nécessaire comprenant des cellules dont les valeurs peuvent être obligatoires (elles doivent être impérativement renseignées) ou optionnelles (elles sont seulement recommandées ou soumises à condition de disponibilité / pertinence).
L’encodage des caractères à privilégier est l' de manière à garantir une meilleure interopérabilité des données.
Les recommandations de formatage pour les données sont généralement issues du standard , lui-même inspiré des spécifications du format , dans lequel sont exprimés les schémas de données permettant l'automatisation de leur validation.
Ci-dessous quelques exemples tirés du .
Description : date au format AAAA-MM-JJ suivant la norme internationale .
Description : date au format aaaa-mm-jjThh:mi:ssZZZZZZ suivant la norme internationale . On considérera que ZZZZZZ (+ou- décalage horaire GMT), est par défaut +01:00 en France et qu'il est inutile de le préciser dans les formats.
Description : date au format aaaa-mm-jjThh:mi/hh:mi suivant la norme internationale ISO 8601. Ce type de données s'applique pour un créneau horaire dans la même journée, sans les secondes. Pour une extension de ces conditions, voir la norme .
Un assistant graphique en ligne permet de générer simplement cette structure de données
Description : ce type de données permet de saisir la coordonnée de latitude exprimée en permettant de localiser un équipement. Le signe de séparation entre les parties entière et décimale du nombre est le point. Précision : 6 décimales maximum.
Description : ce type de données permet de saisir la coordonnée de longitude exprimée en permettant de localiser un équipement. Le signe de séparation entre les parties entière et décimale du nombre est le point. Précision : 6 décimales max.
Description : ce type de données permet de saisir les coordonnées de latitude et de longitude exprimée en permettant de localiser un équipement. Le signe de séparation entre les parties entière et décimale du nombre est le point. Précision : 6 décimales max. Le séparateur de valeur est la virgule. Il est donc nécessaire d'entourer ces valeurs de guillemets. La première valeur est la latitude
idProducteur : Numéro sur 9 chiffres pour identifier le producteur