Canonical Data Model vs Field Mapping: How to Choose
Canonical data model vs field mapping depends on reuse: use crosswalks for bounded links, shared records for recurring integrations, ontologies for reasoning.
Use direct field mappings for a few well-defined connections. Choose a canonical data model when several integrations can reuse the same business record structure.
Add an ontology when software needs to reason over relationships. These are different choices: agreeing on terms, moving data, and drawing conclusions from linked facts.
Key takeaways
Field mappings or a canonical data model?
- Separate the jobs: distinguish shared terms, source-field transformations, and shared record structures.
- Map directly: keep per-source crosswalks when each source’s meaning and exceptions stay manageable.
- Share a model: use a canonical structure when recurring integrations can reuse stable business records.
- Add an ontology: formalize relationships when software must use them for classification or reasoning.
- Support agent retrieval: store documented mappings in AKB while data owners retain responsibility for their semantics.
Are you aligning terms, fields, or shared record structures?
Start by naming the thing you need to make consistent. A business glossary defines terms such as “customer,” a field crosswalk connects system-specific fields to those terms, and a canonical data model defines the shared structure that integrations exchange.
The W3C SKOS reference describes concepts, labels, and links that help teams align vocabularies. A canonical data model instead defines the fields and meaning of records exchanged across systems. A semantic metrics layer standardizes analytics calculations, such as net revenue, and can complement either integration approach.
| Decision criterion | Direct field crosswalk | Canonical data model |
|---|---|---|
| Integration shape | A defined source-to-target path with explicit links between fields or business terms | Participating applications produce and consume messages in one application-independent common format |
| Mapping work | Document the source and target fields, transformations, conditions, and exceptions for each connection | Map each participating application to and from the common format |
| Reuse test | Choose it when each integration’s meanings and exceptions remain clear and testable | Consider it when recurring integrations reuse stable business concepts and attributes |
| Change review | Review the affected source-to-target rules as systems change | Govern shared definitions and check compatibility for dependent producers and consumers |
When is a direct field crosswalk enough?
Choose a direct field crosswalk for a bounded integration when teams can review and test the rules. Record the source system, entity, and field; target term or field; transformation, condition, and exception. Similar labels alone do not prove that fields mean the same thing, and source-specific attributes can stay local when other systems do not need them.
For example, suppose a CRM field called account_ref identifies a CRM account, while a billing field called customer_no identifies a billing account. A crosswalk can map both to an enterprise account identifier when their entity scope matches. If one field identifies a parent account and the other a bill-to account, the mapping needs a condition or a separate relationship rather than a blind one-to-one match.
MuleSoft’s definition-driven mapping example uses an external definition for field renames and defaults. Enterprise crosswalks can also document conversions, code or unit changes, null handling, and rule conditions.
In the canonical data model integration pattern, two applications exchanging messages with each other need two direct translators; under this all-to-all exchange pattern, routing both through a canonical model needs four, one into and one out of the model for each application.
When is a canonical model worth governing?
Choose a canonical model when several integrations reuse stable business concepts and attributes. Participating systems map to and from one application-independent format, rather than negotiating a separate representation for each connection, as described by the canonical-model pattern.
Use it when that reuse outweighs the governance work: assign domain owners, settle shared meanings, keep the common core small, and review changes for affected producers and consumers. Put source-specific attributes in clearly named extensions.
Google Cloud’s schema-lifecycle guide illustrates reuse: Customer and Supplier schemas can reference a common Address schema. Shared definitions reduce repeated work, but changes still require checking which producers and consumers are affected.
The schema-evolution guide defines backward compatibility as new-schema consumers reading older data, and forward compatibility as older-schema consumers reading newer data. Rules vary by format and system, so specify the required direction for model changes.
Google Cloud’s Schema Registry can reject a schema version that fails its configured compatibility rule. This registry capability is separate from AKB.
When does a formal ontology add value?
Choose a formal ontology when an application needs machine-interpretable relationships to infer classifications, not just align terms or move values between fields.
The W3C OWL 2 Primer explains that class relationships must be stated, not inferred from labels alone. For example, an axiom can state that every managed-service contract is a service contract, allowing a reasoning system to classify it accordingly. OWL axioms support inference; by themselves, they do not validate required fields under a closed-world rule or prove a field transformation correct.
Use that logic when an application must answer relationship-based questions or infer membership. If the goal is only to align terms such as “client” and “customer,” a glossary or vocabulary scheme is enough.
Where does AKB fit when agents retrieve mapping records?
A data team can keep its mapping inventory in tables and supporting decisions in documents, then make those records available to agents through MCP. AKB provides hybrid semantic and keyword retrieval and explicit relations, helping agents retrieve the mapping context alongside the integration architecture.
A mapping record might capture the source field, target business term, applicable condition, transformation rule, model version, and owning team. Relations can connect a source field to a target term or a mapping to a model version. AKB makes these decisions available without becoming the authority that defines the canonical schema.
AKB’s document history and diff tools help teams track how supporting decisions changed. See the AKB repository.
FAQ
What is a canonical data model?
A canonical data model is a shared, application-independent structure that participating systems map to and from. The canonical-model pattern uses this common format to reduce direct dependence between application-specific formats.
What is canonical mapping?
Canonical mapping is the transformation from a source system’s representation into a shared model, and from that shared representation into a destination format when data moves onward. Each integration documents the source fields, target fields, conversions, and applicable conditions.
What are field mappings?
Field mappings are rules connecting particular source fields to target fields or business terms. MuleSoft’s definition-driven mapping example uses a mapping definition to specify field renames and default values.
Which option should you choose, and what should you record?
Keep direct mappings when the rules remain manageable; choose a shared model when integrations reuse the same structure. Add an ontology for a specific reasoning need.
- Representative mapping and edge cases: Note one source-to-target mapping and relevant edge cases.
- Reuse, ownership, and compatibility: Record reuse scope, who owns changes, and compatibility requirements.
- Acceptance and retrieval: Record acceptance results and agent retrieval needs where relevant.
Read the AKB documentation
See how AKB can make mapping decisions and their supporting records available to agents through MCP.
