Commit 9d272f9f authored by pascal romain's avatar pascal romain
Browse files

mise à jour avant fusion dans Etalab

parent 62382105
Pipeline #3215 passed with stages
in 10 minutes and 33 seconds
# Recommandations relatives aux jeux de données
La pertinence de la mise en place de standard de données réside dans son adéquation entre les capacités de mise en oeuvre par les producteurs de données et les outils automatisés de validation. Celle-ci doit permettre de **faciliter la mise en relation des jeux de données** issus de différents producteurs.
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 permattant 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.
Il ne s'agit donc pas de règles mais de recommandation, visant à faciliter la création de nouveaux schémas et **leur intégration dans une chaîne de validation et de publication généralisable**.
Il ne s'agit donc pas de règles mais de recommandations, visant à faciliter la création de nouveaux schémas et **leur intégration dans une chaîne de validation et de publication généralisable**.
## Recommandations pour le formatage des fichiers
## Recommandations pour le formatage des fichiers csv
### Format de fichier
Un des formats privilégiés pour les standards de données est le [CSV](https://fr.wikipedia.org/wiki/Comma-separated_values) \(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](https://specs.frictionlessdata.io/table-schema/). 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.
Actuellement le format privilégié par le SCDL est le [CSV](https://fr.wikipedia.org/wiki/Comma-separated_values) \(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**. Bien que de nombreux jeu 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.
::: tip
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'interpoérabilité des données produites.
### Format de fichier csv
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.
[fournir un exemple et la procédure associée dans Excel]
::: tip
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.
:::
L’encodage des caractères à privilégier est l'[UTF-8](https://fr.wikipedia.org/wiki/UTF-8) de manière à garantir une **meilleure interopérabilité 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 ,,
**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 ,, .
## Recommandations de formatage des données
Les recommandations de formatage pour les données sont généralement empruntées au format [TableSchema](https://specs.frictionlessdata.io/table-schema/), lui-même inspiré des spécifications du format [Json](https://www.json.org/json-fr.html) dans lequel sont exprimés les schémas de données permettant l'automatisation de leur validation.
Les recommandations de formatage pour les données sont généralement issues du standard [TableSchema](https://specs.frictionlessdata.io/table-schema/), lui-même inspiré des spécifications du format [Json](https://www.json.org/json-fr.html), dans lequel sont exprimés les schémas de données permettant l'automatisation de leur validation.
Ce standard dispose des types de données suivants :
......@@ -34,13 +47,6 @@ Ce standard dispose des types de données suivants :
Les types de données peuvent être assortis de formats de données facilitant l'automatisation de leur validation.
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
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
......@@ -60,7 +66,7 @@ Il est également possible de contraindre les valeurs autorisées dans 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
Ci-dessous quelques exemples tirés du schéma des menus de la restauration collective
Ci-dessous quelques exemples tirés du schéma des menus de la restauration collective.
Le champ permettant d'indiquer le numéro SIRET d'une collectivité est spécifiée de la manière suivante
......@@ -77,7 +83,7 @@ Le champ permettant d'indiquer le numéro SIRET d'une collectivité est spécifi
}
}
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
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 :
{
"name": "menuPublicationDate",
......@@ -90,7 +96,18 @@ Le champ permettant d'indiquer la date de publication d'un enregistrement du jeu
}
}
Les informations ci-dessous décrivent les différents types de champ disponible dans la spécification TableSchema
Les informations ci-dessous décrivent les différents types de champs disponibles dans la spécification TableSchema.
### Données de type string
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.
### Données de type décimal
......@@ -112,26 +129,31 @@ Les informations ci-dessous décrivent les différents types de champ disponible
* **Type** : datetime
* **Exemple** : 1997−07−16T19:20:00
### Données de type date avec heure de début et de fin
* **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 [ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601).
* **Type** : datetime
* **Exemple** : 1997−07−16T08:30/17:30
### Données de type horaires d'ouverture
* **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
::: tip
Un assistant graphique en ligne [yohours](https://projets.pavie.info/yohours) permet de générer simplement cette structure de données
:::
* **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
### Données de type géolocalisation
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).
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).
#### latitude
* **Description** : ce type de données permet de saisir la coordonnée de latitude exprimée en [WGS 84](https://fr.wikipedia.org/wiki/WGS_84) 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 : 66 décimales max.
* **Description** : ce type de données permet de saisir la coordonnée de latitude exprimée en [WGS 84](https://fr.wikipedia.org/wiki/WGS_84) 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.
* **Type** : number
* **Exemple** : 48.563433
* **Nommage** : abreviation-du-schemaLat
......@@ -154,7 +176,8 @@ La possibilité est laissée de décrire les points de géolocalisation d'une do
* **Exemple** : "48.563433 2.572875, 49.234933 2.134432, 49.885311 2.134003, 48.974635 2.1134567, 48.563433 2.572875"
### Données de type adresse
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.
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.
#### Voie
* **Description** : ce type de champs permet de saisir le numéro et le nom de la voie sur laquelle se trouve l'équipement à décrire
......@@ -174,9 +197,11 @@ Ce type de champ permet de décrire l'adresse postale d'un équipement. Il est d
* **Nommage** : abreviation-du-schemaCommune
## Recommandations de champs obligatoires
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)
### Identification du producteur
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.
#### Nom de la collectivité
......@@ -220,8 +245,11 @@ Par exemple :
}
#### Horodatage des données
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 date 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
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
##### Date de création/publication
......@@ -297,20 +325,23 @@ Les 3 éléments constitutifs de la chaîne principale avant l'extension sont as
* **Exemple** : '20180314_213502388_prenoms-nouveaux-nes-rennes-2017.csv'
## Recommandations pour la mise en conformité
## Recommnandations pour le nommage des champs
Pour garantir la conformité des jeux de données publiés par rapport aux spécifications SCDL, il est demandé aux producteurs de s'assurer que la structure, les champs et les contenus attendus sont effectivement respectés.
Afin d'uniformiser les fichiers produits dans le cadre de schémas de standardisation, il est recommande de normaliser les intitulés des champs composant chaque standard.
De fait, les fichiers tabulaires doivent, autant que possible, contenir :
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 :
- **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\)
- menuCollNom
- menuRestaurantIdType
- menuRepasType
## Recommandations pour la découvrabilité
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 faciliter la détection des jeux de données qui s'appuient sur les spécifications SCDL, ils doivent, autant que possible, être marqués avec des tags prédéfinis au moment où ils sont déposés sur une plateforme open data \(renseignement de la métadonnée 'tags' du catalogue\).
## Recommandations pour la mise en conformité
Les régles d'étiquetage des jeux de données sont les suivantes :
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.
- Un premier tag 'SCDL' doit être indifféremment ajouté à tous les jeux de données concernés
- Un ou plusieurs autre\(s\) tag\(s\) spécifique\(s\) doi\(ven\)t être ajouté\(s\) en fonction du jeu de données
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\)
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment