YamlDoc

YamlDoc est un système de gestion documentaire fondé sur :

1. l'organisation de documents correspondants principalement à des fichiers texte structurés au format Yaml,
2. l'utilisation, quand cela est adapté, pour les champs d'une sémantique bien connue (DublinCore, DCAT, Skos, Schema.org, GeoJSON, ...), conformément aux principes du Web des données,
3. la définition de classes de documents permettant, d'une part, de spécifier le contenu des documents par un schéma JSON et, d'autre part, d'associer à un document un comportement défini par une classe Php,
4. la possibilité de formatter les textes contenus dans un champ du fichier Yaml en utilisant le langage Markdown,
5. la visualisation des documents et fragments au moyen d'un visualiseur Web extensible grâce aux classes de documents,
6. un mécanisme de requête simple (ypath) dans les documents,
7. l'identification par un URI de chaque document et chacun de ses fragments, dont le déréférencement expose son contenu en JSON ou en JSON-LD,
8. la possibilité d'effectuer des recherches plein texte dans les documents,
9. l'organisation d'espaces documentaires partagés chacun sous la forme d'une archive Git, pouvant ainsi utiliser soit Github, soit une archive Git privée,
10. la définition de requêtes sur les documents en Php,

YamlDoc est notamment étendu pour permettre :

• l'accès aux données géographiques et la définition de cartes Leaflet,
• l'exploitation de catalogue de données géographiques,
• l'utilisation de thésaurus Skos comme EuroVoc,
• l'utilisation d'API de l'INSEE.

Idées pour la suite.

Fondé sur le format Yaml

Le format Yaml permet de structurer des documents ou des données par combinaison de listes, tableaux associatifs et données scalaires. Similaire au format JSON, il a l'avantage d'être très lisible pour nous les humains tout en étant facile à comprendre pour les machines.
Il permet de structurer aussi bien des documents composés principalement de textes comme le présent document, que des bases de données comme par exemple la base historique des communes, des structures de graphe comme le thésaurus EuroVoc ou des documents strcturés complexes comme le modèle de données Inspire déduit du règlement interopérabilité.
Enfin, l'édition de documents Yaml est fournie par divers éditeurs de texte comme Notepad++ sous Windows ou TextMate sur Mac.

Sémantique bien connue

Lorsque cela est adapté, la sémantique des champs des tableaux associatifs Yaml respecte les standards suivants :

• le standard Dublin Core pour décrire les métadonnées d'un document ; ainsi il est recommandé d'utiliser des champs Dublin Core (comme title, subject, description, date, ...) pour définir les métadonnées de chaque document (synthèse des principaux champs ici) ;
• le standard W3C DCAT pour décrire les catalogues de jeux de données,
• le standard W3C SKOS (résumé ici) encodé en Yaml pour représenter des thésaurus comme le thésaurus EuroVoc ou le lexique topographique de l'AFT ;
• le standard Schema.org pour structurer des bases de données, telles que par exemple des listes d'organismes en utilisant le type Organization,
• le standard IETF GeoJSON pour décrire des bases de données géographiques vecteur, plus de détails ici.

Définition de classes de documents

Une classe de documents correspond à:

• un schéma JSON,
• une classe d'objets Php définissant:
  • des méthodes de consultation interactive du document,
  • une API REST de consultation en machine to machine,
  • une API Php d'utilisation du document en interne à YamlDoc.

Par exemple la classe YamlSkos définit des documents qui correspondent à un thésaurus décrit en SKOS. Ainsi, le schéma JSON précise coment le thésaurus doit être structuré en Yaml, et la classe Php permet :

• d'afficher en HTML le thésaurus ou une de ses parties (Concept, micro-thésaurus),
• d'exposer une API REST de consultation du thésaurus ou d'une de ses parties,
• de fournir des méthodes Php pour utiliser le thésaurus.

La gestion des classes est développée dans ce document.

Markdown

Le langage Markdown est utilisé pour formatter des textes (titres, gras, italique, liste de puces, liens URL, ...) ; son utilisation est illustrée ici. Les différentes parties du présent document constituent un autre exemple d'utilisation du Markdown.

Visualiseur

Un visualiseur en mode web permet de visualiser les documents et de naviguer entre eux. Il permet de vérifier qu'un document est conforme à son schéma. Il offre aussi une fonctionnalité limitée de modification.
Un mode de visualisation par défaut est défini mais le visualisateur peut être étendu pour s'adapter aux différentes structures de document. Par exemples:

• l'extension YamlData permet de visualiser le contenu d'une base de données,
• l'extension YamlSkos permet de naviguer facilement au sein d'un thésaurus Skos,
• l'extension DataModel permet de naviguer facilement au sein d'un modèle de données.

Le visualisateur de l'espace public est accessible sous http://georef.eu/yamldoc/?doc=index.
Son code source est disponible sur: Github.

Ypath: mécanisme de requêtes simples

La fourniture d'une chaine de caractères particulière (appelée Ypath), permet de sélectionner une partie d'un document ou d'une base de données. Son utilisation est illustrée par les exemples ci-dessous :

• dans le présent document, la sélection de la partie yaml du document s'effectue en entrant dans le champ de saisie en dessous du menu la chaine /yaml,
• il est aussi possible d'afficher ce même champ en suivant l'url ?doc=yamldoc&ypath=/yaml,
• dans un thésaurus comme le lexique topographique, on peut référencer le micro-thésaurus lexiquecadastre par la chaine /schemes/lexiquecadastre ou le terme matrice_cadastrale par la chaine /concepts/matrice_cadastrale,
• dans la table des départements :
  • la sélection de l'enregistrement ayant pour name Guadeloupe s'effectue par la chaine /data/name=Guadeloupe
  • la sélection des enregistrements ayant pour insee_code 04 s'effectue par la chaine /data/insee_code=04
  • la projection sur les champs insee_code, name et successors s'effectue par la chaine /data/insee_code,name,successors

Identification des documents et de leurs fragments et leur exposition en JSON

Chaque document correspond à un URI de la forme http://id.georef.eu/{path} où {path} est le chemin du document.
Le déréférencement de cet URI expose le document en JSON.

De même chaque fragment d'un document correspond à un URI de la forme http://id.georef.eu/{path}{ypath}, où {ypath} est le chemin du fragment dans le document, qui peut être déréférencé pour exposer le fragment en JSON.

Exemples:

• Le présent document : http://id.georef.eu/yamldoc
• Le présent fragment : http://id.georef.eu/yamldoc/id
• Codification des langues selon la norme ISO 639 : http://id.georef.eu/iso639
• Définition du code fre selon la norme ISO 639 : http://id.georef.eu/iso639/concepts/fre

Recherche plein texte

En tapant un mot ou plusieurs dans le champ de saisie, une recherche plein texte est effectuée dans les documents. Si la chaine ne commence pas par un '/' la chaine est interprétée comme une liste de mots.
Par exemple, en tapant le mot bourgogne on trouve les fragments d'EuroVoc et de geohisto qui contiennent ce mot.
On notera que l'indexation est effectuée par fragment, c'est à dire chaine ou texte à l'intérieur du document, et non document par document. C'est un point important par exemple pour indexer des bases de données.
Ainsi, par exemple, lors de la recherche du mot bourgogne, un des résultats est le fragment d'Eurovoc correspondant au ypath /concepts/5032/historyNote/fr/0 ; il s'agit donc de la première note historique en français associée au concept 5032. Il est simple de remonter ici au concept en modifiant le ypath.

Différentes possibilités de recherche sont proposées :

• en indiquant plusieurs mots on cherche les fragments contenant au moins un des mots, par exemple la chaine Franche Comté permet de trouver les fragments contenant soit Franche soit Comté,
• en faisant précéder les mots par un + on cherche les fragments contenant tous les mots, par exemple la chaine +Franche +Comté permet de trouver les fragments contenant à la fois Franche et Comté,
• en faisant précéder un mot par un - on exclue les fragments contenant ce mot, par exemple la chaine +Franche -Comté permet de trouver les fragments contenant Franche mais pas Comté,
• en faisant suivre un mot par * on cherche les mots commencant par le mot, par exemple la chaine geograph* permet de trouver géographie et geography.

Il est aussi possible de restreindre la recherche à un document, voire à certains fragments, par exemple on peut rechercher le mot géographie uniquement dans les concepts d'Eurovoc en indiquant dans le champ key eurovoc/concepts.

Organisation d'espaces documentaires partagés chacun sous la forme d'une archive Git

Les documents sont partitionnés en différents espaces documentaires avec pour chacun des accès en lecture et/ou en écriture pour certains utilisateurs.
Chaque espace documentaire correspond à une archive Git qui peut ainsi être partagée. Outre l'utilisation en mode web, les différents utilisateurs d'un espace peuvent ainsi modifier les documents sur leur poste local au moyen d'un éditeur de texte. Le logiciel Git est utilisé pour assurer la synchronisation entre les différentes copies.

Dans un premier temps, seuls 2 espaces sont définis: un espace public et un espace privé.
L'archive Git de l'espace public est accessible à l'URL: https://github.com/benoitdavidfr/yamldocs et le visualisateur de cet espace est accessible sous http://georef.eu/yamldoc/?doc=index.

L'utilisation du mécanisme des branches de git permet d'isoler les modifications de différents utilisateurs ; cette fonctionnalité potentielle n'a pas encore été mise en oeuvre.

Requêtes en Php

Les documents correspondant à des bases de données peuvent facilement être exploités par des scripts Php qui effectuent des requêtes dans les données. Ces requêtes sont appelées comme des documents.
Par exemples :

• le document jregdept réalise une jointure entre les régions actuelles et les départements actuels et renvoie la liste des régions actuelles avec pour chacune la liste de ses départements (consulter le code source Php de la requête),
• il est possible de sélectionner une partie du document jregdept en indiquant un ypath, ainsi ypath=/data/insee_code=32/depts sélectionne la liste des départements de la région ayant 32 comme insee_code.
• autre exemple, le document cregions sélectionne les régions actuelles (consulter le code source Php de la requête).

Du point de vue implémentation, un document requête est un script Php qui renvoie un array Php à partir duquel sera créé un objet Yamldoc par exemple pour afficher le résultat de la requête.

Réflexions pour la suite

Reconstruire YamlDoc fondé sur les mécanismes suivants :

• un document contient, outre ses métadonnées, un ensemble de ressources liées (RDF) dans l'hypothèse du monde ouvert.
  Chaque ressource est identifiée par un URI et exposée en JSON-LD.
  Aujourd'hui 3 prototypes :

  • les thésaurus Skos comme EuroVoc fondés sur la classe YamlSkos
  • le catalogue des données fondé sur la classe YamlRdf
  • le registre des organisations fondé sur la classe AutoDescribed

  Ces 3 prototypes sont assez différents:

  • le registre des organisations comporte un schéma qui permet de vérifier le contenu du document alors que le catalogue des données n'en contient pas

• un document contient un dictionnaire de collections homogènes d'enregistrements, chaque enregistrement étant censé respecter le schéma JSON défini au niveau de la collection.
  C'est la logique des bases de données et donc hypothèse du monde clos.
  Chaque enregistrement est identifié par un URI et est exposé en JSON (pourquoi pas en JSON-LD ?).

• accès aux API en mode RESTfull

Peut-on gérer simplement la structure Skos comme un cas particulier de Rdf ?

L'exemple du registre des organisations avec la classe AutoDescribed montre:

• l'intérêt d'utiliser conjointement:
  • le schema JSON pour vérifier la syntaxe des données saisies
  • JSON-LD pour exposer de manière standardisée et formalisée la sémantique des données
• pour YamlDoc que les 2 mécanismes ne s'opposent pas

JSON-LD vs. JSON Schema

In https://lists.w3.org/Archives/Public/public-linked-json/2014Oct/0010.html
markus.lanthaler@gmx.net wrote:

They serve different purposes. The short version is:

• JSON-LD give JSON messages a well-defined meaning by mapping most things to IRIs.
• JSON Schema describes the syntactic structure of a JSON document.

Both work with JSON so you can use them together.

Réflexions pour la gestion de données liées

Un document RDF assez générique derait être décrit par:

• un schéma JSON pour contrôler la saisie des données et documenter la structure de données
• un champ permettant la simplification de la traversée hiérarchique des objets, permettant ainsi la définition d'URI simples
  • exemple: http://id.georef.eu/organizations/fr.ign/DP/SPRI/DGT
• un champ explicitant le formattage JSON-LD du retour d'une URI

Exemples:

• http://id.georef.eu/organizations
• http://bdavid.alwaysdata.net/yamldoc/id.php/contacts
• http://id-benoit.georef.eu/contacts

Test dans http://id.georef.eu/organizations d'utilisation de l'URI schema.org dans un schema JSON

Voir l'utilisation de ce principe dans:

• http://id.georef.eu/cdmet
• http://id.georef.eu/eurovoc