ediverse

Type to search across standards, messages, tools and glossary.

ediverse Explore the platform

Spotlight PEPPOL BIS Billing 3.0 The EU e-invoicing mandate is here — France Sept 2026, Belgium Jan 2026, Germany 2025.

— 01

Foundations

— 02

Standards

— 03

Flagship messages

— 04

Tools

Canonical Mapping

Mapping as the concrete artifact of the Canonical Model — the atomic unit of work of a B2B integration team.

Problem

An EDI hub has 80 partners (each with its format: EDIFACT D.96A, EDIFACT D.21B, X12 4010, X12 6020, UBL 2.1, cXML 1.2, Factur-X) and 6 internal systems (SAP, Oracle, Sage, Salesforce, Snowflake lake, S3 archive). Without a canonical model, each partner must be mapped to each system: 80 × 6 = 480 mappings to maintain. An X12 6020 → 7050 evolution forces re-testing 6 mappings. Worse: each ERP team has its own convention, two mappings to SAP are inconsistent with each other.

Forces

  • Partner count grows. A retailer adds a new supplier every month.
  • Formats evolve. UN/EDIFACT minor versions, X12 versions, UBL 2.1 → 2.3.
  • Internal systems differ. SAP, Oracle, Sage have different conventions.
  • Mapping is versionable. A mapping is a coded artifact that can be tested, reviewed, deployed.

Solution

Define a semantically rich internal canonical model (covering the needs of every partner and system). Then materialise, for each external format, a bidirectional mapping partner ↔ canonical. Symmetrically for each internal system: mapping canonical ↔ system. The mapping is coded: XSLT, Smooks DSL, MapForce, Camel transformer, Apache NiFi processor, or simple Java/Python code with unit tests. Versioned in git, owned by a reference team. 

Without canonical mapping (N × M):     With canonical mapping (N + M):

  EDIFACT INVOIC ─┐                       EDIFACT INVOIC ─┐
  X12 810        ─┼──▶ SAP                                │
  UBL            ─┘                       X12 810        ─┤
                                                          ├─▶  Canonical
  EDIFACT INVOIC ─┐                       UBL            ─┤    Invoice
  X12 810        ─┼──▶ Oracle EBS                         │       │
  UBL            ─┘                       Factur-X       ─┘       │
                                                                  ├──▶ SAP
  EDIFACT INVOIC ─┐                                                │
  X12 810        ─┼──▶ Sage                                        ├──▶ Oracle
  UBL            ─┘                                                │
                                                                  └──▶ Sage
  3 partners × 3 ERPs = 9 mappings        3 + 3 = 6 mappings

EDI implementation

Concrete case: EDI hub with canonical Invoice.v3 as JSON Schema. Mapping edifact-invoic-d96a.xslt converts EDIFACT INVOIC to this JSON: UNH.S009 → messageType, BGM.C002 → invoiceTypeCode, DTM+137 → issueDate, RFF+ON → orderReference, NAD+BY → buyer, NAD+SE → seller, LIN/PIA/IMD segments → lines[] array. Reverse mapping canonical-to-x12-810.py generates X12 to Walmart. The mapping code includes unit tests: "PRI+AAA:25.00:CA equals canonical.lines[].priceExclTax = 25.00 EUR". Tools: BizTalk Mapper, Sterling Mapper, Boomi Map, Smooks, MapForce, or native code. Correspondence documentation in human-readable format (Markdown table) next to the mapping. Versioned mapping catalogue kept in an artefactory.

Anti-patterns

  • Ad-hoc mapping in each microservice. No central canonical model, each consumer maps itself: duplication, rule divergence.
  • Mapping as appendix of application code. If the mapping lives in the Java code, it is tied to the application release cycle. Extract it as a separate artifact.
  • Reversible but asymmetric mapping. Parsing EDIFACT to canonical tolerates gaps (no unit price: OK). Serialising canonical to EDIFACT must enforce strict schema. Confusing them produces invalid EDIFACT.
  • Mapping without tests. The slightest change silently breaks partner flows. Invest in a per-mapping test suite (fixture input → expected output).
  • Mapping with business logic. "If country = FR, tax 20%" in the mapping: tax rule scattered. Keep in a dedicated service.

Sources