In this article
A canonical data model reduces rework by giving EDI, JSON, XML and CSV maps one shared description of an order, shipment or invoice. Instead of teaching every connection the structure of every other connection, you translate each format into or out of that shared structure. Changes can then be assessed at the affected boundary rather than copied across unrelated maps.
The approach works best when the model describes business meaning, while each map handles its own format and trading partner rules. BOLD VAN works with organizations that need EDI mapping into business systems and connections to platforms that use APIs. The practical lesson from that work is to separate a reusable order definition from the requirements of any particular partner or application.
What a canonical data model represents
A canonical data model is an agreed internal structure for information shared across systems. For an order, it may distinguish the order identifier, relevant parties, dates and requested delivery information from a collection of lines containing products, quantities and prices. Each property needs a clear meaning and an owner. The model should also say whether a value may be absent and whether it can occur more than once.
Imagine a manufacturer receiving an ANSI X12 850 Purchase Order and sending the resulting order to an ERP. The same manufacturer may accept JSON from an e-commerce platform and send a CSV file to a warehouse. A shared order model gives those flows consistent definitions for buyer, ship-to location and order line, even though their external representations differ.
That shared meaning does not make all inputs interchangeable. A source may omit information a destination requires. A product identifier may have a different meaning in another system. Your model needs to record those differences so a map can reject, enrich or route an incomplete order for review rather than quietly guess.
The central rule: Keep partner-specific requirements at the edge. If you build the shared model around one retailer's guide or one ERP export, you move rework into the model instead of reducing it.
How EDI, JSON, XML and CSV maps use the same structure
An inbound map interprets its source, checks what it can and creates the shared business record. An outbound map reads that record and produces the destination's required structure. The maps still exist. What changes is their dependency: an EDI map does not need to understand a warehouse CSV layout, and the CSV map does not need to understand X12.
| Format | What the map handles | What you should confirm |
|---|---|---|
| EDI | Transaction structure and partner-specific business requirements | The trading partner's published EDI implementation guide and version |
| JSON | Application request or response data | The platform's current documentation and implementation behavior |
| XML | Structured application messages and repeated content | The receiving system's schema and version |
| CSV | Rows, columns and the relationship between headers and lines | The agreed layout, missing values and how repeated lines are grouped |
Consider an 850 mapped into a canonical order, then converted into an ERP's expected structure. If you later add a JSON order source, you write its inbound map against the order model. You still test the ERP destination, but you do not need to embed the new source's layout in the ERP map. For related transactions, such as the X12 856 Ship Notice/Manifest and 810 Invoice, use separate business models or clearly defined related structures. An order model cannot safely stand in for shipment or billing data.
A practical process for building and testing the model
Start with one business event
Choose a flow with repeated mapping work, such as purchase orders. Inventory its sources, destinations and owners. Collect the relevant partner implementation guides and application documentation before deciding which data belongs in the common structure. Record which information every destination uses and which information serves only one connection.
Define meanings before formats
Write a short definition for each shared property. Specify its business purpose, whether it is required, its permitted values when those matter and how it relates to repeated records. Keep source-specific codes in a translation rule where possible. If two systems use the same label for different concepts, give those concepts different definitions.
Test each boundary and the complete path
Test whether the source parses, whether its values become the correct shared record and whether the destination receives usable data. Include missing values, multiple order lines, unexpected identifiers and revised orders where applicable. Save representative inputs and expected outputs as regression tests when maps or requirements change.
Separate syntax confirmation from business acceptance. A 997 functional acknowledgment tells the sender whether a document passed the receiver's syntax check. It can report acceptance or rejection, and it does not mean the order or its content was accepted. Check downstream processing before treating an order as complete.
Common pitfalls and best practices
- Copying one application schema: It can make every other source conform to constraints that belong only to that application. Define shared meaning first.
- Making everything optional: Specify what the business needs and handle missing required data explicitly.
- Flattening repeated records: Preserve the relationship between an order and its lines, particularly when translating to or from CSV.
- Changing the shared model without impact review: Identify affected inbound maps, outbound maps and tests before releasing a change.
- Assuming a standard replaces partner guidance: Check each trading partner's published EDI implementation guide. Versions and partner rules can differ.
Keep a concise mapping record for each connection: source definition, shared property, transformation rule, destination requirement and exception owner. That record helps you distinguish a changed partner requirement from a changed business definition. It also makes it easier to decide whether a fix belongs in one edge map or in the shared model.
Where managed integration fits
BOLD VAN maps data to and from ERP systems such as SAP, Oracle ERP and Infor CloudSuite, WMS platforms such as ShipHero, TMS platforms such as Oracle TMS and e-commerce platforms such as Shopify, among others. BOLD Integration covers EDI mapping into your ERP, WMS or other system, including connections to a platform's API in both EDI-to-API and API-to-EDI directions. The exact mapping follows the relevant partner guide and system documentation.
When a partner changes its requirements, BOLD VAN updates the map, and minor changes are typically handled at no cost. New maps are typically ready to test in about two days. For a lean IT team, managed mapping can also reduce reliance on the person who originally built each connection. You still need business owners to approve shared definitions and test expected outcomes.
A canonical data model earns its place when it makes changes easier to locate and safer to test. Begin with one event, define it clearly and keep format-specific rules at the boundaries. If your order, shipment or invoice maps repeat the same business logic across systems, explore BOLD Integration to discuss a more maintainable mapping approach.
Frequently asked questions
What is a canonical data model in EDI integration?
It is a shared internal definition of business information, such as an order or shipment. Each EDI or application map translates between its own format and that definition.
Does a canonical data model replace EDI maps?
No. You still need maps for each source and destination. The model gives those maps a shared business structure so they do not depend directly on every other format.
How do you handle a field that exists in one format but not another?
First decide whether the information has a shared business purpose. If it does, define how missing values are handled. If it serves only one partner or system, keep its rule in that connection's map.
Does a 997 acknowledgment mean an EDI order was accepted?
No. A 997 functional acknowledgment tells the sender whether a document passed the receiver's syntax check. It can report acceptance or rejection, and it does not mean the order or its content was accepted.
