Commit dd55b5cf authored by Bertille Dubosc de Pesquidoux's avatar Bertille Dubosc de Pesquidoux
Browse files

Relecture de toute la documentation

parent 1ff91d3e
# Tx - C.H.A.T.O.N.S.
Ce projet vise à définir un modèle permettant aux différents CHATONS de décrire ce qu'ils sont et ce qu'ils font, afin de :
Ce projet vise à définir un modèle permettant aux différents Chatons de décrire ce qu'ils sont et ce qu'ils font, afin de :
- Faciliter la maintenance de ces informations,
- Proposer une approche décentralisée de cette description,
- Permettre à un outil de recherche de compiler ces informations et proposer à un⋅e utilisateurice des résultats pertinents et à jour.
Ce projet de Tx n'a pas vocation à imposer un format aux CHATONS, simplement à proposer une des multiples approches. Ainsi, ce format est amené à évoluer, et à se faire approprier ou pas par les CHATONS.
Ce projet de Tx n'a pas vocation à imposer un format au CHATONS, simplement à proposer une des multiples approches possibles. Ainsi, ce format est amené à évoluer, et à se faire approprier ou pas par les Chatons.
Les derniers résultats du projet sont sur le site [chatons.picasoft.net](http://chatons.picasoft.net). Nous y avons aussi expliqué la démarche plus en détail.
## Le schéma
L'approche du JSON validé par un schéma aura été choisie. Chaque CHATONS propose un fichier JSON, valide selon le schéma présenté, qui contient les principales informations telles que :
L'approche du JSON validé par un schéma a été choisie. Chaque Chaton propose un fichier JSON, valide selon le schéma présenté, qui contient les principales informations telles que :
- `url` : le site du CHATONS,
- `name` : le nom
- `servers` : la liste des hébergeurs,
......@@ -24,13 +24,13 @@ L'approche du JSON validé par un schéma aura été choisie. Chaque CHATONS pro
## Le crawler
Le but du crawler est de télécharger tous les fichiers JSON répertoriés et de les exporter en un format pertinent pour une utilisation ultérieure. Il reste encore à définir précisément quel est ce format.
Le but du crawler est de télécharger tous les fichiers JSON répertoriés et de les exporter en un format pertinent pour une utilisation ultérieure, tel qu'un [plus gros JSON qui centralise les informations](http://chatons.picasoft.net/exports/chatons.json) ou la [liste des services au format entraide](http://chatons.picasoft.net/exports/chatons-services.json).
## La liste des URL à vérifier
Le crawler prend en entrée une liste d'URL à télécharger. Les merge request sont les bienvenues sur cette liste pour intégrer de nouveaux CHATONS à l'outil de centralisation.
## Le convertisseur
Une fois les données agrégées, le convertisseur permet de les transformer en un autre format, par exemple celui de https://entraide.chatons.org ou celui d'une organisation selon schema.org (en construction).
Une fois les données agrégées, le convertisseur permet de les transformer en un autre format, par exemple celui de https://entraide.chatons.org ou celui d'une [organisation selon schema.org](https://schema.org/Organization) (en construction).
## Le site
Un site a été mis en place pour présenter la démarche et mettre à disposition les résultats de la collecte. Ses sources sont aussi sur ce dépôt.
......@@ -23,5 +23,6 @@ Pour comparer deux Chatons (pour savoir qui a été ajouté, mis à jour, suppri
Nous recommandons de le lancer ainsi :
```
./crawler.py -u -v -o sortie/chatons.json -s ../schema/CHATONS_schema.json -i ../liste/CHATONS_list.txt
./crawler.py -u -v -o ../sortie/chatons.json -s ../schema/CHATONS_schema.json -i ../liste/CHATONS_list.txt
```
(ce qui revient à lancer run_crawler.sh)
Qui sommes-nous ?
=================
Nous sommes deux étudiant·es de l'Université de Technologie de Compiègne. Notre
école propose à ses élèves de réaliser des études expérimentales, ou TX. Ce sont
des projets en semi-autonomie portant sur des sujets « réels » et pas
seulement pédagogiques. C'est dans ce cadre-là que nous avons conçu cet outil.
Nous sommes deux étudiant·es de l'Université de Technologie de Compiègne. Notre école propose à ses élèves de réaliser des études expérimentales, ou TX. Ce sont des projets en semi-autonomie portant sur des sujets « réels » et pas seulement pédagogiques. C'est dans ce cadre-là que nous avons conçu cet outil.
Remerciements
=============
Merci à Stéphane Crozat, Rémi Uro et Quentin Duchemin d'avoir encadré ce projet.
Merci à Angie et à pyg d'avoir répondu à nos questions et de nous avoir aidés
à comprendre l'écosystème du CHATONS.
Merci à Angie et à pyg d'avoir répondu à nos questions et de nous avoir aidés à comprendre l'écosystème du CHATONS.
Merci à TTDM, ljf, djayroma, unteem, numahell, Neil, Kyâne, Meewan, pierre, bouviermullerp, mrflos, cpm et deblan pour leurs
coups de main, retours et suggestions.
Merci à TTDM, ljf, djayroma, unteem, numahell, Neil, Kyâne, Meewan, pierre, bouviermullerp, mrflos, cpm et deblan pour leurs coups de main, retours et suggestions.
......@@ -4,41 +4,26 @@ Construire la liste des Chatons
Le principe du crawler et l'intérêt de cette liste
---------------------------------------------------
Le crawler est un outil permettant de récupérer des fichiers JSON
décrivant les Chatons. Un fichier central liste les urls des JSON, et
les fichiers pointés sont aglomérés dans un unique fichier JSON.
Le crawler est un outil qui permet de récupérer des fichiers JSON décrivant les Chatons. Un fichier central liste les urls des JSON à intégrer, et les fichiers pointés sont agglomérés dans un unique fichier JSON.
Le modèle de description de chaque Chaton est un fichier JSON hébergé
sur son site web, valide selon un format propre au collectif. Ce modèle
a été jugé optimal car il permet à chaque Chaton de décrire exactement
son identité et ses services. Cette décentralisation des description est
une solution courante, utilisée notamment par la FFDN et les
LibreHosters.
Le modèle de description de chaque Chaton est un fichier JSON hébergé sur son site web, valide selon un format propre au collectif. Ce modèle a été jugé intéressant car il permet à chaque Chaton de décrire exactement son identité et ses services tout en assurant une intercompatibilité des descriptions.
Cette décentralisation des description est une solution courante, utilisée notamment par la FFDN et les LibreHosters.
Le choix d'héberger ce fichier sur un dépôt git
------------------------------------------------
Le choix d'utiliser un fichier central nous paraît être la meilleure
solution pour cette TX :
Le choix d'utiliser un fichier central pour lister les fiches nous paraît être la meilleure solution pour cette TX :
- Une structure centrale existe déjà (sur le [Framagit du
CHATONS](https://framagit.org/framasoft/CHATONS)) pour des documents
comme la charte ou l'identité graphique du CHATONS, cela ne
demande donc pas d'adaptation technique
CHATONS](https://framagit.org/framasoft/CHATONS)) pour des documents comme la charte ou l'identité graphique du CHATONS, cela ne demande donc pas d'adaptation technique
- Elle est facile à mettre en place :
- Pour sa lecture pour le crawler
- Pour les Chatons qui modifient ce fichier en ajoutant une ligne
à chaque Chaton qui arrive
- Elle correspond bien à une échelle moyenne d'information, ici moins
d'une centaine de Chatons pour des fichiers légers
- Une solution décentralisée paraît trop compliquée, et pour la PoC de
cette TX, et de manière générale car c'est une problématique
dépassant l'outil de recherche, mais suscitant une refonte plus
générale de l'organisation même du CHATONS
Ces informations sont alors agglomérées dans un unique fichier JSON, et
non pas une base de donnée plus classique, pour des raisons discutées
[ci-après](export.md).
- Pour les Chatons qui modifient ce fichier en ajoutant une ligne à chaque Chaton qui arrive
- Elle correspond bien à une échelle moyenne d'information, ici moins d'une centaine de Chatons pour des fichiers légers
- Une solution décentralisée paraît trop compliquée, et pour la preuve de concept de cette TX, et de manière générale car c'est une problématique dépassant l'outil de recherche, mais suscitant une refonte plus générale de l'organisation même du CHATONS
Ces informations sont alors agglomérées dans un unique fichier JSON, et non pas une base de donnée plus classique, pour des raisons discutées [ci-après](export.md).
[Dernière version de la liste des URL](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/liste/CHATONS_list.txt)
--------------------------------------
Ajouter son Chaton
==================
Si le projet vous intéresse ou vous préférez renseigner ainsi les
informations de votre Chaton, voici la marche à suivre.
Si le projet vous intéresse ou que vous préférez renseigner les informations de votre Chaton ainsi plutôt que sur le site central, voici la marche à suivre.
Créer le fichier JSON
---------------------
Tout d'abord, il faut renseigner les informations de votre structure.
Pour ce faire, vous pouvez consulter [la liste de tous les champs possibles, des valeurs qu'ils peuvent
prendre et de leur sens](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/README.md).
Pour ce faire, vous pouvez consulter [la liste de tous les champs possibles, des valeurs qu'ils peuvent prendre et de leur sens](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/README.md).
Vous pouvez aussi utiliser [un formulaire qui se génère avec le schéma](http://chatons.picasoft.net/gen/json_gen.html).
Vérifier que le fichier respecte bien la convention adoptée
-----------------------------------------------------------
Pour que le fichier puisse être utilisé, il faut qu'il respecte le
[schéma](http://chatons.picasoft.net/schema/schema.json). Vous pouvez vérifier que c'est bien le cas
avec un [outil de validation en
ligne](https://www.jsonschemavalidator.net/) par exemple.
Pour que le fichier puisse être utilisé, il faut qu'il respecte le [schéma](http://chatons.picasoft.net/schema/schema.json). Vous pouvez vérifier que c'est bien le cas avec un [outil de validation en ligne](https://www.jsonschemavalidator.net/) par exemple.
Mettre le JSON en ligne
-----------------------
Assurez-vous que l'on peut avoir accès au fichier sur votre site. Vous
pouvez par exemple le déposer à la racine, avec chaton.json en nom.
Assurez-vous que l'on peut avoir accès au fichier sur votre site. Vous pouvez par exemple le déposer à la racine, avec chaton.json en nom.
Ajouter l'adresse du fichier à la liste
----------------------------------------
Vous pouvez maintenant demander à mettre à jour la liste des fichiers à
surveiller. Pour ce faire, allez sur [la
liste](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/liste/CHATONS_list.txt).
Vous pouvez maintenant demander à mettre à jour la liste des fichiers à surveiller. Pour ce faire, allez sur [la liste](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/liste/CHATONS_list.txt).
Vous devriez voir un bouton bleu sur lequel il est écrit « Edit ».
Cliquez dessus. GitLab vous prévient alors que vous n'avez pas les
droits d'édition et vous propose de faire un fork.
Vous devriez voir un bouton bleu sur lequel il est écrit « Edit ». Cliquez dessus. GitLab vous prévient alors que vous n'avez pas les droits d'édition et vous propose de faire un fork.
![Bandeau d'outils pour l'édition dans
GitLab](images/edit_banner.png)
![Bandeau d'outils pour l'édition dans GitLab](images/edit_banner.png)
Après un petit temps de chargement, un éditeur en ligne s'ouvre. Vous
pouvez alors ajouter en bas de la liste les deux lignes suivantes :
Après un petit temps de chargement, un éditeur en ligne s'ouvre. Vous pouvez alors ajouter en bas de la liste les deux lignes suivantes :
```
# [Nom de votre CHATON]
[URL du fichier]
```
Quand vous avez fini, cliquez sur le bouton bleu « Commit... » en
bas à gauche. Vérifiez que la case « Start a new merge request » est
bien cochée et validez en cliquant à nouveau sur le bouton, qui est
devenu vert.
Quand vous avez fini, cliquez sur le bouton bleu « Commit... » en bas à gauche. Vérifiez que la case « Start a new merge request » est bien cochée et validez en cliquant à nouveau sur le bouton, qui est devenu vert.
La page qui s'ouvre est l'interface pour saisir une demande
d'intégration de vos modifications dans le projet principal. Donnez-lui
un titre explicite, comme par exemple « Ajout du Chaton X » et
cliquez sur« Submit merge request »
La page qui s'ouvre est l'interface pour saisir une demande d'intégration de vos modifications dans le projet principal. Donnez-lui un titre explicite, comme par exemple « Ajout du Chaton X » et cliquez sur « Submit merge request »
C'est fini !
-------------
......@@ -69,19 +52,13 @@ Proposer une modification du schéma
Ajouter un champ
----------------
Vous trouvez qu'il manque une information importante dans le schéma ?
Vous pouvez proposer son ajout.
Vous trouvez qu'il manque une information importante dans le schéma ? Vous pouvez proposer son ajout.
Ouvrez tout d'abord le
[schéma](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema.json).
Ouvrez tout d'abord le [schéma](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json).
Réfléchissez au type de champ que vous voulez ajouter et à son
emplacement dans la hiérarchie.
Réfléchissez au type de champ que vous voulez ajouter et à son emplacement dans la hiérarchie.
Chaque champ est défini par une description, un type et des contraintes
éventuelles. [Ce tutoriel](https://json-schema.org/understanding-json-schema/index.html)
explique comment définir un champ. Par exemple, pour du
texte libre, on définit le champ ainsi :
Chaque champ est défini par une description, un type et des contraintes éventuelles. [Ce tutoriel](https://json-schema.org/understanding-json-schema/index.html) explique comment définir un champ. Par exemple, pour du texte libre, on définit le champ ainsi :
```
"nouveau_champ": {
......@@ -90,22 +67,15 @@ texte libre, on définit le champ ainsi :
}
```
Insérez la définition de ce nouveau champ au bon endroit. Pour une
information générale sur un Chaton, c'est sans doute dans l'objet
`"properties"`.
Insérez la définition de ce nouveau champ au bon endroit. Pour une information générale sur un Chaton, c'est sans doute dans l'objet `"properties"`.
Pensez à modifier aussi le
[README](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/README.md)
du schéma, pour documenter votre ajout.
Pensez à modifier aussi le [README](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/README.md) du schéma, pour documenter votre ajout.
De la même manière que pour ajouter un Chaton, faites une merge request
pour proposer vos modifications.
De la même manière que pour ajouter un Chaton, faites une merge request pour proposer vos modifications.
Ajouter un service ou un logiciel dans la liste des possibilités
----------------------------------------------------------------
Il suffit d'ajouter la valeur souhaitée dans le `enum` de la définition
de software ou de service\_type, vers la fin du schéma.
Il suffit d'ajouter la valeur souhaitée dans le `enum` de la définition de `software` ou de `service_type`, vers la fin du schéma.
C'est la même procédure pour ajouter une valeur possible à n'importe
laquelle des listes.
C'est la même procédure pour ajouter une valeur possible à n'importe laquelle des listes.
# Le convertisseur
# Le convertisseur vers entraide
## Principe
......@@ -15,9 +15,12 @@ converter.py [-o OUTPUT] <input>
Avec `<input>` le [fichier json](http://chatons.picasoft.net/exports/chatons.json) exporté par le [crawler](http://chatons.picasoft.net/documentation/crawler/), et output un fichier dans lequel écrire l'export (par défaut `<input>_converted.json`)
## Fonctionnement
(Le fonctionnement détaillé est donné sur le [framagit](https://framagit.org/bertille/tx-collecte-chatons/-/tree/master/conversion#fonctionnement).)
(Le fonctionnement détaillé est donné sur le [Framagit](https://framagit.org/bertille/tx-collecte-chatons/-/tree/master/conversion#fonctionnement).)
La conversion se fait en trois étapes :
- Renommage des clés et des valeurs,
- Renommage des clés et des valeurs (voir [pourquoi les clefs et les valeurs doivent être converties](formatage_donnees.md)),
- Explosion des Chatons par service,
- Transformation de la structure vers du Node.
## Fonctionnalité de l'export
Nous avons pu tester que l'export ainsi obtenu fonctionnait bien en faisant tourner [le site d'entraide](https://framagit.org/chatons/entraide). Cependant, le site donne des erreurs s'il n'y a aucun fournisseur pour certains services. Nous avons donc dû ajouter à la [liste](centralisation.md) un Chaton factice, dont les données servent seulement de démonstration pour l'export entraide.
# Le crawler
## Fonctionnement
Le crawler est un outil permettant de centraliser des données json contenues dans des fichiers hébergés en ligne représentant chacun un Chaton, explicitant ses activités et ses services, afin de générer un gros fichier json qui sera à son tour exploité pour les recherches.
Le [fichier central](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/liste/CHATONS_list.txt) stocké sur le framagit contient une liste d'url. Le crawler essaie pour chaque url d'extraire le contenu et vérifie s'il s'agit bien d'un fichier json, que ce json est éventuellement valide selon un [schéma](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema.json), que le Chaton décrit n'est pas déjà dans la liste, et une fois tous les critères de validité remplis, l'url est ajouté à une liste. Si l'option de mise à jour seulement est passé au crawler, celui-ci va rajouter les Chatons supprimés entre deux générations pour ne pas perdre d'information.
Enfin, un fichier [json final](http://chatons.picasoft.net/exports/chatons.json) est produit, le rendant utilisable pour [l'outil de recherche](http://chatons.picasoft.net/search/recherche.html). Tout le déroulement du processus est consigné dans un fichier de [log](http://chatons.picasoft.net/logs/log.txt).
Le crawler est un outil permettant de centraliser des données JSON contenues dans des fichiers hébergés en ligne représentant chacun un Chaton. Chaque fichier explicite les activités et les services du Chaton, qui pourront être rassemblés dans un gros fichier JSON qui sera à son tour exploité pour les recherches.
Le [fichier central](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/liste/CHATONS_list.txt) stocké sur le Framagit contient une liste d'URL. Le crawler essaie pour chaque URL d'extraire le contenu et vérifie s'il s'agit bien d'un fichier JSON, que ce JSON est éventuellement valide selon un [schéma](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json) et que le Chaton décrit n'est pas déjà dans la liste. Une fois tous les critères de validité remplis, l'URL est ajouté à une liste. Si l'option de mise à jour seulement est passée au crawler, celui-ci va rajouter les Chatons supprimés entre deux générations pour ne pas perdre d'information.
Enfin, un fichier [JSON final](http://chatons.picasoft.net/exports/chatons.json) est produit, le rendant utilisable pour [l'outil de recherche](http://chatons.picasoft.net/search/recherche.html). Tout le déroulement du processus est consigné dans un fichier de [log](http://chatons.picasoft.net/logs/log.txt).
## Utilisation
(Une documentation plus complète est disponible sur le [Framagit](https://framagit.org/bertille/tx-collecte-chatons/-/tree/master/crawler))
......@@ -12,8 +14,8 @@ Le crawler s'appelle en ligne de commande en précisant le fichier d'entrée, ce
```
crawler.py [-h] [-u] [-v] [-o OUTPUT] [-s SCHEMA] -i INPUT
```
- `-i, --input INPUT` : Liste d'urls pointant vers les jsons des Chatons
- `-o, --output OUTPUT` : Fichier json dans lequel sont exportés toutes les informations récoltées.
- `-i, --input INPUT` : Liste d'URL pointant vers les JSON des Chatons
- `-o, --output OUTPUT` : Fichier JSON dans lequel sont exportées toutes les informations récoltées.
- `-s, --schema SCHEMA` : Fichier optionnel, si donné les jsons des Chatons doivent être valides pour être ajoutés à `OUTPUT`
- `-v, --verbose` : Affiche plus d'informations dans la console
- `-u, --update-only` : Mode « mise à jour seulement », permet de garder les Chatons qui seraient supprimés entre deux exécutions successives (par exemple si un Chaton a un problème avec son json pendant la procédure de mise à jour).
Différentes solutions possibles pour interroger les données collectées
======================================================================
[Ce site propose de manière statique de télécharger le JSON de tous les
Chatons](http://chatons.picasoft.net/exports/chatons.json).
[Ce site propose de manière statique de télécharger le JSON de tous les Chatons](http://chatons.picasoft.net/exports/chatons.json).
Il est également possible d'interroger ce fichier
pour trouver un Chaton ou un service spécifique, par exemple, et de
demander des exports particuliers. Pour ce faire, plusieurs possibilités
se présentaient, et notamment plusieurs choix d'architecture.
[Il est également possible d'interroger ce fichier pour trouver un Chaton ou un service spécifique](http://chatons.picasoft.net/search/recherche.html), par exemple, et de télécharger des exports particuliers, comme [celui vers le format entraide](http://chatons.picasoft.net/exports/chatons-services.json). Pour ce faire, plusieurs possibilités se présentaient, et notamment plusieurs choix d'architecture.
Une architecture avec serveur applicatif seulement
--------------------------------------------------
C'est la solution que nous avons choisie.
Nous avons développé [un outil de recherche](http://chatons.picasoft.net/search/recherche.html)
qui charge le JSON dans le navigateur de l'utilisateur·ice et lui permet
d'effectuer une recherche. Pour l'instant, il n'est possible de chercher un
Chaton que sur la base de sa structure, des services qu'il propose, de son
modèle économique et du public auquel il s'adresse.
Nous avons développé [un outil de recherche](http://chatons.picasoft.net/search/recherche.html) qui charge le JSON dans le navigateur de l'utilisateur·ice et lui permet d'effectuer une recherche. Pour l'instant, il n'est possible de chercher un Chaton que sur la base de sa structure, des services qu'il propose, de son modèle économique et du public auquel il s'adresse.
Une architecture serveur applicatif et serveur de données
---------------------------------------------------------
Une architecture avec serveur applicatif et serveur de données
--------------------------------------------------------------
Ici, il s'agit de créer une base de données, d'entrer les informations
dedans et de développer une application qui interroge cette base de
données.
Ici, il s'agit de créer une base de données, d'entrer les informations dedans et de développer une application qui interroge cette base de données.
Nous n'avons pas retenu cette solution parce qu'elle ajoute une couche
de complexité au projet alors que les avantages des bases de données
(notamment la performance avec des gros volumes de données) ne sont pas
utiles ici.
Nous n'avons pas retenu cette solution parce qu'elle ajoute une couche de complexité au projet alors que les avantages des bases de données (notamment la performance avec des gros volumes de données) ne sont pas utiles ici.
Nous avions considéré comme candidats les SGBD suivants :
......@@ -38,52 +25,28 @@ Nous avions considéré comme candidats les SGBD suivants :
Avantages
- C'est un SGDB orienté document, il prend des JSON en entrée. Il
n'y a donc pas besoin de traiter plus avant les fichiers collectés,
on peut directement les importer dans la BDD. Il y a juste à écrire
des procédures de mise à jour qui préservent la cohérence de
l'information.
- C'est un SGDB orienté document, il prend des JSON en entrée. Il n'y a donc pas besoin de traiter plus avant les fichiers collectés, on peut directement les importer dans la BDD. Il y a juste à écrire des procédures de mise à jour qui préservent la cohérence de l'information.
Inconvénients
- C'est un système assez lourd et gourmand, il n'y a sans doute pas
besoin de cet outil pour un usage aussi léger.
- Il n'est pas utilisé dans l'écosystème technique actuel du
collectif des CHATONS, c'est donc un investissement en temps et
compétences qui n'est pas négligeable.
- C'est un système assez lourd et gourmand, il n'y a sans doute pas besoin de cet outil pour un usage aussi léger.
- Il n'est pas utilisé dans l'écosystème technique actuel du CHATONS, c'est donc un investissement en temps et en compétences qui n'est pas négligeable.
### PostgreSQL
Avantages
- Le site actuel du CHATONS utilise une BDD PostgreSQL, cela ne
duplique pas l'infrastructure technique.
- Le site actuel du CHATONS utilise une BDD PostgreSQL, cela ne duplique pas l'infrastructure technique.
Inconvénients
- C'est une BDD relationnelle. Les colonnes peuvent facilement avoir
un type JSON mais il sera sans doute préférable de travailler un peu
l'export pour en faire quelque chose de plus dans la philosophie
des tables.
- C'est une BDD relationnelle. Les colonnes peuvent facilement avoir un type JSON mais il sera sans doute préférable de travailler un peu l'export pour en faire quelque chose de plus dans la philosophie des tables.
Question de l'intégration technique et fonctionnelle au site du CHATONS
=========================================================================
Pour une preuve de concept, ce site en stand-alone suffit. Cela étant,
le but à terme est d'utiliser ce mode de récolte des données pour
nourrir le site actuel du CHATONS. L'information devrait être
regroupée et pas dupliquée, et certains membres du collectif préféreront
toujours remplir le formulaire pour créer leur fiche.
Le site [entraide.chatons.org](https://entraide.chatons.org) prend en
entrée un fichier JSON assez simple avec les informations des différents
services. Il sera possible de générer un fichier qui respecte le bon
format et de le fusionner avec celui généré par le formulaire du site
chatons.org.
Pour les fiches des Chatons, c'est plus compliqué. Certains champs ne
sont pour l'instant pas intégrés dans notre schéma et seraient lourds à
inclure (le respect de la charte point par point par exemple). Il faudra
donc trouver à la fois des solutions pour faire l'interface entre les
clefs et les valeurs des deux modèles, et pour importer les données dans
le Drupal de chatons.org.
Pour une preuve de concept, ce site en stand-alone suffit. Cela étant, le but à terme est d'utiliser ce mode de récolte des données pour nourrir le site actuel du CHATONS. L'information devrait être regroupée et pas dupliquée, et certains membres du collectif préféreront toujours remplir le formulaire pour créer leur fiche.
Le site [entraide.chatons.org](https://entraide.chatons.org) prend en entrée un fichier JSON assez simple avec les informations des différents services. Nous générons donc [un fichier qui respecte le bon format](http://chatons.picasoft.net/exports/chatons-services.json) et qui pourrait être fusionné avec celui généré par le formulaire du site chatons.org. [Voici comment nous générons cet export](convertisseur.md).
Pour les fiches des Chatons, c'est plus compliqué. Certains champs ne sont pour l'instant pas intégrés dans notre schéma et seraient lourds à inclure (le respect de la charte point par point par exemple). Il faudra donc trouver à la fois des solutions pour faire l'interface entre les clefs et les valeurs des deux modèles, et pour importer les données dans le Drupal de chatons.org.
# Réflexions sur le formatage idéal des données dans un modèle JSON
Sur cette page, nous tenterons de répondre à la question :
Quelles conventions adopter pour les clés et pour les valeurs du [schéma](schema.md) ?
## Les clés
La question ne se pose pas vraiment pour les clés. On a deux options :
* Soit on met les clefs français, et le document est fait uniquement pour un public francophone. On perd la possibilité de [transformer les fiches en JSON-LD](jsonld).
* Soit on met les clés en anglais, respectant ainsi des standards implicites et explicites, permettant aisément de LD-ifier le tout.
Sur ce sujet, la réponse est vite tranchée en faveur de clés en anglais.
## Les valeurs
La question est de nature plus polémique. Il existe trois options principales :
### Tout en anglais
Les valeurs des champs sont des étiquettes en langue anglaise référençant un concept.
```
"public": {
"description": "The public to whomst the Chaton is aimed at",
"type": "string",
"enum": ["all", "members", "customers", "private_circle"]
}
```
Avantages :
* Format très générique et adaptable aisément
* Explicite le fait uqe ce sont des étiquettes, pas des valeurs, et qu'il faut les recopier scrupuleusement
Inconvénients :
* Nécessité de refaire tout le schéma
* Nécessite des fichiers de dictionnaire et une fonction convertissant une valeur (`all`) en du français lisible (« Tou⋅te⋅s ») sur le site web
* Nécessité de maîtriser une plus grande quantité de concepts dans une autre langue pour les personnes chargées de maintenir le code
* Éventuellement moins compatible avec la volonté politique francophone des Chatons
### Un système d'étiquettes en français
Les valeurs des champs sont des étiquettes en langue française référençant un concept.
```
"public": {
"description": "La liste des publics auxquels s'adresse un Chaton ou un service",
"type": "string",
"enum": ["tou.te.s", "adherent.e.s", "client.e.s", "cercle_prive"]
}
```
Avantages :
* Le système de description fonctionne actuellement sur ce principe, et cela suffit pour une preuve de concept
* Les étiquettes sont explicites et ne contiennent que des caractères « simples » pour être parsées
* Il suffit de quelques magouilles (peu orthodoxes) pour passer d'une étiquette à un groupe nominal pour l'affichage sur le site web
Inconvénients :
* Le mélange sémantique entre étiquette et valeur est mal vu
* Difficile d'évoluer
* Le niveau de simplification des valeurs n'est pas évident
* Est désagréable à lire pour un humain sans être plus facilement manipulable par une machine
### Tout en français
Les valeurs des clés ne sont plus des étiquettes mais bien des valeurs qui seront utilisées telles quelles pour l'affichage, avec leur lot de caractères accentués, d'espaces et de points médians.
```
"public": {
"description": "La liste des publics auxquels s'adresse un Chaton ou un service",
"type": "string",
"enum": ["tou⋅te·s", "adhérent⋅e⋅s", "client⋅e⋅s", "cercle privé"]
}
```
Avantages :
* Pas besoin de fonction de conversion entre étiquette et valeur
* Termes explicites
* C'est le choix qui a été fait pour entraide.chatons.org, l'export en ce format peut donc se faire de manière transparente
Inconvénients :
* Espaces et caractères spéciaux à traiter
* Moins facile à copier à la main (erreurs, accessibilité des caractères spéciaux) par une personne écrivant son fichier json.\
Si le json est généré automatiquement, ce dernier point perd de son importance
* Nécessité de refaire tout le schéma
## Les descriptions
La description étant l'équivalent d'un commentaire dans du code, une explicitation du quoi, du pourquoi et du comment dans un schéma, il aura été convenu qu'elles soient en français véritable, et pas en une version ASCII-friendly bâtarde entre deux concepts.
......@@ -2,38 +2,20 @@ La démarche
===========
Le [site du CHATONS](https://chatons.org) permet notamment
de recenser les hébergeurs du réseau. Ceux-ci créent des fiches pour
donner des détails sur leur structure et les services numériques qu'ils
proposent.
de recenser les hébergeurs du réseau. Ceux-ci créent des fiches pour donner des détails sur leur structure et les services numériques qu'ils proposent.
Malheureusement, les Chatons ne pensent pas tous à tenir leur fiche à
jour. Nous proposons ici un nouveau système pour recueillir les
informations sur les Chatons. Il ne se subsitue pas à l'ancien mais
offre une nouvelle voie pour mettre les données en ligne, en espérant
que ces deux méthodes sauront se montrer complémentaires et augmenter la
fiabilité des informations du site du CHATONS.
Malheureusement, les Chatons ne pensent pas tous à tenir leur fiche à jour. Nous proposons ici un nouveau système pour recueillir les informations sur les Chatons. Il ne se subsitue pas à l'ancien mais offre une nouvelle voie pour mettre les données en ligne, en espérant que ces deux méthodes sauront se montrer complémentaires et augmenter la fiabilité des informations du site du CHATONS.
Le principe
===========
Il s'agit de donner les informations des Chatons de manière
décentralisée. Au lieu de remplir un formulaire sur le site du
collectif, chaque Chaton qui le souhaite peut créer un fichier JSON qui
décrit ses activités. Il dépose ensuite ce fichier JSON sur son site et
ajoute l'adresse du fichier à un répertoire commun.
Il s'agit de donner les informations des Chatons de manière décentralisée. Au lieu de remplir un formulaire sur le site du collectif, chaque Chaton qui le souhaite peut créer un fichier JSON qui décrit ses activités. Il dépose ensuite ce fichier JSON sur son site et ajoute l'adresse du fichier à un répertoire commun.
Lorsque les informations du Chaton changent, avec l'ouverture d'un
nouveau service par exemple, il suffit d'éditer ce fichier. Les
modifications seront prises en compte automatiquement, sans avoir besoin
d'aller se connecter à un autre site.
Lorsque les informations du Chaton changent, avec l'ouverture d'un nouveau service par exemple, il suffit d'éditer ce fichier. Les modifications seront prises en compte automatiquement, sans avoir besoin d'aller se connecter à un autre site.
En effet, chaque nuit, la liste des fichiers à vérifier est téléchargée,
et les différents JSON sont récupérés par un programme qui vérifie
s'ils sont conformes, les agrège et les publie ici (voir plus bas).
En effet, chaque nuit, la liste des fichiers à vérifier est téléchargée, et les différents JSON sont récupérés par un programme qui vérifie s'ils sont conformes, les agrège et les publie [sur ce site](http://chatons.picasoft.net/search/recherche.html).
D'autres collectifs, tels que la [FFDN](https://db.ffdn.org/) et
[LibreHosters](https://libreho.st/), utilisent un système décentralisé
similaire.
D'autres collectifs, tels que la [FFDN](https://db.ffdn.org/) et [LibreHosters](https://libreho.st/), utilisent un système décentralisé similaire.
- [Comment est gérée la liste des URL à
vérifier](centralisation.md) (et pourquoi un dépot
......@@ -53,14 +35,12 @@ Voici les liens vers les dernières données obtenues :
- [Chercher un Chaton](http://chatons.picasoft.net/search/recherche.html)
- [Télécharger le JSON de tous les Chatons](http://chatons.picasoft.net/exports/chatons.json)
- [Télécharger le JSON des services](http://chatons.picasoft.net/exports/chatons-services.json)
- [Les logs](http://chatons.picasoft.net/logs/log.txt) (pour vérifier si votre Chaton est bien
inclus dans l'export par exemple)
- [Les logs](http://chatons.picasoft.net/logs/log.txt) (pour vérifier si votre Chaton est bien inclus dans l'export par exemple)
Les ressources
===========
Pour contribuer ou simplement regarder comment ça marche, vous pouvez
consulter [notre dépôt git](https://framagit.org/bertille/tx-collecte-chatons).
Pour contribuer ou simplement regarder comment ça marche, vous pouvez consulter [notre dépôt git](https://framagit.org/bertille/tx-collecte-chatons).
Il contient notamment :
......
# Un convertisseur JSON-LD ?
Le JSON-LD est un formalisme du web sémantique. Il permet de donner du sens aux données en standardisant les noms des champs et en décrivant des types d'objets. [Cette vidéo de présentation permet de comprendre les enjeux du JSON-LD](https://www.youtube.com/watch?v=vioCbTo3C-4).
C'est une possibilité intéressante pour les Chatons, qu'on pourrait décrire comme des [organisations](https://schema.org/Organization). Ainsi, ils seraient plus facilement référencés, et comparables à d'autres organisations, en particulier à d'autres fournisseurs de services associatifs dans d'autres pays.
Cependant, pour donner des informations à la fois sur un Chaton et ses services, il faudrait mobiliser plusieurs schémas de JSON-LD dans le [contexte](https://www.w3.org/TR/json-ld/#the-context), et donc écrire un convertisseur un peu plus complexe ou bien définir notre propre document de contexte. C'est un chantier dans lequel nous n'avons pas eu le temps de nous lancer.
Pour un convertisseur simple, la correspondance des champs entre une Organization et notre schéma 0.0.2 serait :
```
{
"@context" : "http://schema.org",
"@type" : "Organization",
"name" : name,
"url": url,
"description": description,
"address" : address,
"logo": logo,
"areaServed": perimeter,
"foundingDate": creation_date
}
```
# Un schéma Json pour les Chatons
# Un schéma JSON pour les Chatons
## Le Json
Dans ce projet Tx, chaque Chaton est décrit par un fichier json (voir par exemple celui de [Picasoft](https://picasoft.net/picasoft.json)). Un fichier json décrit une structure de listes et d'objets définis par un système de clé-valeur. Par exemple, un Chaton a un champ `name` qui prend la valeur du nom du Chaton, un champ `url` qui prend l'url du site du Chaton, etc. Mais un Chaton propose également une liste de services, eux aussi décris par ce formalisme, avec un champ `type`, un champ `description`...
## Le JSON
Dans ce projet Tx, chaque Chaton est décrit par un fichier JSON (voir par exemple celui de [Picasoft](https://picasoft.net/picasoft.JSON)). Un fichier JSON décrit une structure de listes et d'objets définis par un système de clé-valeur. Par exemple, un Chaton a un champ `name` qui prend la valeur du nom du Chaton, un champ `url` qui prend l'URL du site du Chaton, etc. Mais un Chaton propose également une liste de services, eux aussi décris par ce formalisme, avec un champ `type`, un champ `description`...
Afin de permettre à un outil de recherche de rechercher des informations dans des champs précis, il est nécessaire de standardiser les clés de ces champs : si `name`, `nom` ou `nom_chaton` représentent la même information, il faut que tous les chatons respectent les mêmes conventions.
La convention que nous avons choisie en début de projet [a ses faiblesses](formatage_donnees.md). Il conviendrait de refonder le schéma, avec des valeurs soit en anglais, soit en «&nbsp;vrai&nbsp;» français.
## Le schéma
Pour ce faire, nous avons créé un *schéma*, lui aussi exprimé en langage json, qui explique quel champ est à utiliser pour quoi, et qui permet de *valider* un json décrivant un Chaton, garantissant que l'information est correctement formatée et sera utilisable par l'outil de recheche.
Pour ce faire, nous avons créé un *schéma*, lui aussi exprimé en langage JSON, qui explique quel champ est à utiliser pour quoi, et qui permet de *valider* un JSON décrivant un Chaton, garantissant que l'information est correctement formatée et sera utilisable par l'outil de recheche.
[Le schéma en question](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json) indique par exemple qu'un fichier json décrivant un Chaton est valide s'il a obligatoirement un champ `name`, `url`, `status` et `structure`, que s'il propose des services alors ces derniers ont un champ `type` et éventuellement une `description`...
[Le schéma en question](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/CHATONS_schema-0.0.2.json) indique par exemple qu'un fichier JSON décrivant un Chaton est valide s'il a un champ `name`, `url`, `status` et `structure`, que s'il propose des services alors ces derniers ont un champ `type` et éventuellement une `description`...
Pour commencer à décrire votre Chaton, un [template](https://framagit.org/bertille/tx-collecte-chatons/-/blob/master/schema/exemples/template.json) vide est disponible sur le Framagit, ainsi que quelques [exemples](https://framagit.org/bertille/tx-collecte-chatons/-/tree/master/schema/exemples).
Il est demandé aux Chatons de ne fournir que des jsons valides selon ce schéma, et encodés en utf-8, afin de permettre à l'outil de recherche de fonctionner. Les fichiers non-valides ne seraient simplement pas ajoutés à la liste des Chatons utilisée pour la recherche par le [crawler](http://chatons.picasoft.net/documentation/crawler/). Si d'aventure vous avez le moindre retour à faire sur ce schéma, n'hésitez pas à ouvrir une issue sur le [framagit](https://framagit.org/bertille/tx-collecte-chatons/), ou à nous contacter sur le [forum](https://forum.chatons.org/t/conception-dun-outil-de-centralisation-des-informations-des-chatons/1074) des Chatons.
Il est demandé aux Chatons de ne fournir que des JSON valides selon ce schéma, et encodés en utf-8, afin de permettre à l'outil de recherche de fonctionner. Les fichiers non-valides ne seraient simplement pas ajoutés à la liste des Chatons utilisée pour la recherche par le [crawler](http://chatons.picasoft.net/documentation/crawler/). Si d'aventure vous avez le moindre retour à faire sur ce schéma, n'hésitez pas à ouvrir une issue sur le [Framagit](https://framagit.org/bertille/tx-collecte-chatons/), ou à nous contacter sur le [forum](https://forum.chatons.org/t/conception-dun-outil-de-centralisation-des-informations-des-chatons/1074) du CHATONS.
......@@ -4,35 +4,20 @@ Comment marche ce site
Principe
--------
Les sources du site sont hébergées sur le [Framagit du projet](https://framagit.org/bertille/tx-collecte-chatons)
dans un dossier spécifique `site`.
Les sources du site sont hébergées sur le [Framagit du projet](https://framagit.org/bertille/tx-collecte-chatons) dans un dossier spécifique `site`.
Un serveur HTTP a été mis en place avec NGINX (grâce, notamment, à
[ce tutoriel](https://medium.com/@jgefroh/a-guide-to-using-nginx-for-static-websites-d96a9d034940))&nbsp;;
il a été configuré pour le site `chatons.picasoft.net`, en indiquant que le
contenu se trouvait dans `/var/www/html/chatons`&nbsp;; c'est en fait un lien
symbolique vers `/home/tx/tx-collecte-chatons/site`.
Un serveur HTTP a été mis en place avec NGINX (grâce, notamment, à [ce tutoriel](https://medium.com/@jgefroh/a-guide-to-using-nginx-for-static-websites-d96a9d034940))&nbsp;; il a été configuré pour le site `chatons.picasoft.net`, en indiquant que le contenu se trouvait