title |
Présentation résumée de YamlDoc
|
modified |
2020-02-18 00:00:00 |
abstract |
YamlDoc
YamlDoc est un système de gestion documentaire fondé sur :
- l'organisation de documents correspondants principalement à des fichiers texte
structurés au format Yaml,
- 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,
- 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,
- la possibilité de formatter les textes contenus dans un champ du fichier Yaml
en utilisant le langage Markdown,
- la visualisation des documents et fragments au moyen d'un visualiseur Web
extensible grâce aux classes de documents,
- un mécanisme de requête simple (ypath) dans les documents,
- 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,
- la possibilité d'effectuer des recherches plein texte dans les documents,
- 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,
- la définition de requêtes sur les documents en Php,
YamlDoc est notamment étendu pour permettre :
Idées pour la suite.
|
yaml |
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.
|
semantic |
Sémantique bien connue
Lorsque cela est adapté, la sémantique des champs des tableaux associatifs Yaml respecte les standards suivants :
|
ydclass |
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 |
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.
|
viewer |
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 |
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 :
|
id |
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:
|
textSearch |
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 .
|
git |
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.
|
query |
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 :
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.
|
next |
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 :
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.
|
ld |
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
|