Composants, listes et types primitifs
Un schéma de message ne décrit presque rien lui-même. Il assemble : des composants pour les objets qui reviennent partout, des listes pour les valeurs autorisées, des types primitifs pour la forme des valeurs. Comprendre ces trois briques, c'est comprendre pourquoi une adresse a exactement la même forme dans un contrat et dans un sinistre.
Les composants partagés
Un composant est un morceau de schéma défini une fois et référencé partout. Le registre en publie près de nonante, rangés en sept familles.
- units : les briques élémentaires : nom, adresse, référence, profession.
- parties : les intervenants et leurs identifications.
- riskObjects : la famille la plus fournie : véhicules, bâtiments, personnes, animaux…
- guarantees : les garanties et sous-garanties.
- damages, clauses, licences : les objets propres au sinistre, aux clauses et aux agréments.
L'intérêt n'est pas l'économie de lignes : c'est la garantie d'uniformité. Une adresse porte les mêmes propriétés, les mêmes longueurs et les mêmes règles quel que soit le message où elle apparaît. Votre code écrit une fois la lecture d'une adresse et elle vaut partout.
Un composant : la référence
{
"title": "reference",
"type": "object",
"additionalProperties": false,
"required": ["referenceContent"],
"properties": {
"referenceContent": {
"type": "string",
"maxLength": 40
},
"statusCoded": { "$ref": "…/statusCoded_V1.json" }
}
}Utilisé partout, sous des noms différents
{
"policyReference": { "referenceContent": "POL-…" },
"numberPlate": { "referenceContent": "1-ABC-123" },
"claimReference": { "referenceContent": "SIN-…" }
}
Les listes de valeurs, en deux familles
Le registre publie près de trois cents listes et elles ne se ressemblent pas toutes. La distinction est structurelle, pas cosmétique.
Les listes Telebib (plus de deux cent soixante) sont celles que les groupes de travail de la normalisation arbitrent. Leurs valeurs sont des noms lisibles, déclarés dans un enum, accompagnés de libellés français et néerlandais dans x-enum-labels.
Les listes officielles (une quinzaine) viennent d'organismes extérieurs : FSMA, DIV, nomenclature NACE, zones de police. Elles sont reprises telles quelles, codes d'origine compris et s'écrivent avec oneOf plutôt qu'avec enum. Un code pays y vaut "B", un type de carburant "1".
Si vous générez du code depuis les schémas, votre générateur doit savoir traiter les deux formes. C'est le seul endroit du registre où la structure d'un même concept varie.
Liste Telebib — enum et libellés
{
"title": "AppliedBonusMalusGrade",
"type": "string",
"enum": ["minus1", "_00", "_01", "_11"],
"x-enum-labels": {
"_11": { "fr": "11", "nl": "11" }
}
}Liste officielle — oneOf et titres
{
"title": "countryCode",
"type": ["string"],
"oneOf": [
{ "const": "B", "title": "Belgium" },
{ "const": "F", "title": "France" },
{ "const": "NL", "title": "Netherlands" }
]
}
Les types primitifs
Les primitifs disent la forme d'une valeur, jamais son sens. Ils tiennent dans un seul fichier et c'est voulu : quand une décision porte sur la représentation des montants, elle se prend à un endroit et vaut pour les cent vingt propriétés qui s'y réfèrent.
Le sens, lui, est porté par le nom de la propriété et sa description. C'est pour cela qu'un primitif de mesure n'a pas d'unité : livingAreaMeasure est en mètres carrés parce que son nom et sa description le disent, pas parce que le primitif le sait.
Retenez la règle de partage : tout ce qui a une virgule est une chaîne, seuls les comptages sont des nombres. Un article entier explique pourquoi.
L'unité est dans le nom, pas dans le type
{
"livingAreaMeasure": "142.50",
"vehicleWeightMeasure": "1350",
"premiumAmount": "1234.56"
}
Comment ces briques sont versionnées
Composants et primitifs portent une release dans leur nom, exactement comme les messages. Mais la règle qui les gouverne est différente et elle surprend : une brique inchangée n'est pas republiée.
Autrement dit, un message d'une release donnée référence la version de chaque composant qui était en vigueur au moment de sa publication (laquelle peut être plus ancienne que le message lui-même). Un schéma de 2027 peut parfaitement pointer vers une adresse de 2025 si l'adresse n'a pas bougé entre-temps.
Ce n'est pas le cas aujourd'hui pour la release 202701 : l'ensemble des composants ayant été revu lors de sa préparation, tous ses messages référencent des composants 202701. Mais la règle vaut pour la suite et votre code ne doit pas supposer que la release d'un composant suit celle du message qui l'utilise.
Les listes, elles, ne suivent pas les releases : elles portent un numéro de version propre, _V1, _V2, incrémenté quand leur contenu change.
Ne présumez pas de la release d'une brique
{
"$ref": "…/components/units/address.202701.json"
}
Le rapport est saisissant : sur les quatre cent vingt fichiers du registre, une cinquantaine seulement décrivent des messages. Tout le reste est de la brique partagée : près de trois cents listes, nonante composants et un fichier de primitifs.
C'est le signe d'une norme qui a mis son effort au bon endroit. Ce qui est commun est décrit une fois ; un message ne fait qu'assembler.