Modèle canonique interne

Sans pivot, chaque nouveau partenaire ajoute autant de mappings que vous avez de systèmes cibles. Avec un pivot, vous n'avez qu'à parler au pivot. Le calcul est linéaire au lieu d'être quadratique.

Problème — le mapping n × m

Une plateforme EDI doit, par construction, parler à plusieurs partenaires (chacun avec son standard : EDIFACT, X12, UBL, cXML) et alimenter plusieurs systèmes cibles (ERP, WMS, TMS). Si chaque mapping est écrit direct du partenaire vers le système, on aboutit à un produit cartésien : avec 10 partenaires et 4 systèmes, c'est 40 mappings à maintenir. Ajouter un partenaire ajoute 4 mappings ; ajouter un système ajoute 10. Cette croissance n × m est inviable au-delà de quelques années.

plaintext mapping-comparison.txt

Sans canonique — n × m mapping :

  Partenaire A (EDIFACT)  ┐                ┌─── ERP X
  Partenaire B (X12)      ├── 12 mappings ─┤
  Partenaire C (cXML)     │   (3 × 4)      ├─── ERP Y
  Partenaire D (UBL)      ┘                └─── ERP Z

Avec canonique — n + m mapping :

  Partenaire A ──┐                  ┌── ERP X
  Partenaire B ──┤                  ├── ERP Y
  Partenaire C ──┼─► CANONIQUE ─────┤
  Partenaire D ──┘   (1 schéma)     └── ERP Z

  → 7 mappings au lieu de 12 (4 IN + 3 OUT)

Forces

Hétérogénéité réelle des partenaires. On ne peut pas forcer tous ses partenaires à parler un standard unique — ils restent sur leur héritage EDIFACT D.96A, leur X12 .004010 ou leur cXML 1.2.069.
Hétérogénéité réelle des systèmes. ERP, WMS, BI et portail client ont chacun leur schéma interne, souvent dicté par l'éditeur (SAP IDoc, NetSuite REST, Salesforce SOQL).
Évolutions semestrielles. EDIFACT et X12 publient deux releases par an. Sans pivot, chaque mise à jour répercute sur tous les mappings sortants concernés.
Stabilité du modèle pivot. Le canonique doit évoluer moins vite que les périphériques, sinon il perd son intérêt. C'est une contrainte forte de design.

Solution : un canonique au milieu

Le pattern Canonical Data Model (Hohpe & Woolf, 2003) prescrit de définir un schéma interne unique — appelons-le le canonique — qui sert de pivot entre les périphériques. Chaque partenaire a un mapping IN qui traduit son format vers le canonique, et chaque système cible a un mapping OUT qui traduit le canonique vers son format interne. Le canonique lui-même n'est jamais exposé.

Le canonique est typiquement défini en JSON Schema (Draft 2020-12) ou en XSD. Le choix de JSON facilite l'outillage moderne (TypeScript types générés, validation Zod/Ajv), mais XSD reste plus adapté si l'on veut s'aligner sur des canoniques publics (OAGi BODs, UBL).

Exemple d'un canonique ORDER JSON

Voici à quoi ressemble une commande pivot minimaliste pour une plateforme EDI :

json canonical-order-v3.json

{
  "$schema": "https://ediverse.example.com/schemas/order/v3",
  "kind": "Order",
  "version": "v3",
  "header": {
    "id": "ORD-2026-00187",
    "issuedAt": "2026-05-14T10:18:00Z",
    "currency": "EUR",
    "buyer": {
      "gln": "5410000000123",
      "name": "Coopérative Textile Nord",
      "address": { "country": "FR", "city": "Lyon" }
    },
    "seller": {
      "gln": "5410000000456",
      "name": "Atelier Marchand SARL"
    }
  },
  "lines": [
    {
      "id": "1",
      "itemId": { "scheme": "gtin", "value": "3520000001234" },
      "description": "Toile écrue 220 g/m²",
      "quantity": { "value": 120, "unit": "MTR" },
      "unitPrice": { "value": 18.00, "currency": "EUR" }
    }
  ]
}

Quelques principes à retenir :

Identifiants typés. itemId a un scheme explicite (gtin, sap-mat, …). On évite ainsi de confondre GTIN et SKU interne dans 18 mois.
Versioning du canonique. Le v3 dans le schéma indique qu'on est sur la troisième révision. Les anciens mappings v2 peuvent coexister pendant une fenêtre de migration.
Unités explicites. quantity.unit en code UN/ECE Recommendation 20 (MTR = mètre, PCE = pièce). On ne suppose jamais l'unité par défaut.
Pas de champ optionnel non-typé. Si un partenaire a un besoin métier non couvert, on ajoute un champ explicite dans le canonique, on n'autorise pas un sous-objet extra libre.

Off-the-shelf — OAGi BODs et UBL

Plutôt que d'inventer un canonique, on peut adopter un canonique public :

OAGi BODs (Business Object Documents) — Open Applications Group, depuis 1995. Catalogue de plus de 700 BOD couvrant commande, facture, paiement, RH, manufacturing. Adopté par Oracle Fusion et SAP S/4HANA comme schéma d'intégration intermédiaire. oagi.org
UBL (Universal Business Language) — OASIS, version 2.4 (2023). Plus orienté facturation/procurement, fondation technique de PEPPOL BIS Billing 3.0. docs.oasis-open.org/ubl

Les deux ont l'avantage d'un mainteneur stable et d'une communauté outillée (parseurs, validateurs). Inconvénient : ils sont volumineux et couvrent souvent plus que ce qu'on souhaite porter en interne. La pratique courante est de profiler un canonique public, c'est-à-dire d'en extraire un subset documenté qui devient le canonique interne.

Gouvernance du canonique

Le pattern n'est viable que si le canonique est gouverné comme une API publique :

Versionnement sémantique. v1, v2, … avec règle claire pour les changements breaking (nouveau majeur) vs additifs (mineur).
Fenêtre de migration. Quand on publie v3, on supporte v2 en parallèle pendant 6 à 12 mois. Les mappings IN/OUT existants n'ont pas à être tous migrés le même week-end.
Validation à l'entrée et à la sortie. Un mapping IN qui produit un canonique invalide doit être rejeté avant tout traitement applicatif. Un mapping OUT qui consomme un canonique doit le valider à l'entrée du processus.
Documentation dérivée. Le canonique est la source unique de vérité : les schémas, les types TypeScript, la documentation partenaires, les tests d'intégration en sont tous générés. Pas de copie manuelle.

Anti-patterns

Canonique passe-partout. Un schéma avec un champ customFields: Record<string, any> où chaque mapping met ce qu'il veut. Plus de typage, plus de garantie : ce n'est plus un canonique, c'est un sac à dos.
Canonique = standard fournisseur. Adopter le format SAP IDoc comme canonique parce que tout passe par SAP est tentant et catastrophique le jour où l'on remplace SAP. Le canonique doit être neutre vis-à-vis des périphériques.
Versionnement implicite. Ajouter un champ obligatoire sans bumper la version casse silencieusement tous les mappings existants.
Mappage direct partenaire → système par-dessus le canonique, « pour aller plus vite ». On reconstruit le n × m qu'on voulait éviter.
Canonique trop riche. Reprendre UBL entier dans son canonique interne sans le profiler donne 600+ éléments dont 95 % ne servent à rien — chaque mapping devient une exégèse.

Patterns liés

Acquittements — l'ACK métier renvoyé au partenaire est généré depuis le canonique.
Flux d'exception — l'invalidation du canonique est l'un des points d'entrée.

Sources

Hohpe G., Woolf B. — Enterprise Integration Patterns, pattern Canonical Data Model, le pattern originel. enterpriseintegrationpatterns.com — Canonical Data Model
OAGi — Open Applications Group. Catalogue des Business Object Documents (BODs). oagi.org
OASIS — UBL 2.4 (2023). Schéma XML universel pour les documents commerciaux. docs.oasis-open.org/ubl/UBL-2.4.html
UN/ECE Recommendation 20 — codes unités de mesure (kg, MTR, PCE, …). Référence pour le typage des quantités dans tout canonique. unece.org/trade/uncefact/cl-recommendations
JSON Schema Draft 2020-12. Le standard de schéma dominant pour les canoniques modernes. json-schema.org

Fondamentaux

Standards

Messages phares

Outils