**Ceci est une ancienne révision du document !**

Mode d’emploi Validata

(Réf : ODF/v0.1/4avr19)

Introduction

Validata est une plateforme de validation de données ouvertes produites par des acteurs territoriaux. Elle offre à ses utilisateurs la possibilité de vérifier la conformité de ces données par rapport aux modèles définis dans le cadre du Socle Commun des Données Locales (SCDL). En détectant d'éventuelles erreurs ou anomalies, en amont ou en aval de leur publication, elle aide à harmoniser les données locales ouvertes, elle engage à améliorer leur qualité et elle facilite leur exploitation par les réutilisateurs.

Coordonné par OpenDataFrance, Validata est un projet collaboratif et ouvert. Il s'appuie sur les expertises croisées de Jailbreak, La Fing et Datactivist. Il associe de nombreux acteurs territoriaux en tant que souscripteurs (participation au financement) et/ou expérimentateurs (tests et retours d’usage). Il est soutenu par l'Etat dans le cadre du Programme d'Investissements d'Avenir (PIA2 pour le “développement de l’open data au sein des territoires”) et suivi par la mission Etalab de la DINSIC. Les sources de la plateforme, briques techniques et schémas de validation, sont déposées et accessibles sur le GitLab d'OpenDataFrance.

Principes

Le socle commun des données locales Le Socle Commun des Données Locales définit un ensemble de jeux de données prioritaires, normalisés et communs aux collectivités territoriales. Dans un premier temps, les données relatives aux compétences générales et à celles des communes sont proposées. Les données spécifiques aux Interco (EPCI), départements et régions (et autres compétences particulières CCAS…) seront abordées ultérieurement. On rappelle que la loi République Numérique rend obligatoire pour toutes les collectivités de plus de 3500 habitants (et de plus de 50 agents) l’ouverture par défaut, en opendata, de « toutes les informations dont la publication présente un intérêt économique, social, sanitaire ou environnemental” à l’exception des informations protégées lorsqu’elles peuvent porter atteinte à la vie privé, à la sécurité ou à des droits particuliers (propriété intellectuelle, secret commercial…). Le Socle Commun des Données locales ne restreint pas cette obligation mais il aide à la mise en œuvre d’un ensemble cohérent, interopérable et prioritaire de données produites au niveau local afin de constituer un gisement national de qualité. Il se fixe comme objectifs de :

  • Eviter à tout prix la dispersion de données non homogènes (format et nature)
  • Coproduire un socle commun national
  • Faciliter l’identification, la production et la réutilisation des données
  • Favoriser la qualité des données plus que leur nombre

Les spécifications sont disponibles sur les espaces en ligne suivants :

  • Socle Commun des Données Locales (version finalisée) : scdl.opendatafrance.net
  • Evolution du Socle Commun des Données Locales (version de travail) : opendatafrance.gitbook.io/scdl/

L’outil de validation Validata

Validata propose des modules de test pour chaque jeu de données standardisés. Les spécifications des jeux de données standardisés du SCDL sont traduites sous forme de modules exécutables (schémas). Chaque module vérifie la conformité du jeu de données vis-à-vis des contraintes de format et de contenu des données concernées. La plateforme de validation est basée sur une architecture Frictionlessdata, de portée internationale, et intégrant de nombreux modules utiles à aux fonctionnalités de Validata. Le groupement portant le projet Validata développe des modules spécifiques lorsque cela est nécessaire (). L’architecture générale est décrite ici (https://git.opendatafrance.net/validata/validata-core/wikis/architecture) :

Modules de validation

Chaque spécification du SCDL est donc traduite sous forme de module exécutable dans la couche TableSchéma de FrictionLessData : https://frictionlessdata.io/specs/table-schema/

Exemple de schéma sont développés pour les Infrastructures de recharge électrique : https://github.com/etalab/schema.data.gouv.fr/blob/master/irve/schema.json

Chaque module présents dans Validata est suivi en configuration (numéro de version). Chaque module donne un lien vers la spécification du jeu de données concernées.

Fonctionnalités générales de Validata

Validata permet essentiellement de :

  • Tester la structure générale du fichier soumis validation (format, encodage, …)
  • Tester la présence, l’ordre et le titre exact des colonnes des fichiers soumis à validation
  • Tester la conformité de la structure de chaque champ du jeu de données soumis à validation

Portée des test de Validata Les modules de Validata testent :

  • La conformité de la structure du fichier soumis : Formats acceptés : csv, txt, xls, …, Encodage : UTF8, …
  • Le séparateur de colonne : “,” pour les formats CSV, “;” pour les formats xls
    * La présence obligatoire des colonnes, leur ordre, leur nomination exacte (sensible à la casse)
  • La conformité des cellules de la table vis-à-vis des contraintes indiquées dans le schéma concernées (et hérité des spécifications).

Certaines erreurs sont bloquantes : le test est interrompu immédiatement. Certaines erreurs sont graves mais Validata peut poursuivre le test du jeu de données en s’adaptant. Certaines anomalies ne sont signalées que comme des “Avertissements” et non comptabilisées dans le total des erreurs.

Les erreurs rencontrées sont détaillées par Validata en contexte (IHM) et dans le log.

Restitution des erreurs

En ligne :
  • Restitution des erreurs en contexte (mapping de la table, cellule en erreur colorée et sur passage du curseur, affichage du niveau d’erreur et des contraintes du champs)

* Fichier de Log comportant une synthèse du nombre d’erreurs constatées, par exemple : La table est invalide, 9 erreurs détectées, Aucune erreur de structure, - Erreurs de contenu (9) : format incorrect : 2, n° siret invalide : 4, valeur incorrecte : 2, valeur maximale non respectée : 1 - 6 lignes en erreur sur 8 lignes au total

  • Le détail de chaque erreur constatée en contexte.

Un badge synthétique indiquant la qualité générale du fichier (conforme, non conforme avec indication chiffrée du % d’erreur constatées).

via API :
  • Fichier de Log (cf supra)
  • Badge synthétique (cf supra)
Le badge synthétique

Le badge synthétique fonctionne de la façon suivante :

  • Aucune erreur > picto vert avec label “Valide”
  • Structure invalide : Validata ne peut pas poursuivre le test ou les erreurs sont considérées comme bloquantes > picto rouge avec label “structure invalide”
  • Erreurs non bloquantes : Validata comptabilise le nb de cellule en erreur et élabore le pourcentage de conformité par rapport au nombre total de cellule (nb ligne x nb de colonne) > picto orange avec label “cellules valides : 50.0 %”

Exemple : {{:badge_validata_.png?200|

Nb : certaines erreurs étant considérées par paramétrage comme bénignes, un coefficient de pondération amoindrit leur contribution au calcul du pourcentage d’erreur. La liste des erreurs (code, description, criticité et coef. éventuel de pondération est présentée en annexe). Algorithme de calcul : https://scdl.opendatafrance.net/docs/badge.html

Appel en ligne

Entrée : Il est possible d’activer Validata :

  • En chargeant un fichier dans le module concerné
  • En indiquant l’url d’un fichier distant dans le module concerné

Il est possible de constater le fonctionnement de Validata en chargeant des fichiers d’exemple (avec ou sans erreur) proposés dans une liste déroulante.

Sortie : Les éléments restitués par Validata sont :

  • Badge synthétique
  • Synthèse du nombre d’erreur par type, par ligne et du nombre de ligne traitées
  • Fichier de Log
  • Erreurs en contexte
Automatisation (API)

Une API est disponible pour lancer à distance les tests de fichiers dans Validata. L’API est décrite ici : https://go.validata.fr/api/v1/apidocs#/

Entrée : Les paramètres d’appel sont essentiellement :

  • Module de test concerné
  • l’Url du fichier à tester
  • Paramètres optionnels

Sortie : L’API rend les éléments suivants :

  • Badge synthétique
  • Synthèse du nombre d’erreur par type, par ligne et du nombre de ligne traitées
  • Fichier de Log
  • Autres informations

Description de l’API

L'API est documenté sur le site de Validata : https://go.validata.fr/api/v1/apidocs

Mode d’emploi
  • Se connecter à la plateforme : go.validata.fr
  • Choisir le module concerné par le test (parmi l’ensemble des modules traduisant les spécifications)

En ligne:

  • Charger le fichier (ou l’url)
  • Lancer le test
  • Récupérer les résultats

Par API :

  • voir documentation de l'API

En cas d’anomalie de fonctionnement de Validata, envoyer un mail à : validata@opendatafrance.email

Il existe un forum pour discuter du fonctionnement et des évolutions de Validata : https://riot.im/app/#/room/#validata:jailbreak.paris

Et aussi un forum pour les évolutions du Socle Commun des Données Locales : https://teamopendata.org/c/socle-commun-des-donnees-locales