Explorer la norme sur telebib2.org
La norme vit à deux adresses, et la distinction vaut d'être posée une fois pour toutes : www.telebib2.org est fait pour être lu par des humains qui cherchent à comprendre, json.telebib2.org pour être consommé par des programmes qui valident. Le premier vous sert pendant la conception, le second en production. Ne les intervertissez pas.
Le catalogue, point de départ
La page Documentation rassemble les cinq portes d'entrée de la norme. Chacune répond à une question différente, et savoir laquelle pousser fait gagner beaucoup de temps.
- Message Content Inventories : la définition des messages.
- Releases : ce qui a changé, et quand.
- Listes de codes : les valeurs autorisées.
- Annuaires : les briques, EDIFACT et JSON.
- Documents par domaine : filtrés par processus et branche.
Si vous ne savez pas par où commencer, commencez par les MCI. C'est le pivot de la norme : chaque message y est décrit ligne à ligne, indépendamment de la représentation technique, et c'est de là que partent les liens vers l'EDIFACT comme vers le JSON.
La fiche d'un message : le pivot et ses deux implémentations
La fiche d'un message est l'écran le plus dense du site et le plus utile. Elle présente le MCI (la liste des lignes sémantiques du message), avec pour chacune sa description, son caractère obligatoire ou non et la liste de codes qui s'y applique.
Le panneau Implémentations, sur le côté, est la pièce à connaître : il pointe vers les deux représentations du même message, le MIG EDIFACT d'un côté, le schéma JSON de l'autre. C'est le chemin le plus court pour répondre à « à quoi correspond ce segment dans le nouveau format ? », sans avoir à tenir une table de correspondance à la main.
La fiche donne aussi l'émetteur, le destinataire, l'objet et l'action du message et une comparaison de versions qui montre ce qui a bougé d'une release à l'autre (un filtre isole les lignes modifiées).
L'annuaire : deux moitiés, dix rayons
L'annuaire se divise en deux moitiés : les composants EDIFACT d'un côté, les briques des schémas JSON de l'autre.
La moitié JSON compte quatre rayons :
- Composants : les objets réutilisés : adresse, nom, référence, garantie.
- Listes Telebib : celles que les groupes de travail de la normalisation arbitrent.
- Listes officielles : celles qui viennent d'ailleurs : FSMA, DIV, NACE.
- Types primitifs : montant, pourcentage, mesure, comptage, durée.
La moitié EDIFACT en compte six : segments, éléments de données, composites, qualifiants, groupes de segments et unités d'échange.
La fiche d'un schéma affiche son $id, son chemin, ses propriétés de premier niveau avec type, cardinalité et règles, et un lien vers le JSON brut. Une fiche de liste affiche ses valeurs avec les libellés français et néerlandais côte à côte (ce que le fichier de schéma contient aussi, mais en bien moins lisible).
Deux fonctions que le registre ne peut pas rendre
Le registre est un ensemble de fichiers. Il ne sait pas répondre aux questions qui traversent ces fichiers alors que ce sont précisément celles qu'on se pose en implémentant.
« Qui utilise ce composant ? » Le panneau Utilisé par d'une fiche de schéma répond à l'envers : il liste tous les schémas qui référencent celui que vous consultez. Avant de vous appuyer sur un composant partagé, c'est la façon la plus rapide de voir dans quels messages il apparaît réellement.
« De quoi ce schéma dépend-il ? » Le panneau Dépendances déplie l'arbre des $ref. Un schéma de MIG en tire couramment une trentaine : composants partagés, listes de valeurs, types primitifs. Les parcourir avant d'écrire du code évite de redécouvrir une contrainte au moment de la recette.
S'y ajoute la recherche, qui indexe aussi bien les messages que les listes et les propriétés (souvent le chemin le plus court quand on ne connaît qu'un nom approximatif).
Où s'arrête le site, où commence le registre
Une règle et elle est stricte : votre code ne doit jamais lire le site. Les pages sont faites pour l'œil, leur structure peut changer sans préavis et rien n'y est contractuel. Le registre, lui, est un point de distribution stable dont chaque fichier est immuable une fois publié.
Pour découvrir par programme ce que le registre contient, l'entrée est catalog.json : un inventaire de tous les schémas publiés, avec pour chacun son identifiant, son chemin, son MIG, sa release, son empreinte et sa taille. Le listage des répertoires est désactivé, le catalogue est la façon prévue de savoir ce qui existe. L'article sur le registre en détaille le contenu.