Le registre json.telebib2.org
Le registre est la source unique de vérité de la norme JSON Telebib2. Ce n'est pas une API : c'est un ensemble de fichiers statiques, servis à des adresses stables, dont chacun est immuable une fois publié. Cette simplicité est délibérée et elle est ce qui rend la norme utilisable sans dépendance et qu'elle est vérifiable.
L'identifiant est l'adresse
Chaque schéma déclare un $id, son identifiant absolu. Dans ce registre, cet identifiant est aussi l'adresse réelle du fichier : collez-le dans un navigateur, vous obtenez le schéma. Aucune table de correspondance, aucune résolution à écrire.
C'est ce qui permet à n'importe quel validateur de suivre les $ref tout seul. Les fichiers sont servis avec le type de média application/schema+json et l'en-tête CORS ouvert en lecture, de sorte qu'un outil tournant dans un navigateur peut les charger sans obstacle.
Le nommage suit une règle unique : <MIG>.<AAAANN>.json, où AAAANN est la release. Composants partagés, listes et types primitifs suivent la même logique, avec l'année de release à laquelle ils ont été modifiés.
Un identifiant, une adresse
curl -s https://json.telebib2.org/schemas/\
contract/contractEvent/M0103.202701.jsonCe que le serveur renvoie
Content-Type: application/schema+json
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=3600
Un fichier publié ne change jamais
C'est la règle fondatrice et elle n'a pas d'exception silencieuse. Une fois publié, un fichier de schéma n'est plus modifié -jamais, pas même pour corriger une faute de frappe dans une description. Toute évolution donne un nouveau fichier.
La conséquence est celle qui compte : un message que vous validez aujourd'hui se validera à l'identique dans dix ans, contre exactement le même schéma, octet pour octet. Aucune modification en amont ne peut invalider rétroactivement ce que votre système a accepté.
Deux fichiers échappent à cette règle et c'est assumé : schemaRouter.json, qui aiguille vers les schémas en service et compatibility.json, qui tient l'inventaire des versions. Tous deux décrivent un état du registre, pas un contenu. Ils doivent donc pouvoir changer sans changer de nom.
Comment savoir ce qui existe
Le listage des répertoires est désactivé : vous ne pouvez pas parcourir l'arborescence à l'aveugle. Ce n'est pas une restriction d'accès car tous les fichiers sont publics, mais un choix de conception. Un répertoire ouvert invite à deviner des adresses ; le registre préfère les déclarer.
La déclaration s'appelle catalog.json. C'est un inventaire lisible par une machine de tout ce que le registre publie : pour chaque fichier, son identifiant, son chemin, le MIG dont il relève, sa release, son état, une empreinte de contenu et sa taille.
L'empreinte mérite une mention : elle vous permet de vérifier qu'un fichier miroité localement est bien celui que le registre publie, sans avoir à le rapatrier.
Pour explorer à l'œil plutôt qu'au programme, le site www.telebib2.org présente les mêmes contenus avec des libellés, des index inverses et une recherche.
Une entrée du catalogue
{
"id": "https://json.telebib2.org/schemas/…",
"path": "schemas/community/M0151.202701.json",
"mig": "M0151",
"release": "202701",
"title": "M0151 — Certificat de sinistralité",
"domain": "community",
"state": "active",
"hash": "sha256-…",
"bytes": 118432
}
Comment le registre est rangé
L'arborescence suit les domaines fonctionnels de la norme. Les messages vivent dans leur domaine, découpés par famille (événements de contrat, modifications, ouverture de sinistre, quittances, extraits de compte). Tout ce qui est réutilisable vit sous shared/.
Deux dossiers accompagnent les schémas et méritent d'être connus.
payloads/ contient, pour chaque message, deux exemples valides : une variante min réduite aux propriétés obligatoires et une variante full qui exerce tout le schéma. Ce sont vos cas de test tout prêts.
validation/ contient le rapport de validation de chacun de ces exemples, sur deux moteurs indépendants. C'est le registre qui se contrôle lui-même et la preuve est publiée avec le résultat.
Le consommer correctement
Miroitez plutôt que de déréférencer. Valider un message en allant chercher chaque référence en HTTP fonctionne, mais rend votre validation dépendante du réseau et multiplie les allers-retours. Rapatriez les schémas, enregistrez-les par leur $id, résolvez hors ligne.
Cachez agressivement, sauf trois fichiers. Les fichiers de version sont immuables : leur durée de cache n'a pas de limite raisonnable. Le routeur, la table de compatibilité et le catalogue changent (ce sont les seuls à rafraîchir).
Notez la version du registre. Elle figure dans compatibility.json. Le jour où un comportement change, savoir avec quelle version vous validiez vous dira entre quels points chercher.
Un miroir local
# Récupérer l'inventaire
curl -s https://json.telebib2.org/catalog.json \
-o catalog.json
# Rapatrier chaque schéma déclaré
jq -r '.schemas[].path' catalog.json | \
while read p; do
mkdir -p "$(dirname "$p")"
curl -s "https://json.telebib2.org/$p" -o "$p"
done