Data Mapping Specification¶
Specification artifact — instantiates Schema Conflict Resolution
A build-ready document that states exactly how each field moves from a source data schema to a target — the transform, the exception path for values that don't fit, and the version it was cut against.
Once a team has decided to translate between two data schemas, someone still has to say precisely how — at the level an engineer can build against. Data Mapping Specification is that artifact: a per-field statement of the transform from source to target, the handling for values that don't cleanly convert, and a version stamp pinning which revision of each schema it was written for. Its defining property is that it is executable in intent — every entry is concrete enough to become code or a configured pipeline, with no "we'll figure it out at runtime" gaps. It is not a discussion of whether meanings correspond; it assumes that decision is made and encodes the mechanics of moving data across the gap.
Example¶
An e-commerce company migrates order data from a legacy ERP to a new order-management system. The spec walks field by field: the ERP's order_status (a code set of OP, HD, CN, SH, CL) maps to the OMS's named states, but HD ("hold") splits by reason — a fraud hold becomes on_review, a stock hold becomes backordered. That conditional is a translation rule with a caveat, not a lookup. Amounts stored as integer cents in the ERP convert to decimal currency in the OMS with a rounding rule stated explicitly. And a handful of ancient orders carry a status code retired years ago with no target equivalent; rather than drop or guess, the spec routes them to a quarantine queue for manual disposition — an exception path. The whole document is stamped against ERP schema v8.3 and OMS schema v2.1, so when the OMS adds a state next quarter, everyone knows this mapping predates it and must be rechecked.
How it works¶
- Specify per field, source to target. Each target field gets its transform: direct copy, lookup, computed conversion, or conditional split, written concretely enough to implement.
- State the caveats inline. Where a transform is only valid under conditions (units, reason codes, null handling), the condition rides with the rule rather than living in someone's memory.
- Route the misfits. Values with no valid target — retired codes, out-of-range, ambiguous — go to a named exception path (quarantine, default-with-flag, manual review), never a silent drop or best-guess.
- Pin the versions. The spec records which schema revisions it was cut against, so downstream changes trigger a recheck instead of silently invalidating it.
Tuning parameters¶
- Transform granularity — coarse field-to-field rules versus fine conditional splits. Finer rules preserve meaning but multiply the surface that must be maintained.
- Exception strictness — how aggressively non-conforming values are quarantined versus defaulted through. Strict quarantine protects integrity but can stall a migration on a long tail.
- Directionality — one-way (migration) or round-trippable (ongoing sync). Round-trip specs must avoid lossy transforms, which sharply constrains what mappings are allowed.
- Version-binding tightness — pin to exact revisions or to a compatible range. Tight pins catch drift early; loose ranges reduce churn but risk silent invalidation.
When it helps, and when it misleads¶
Its strength is removing ambiguity from execution: an engineer can build the pipeline without re-deciding semantics, and the exception path guarantees that data which doesn't fit is surfaced rather than corrupted. Routing through a shared canonical data model rather than point-to-point pairs keeps a growing integration from turning into an unmaintainable web of one-off specs.[n1]
Its failure mode is lossy transformation dressed up as a clean rule: a spec can look complete while quietly collapsing a distinction — mapping three source states to two target states because the target simply lacks the third. The classic misuse is treating the spec as proof the schemas are semantically compatible, when it only proves the data can be moved; a field can transfer perfectly and still mean something different on the other side. The guarding discipline is to have the semantic correspondence decided and case-tested upstream, and to keep the exception path honest rather than defaulting the awkward tail into a bucket that hides the loss.
How it implements the components¶
translation_rule— each field entry is a concrete, condition-bearing rule for how a value moves from source to target.exception_handling_path— values with no valid target are routed to a named disposition (quarantine, flag, manual review) instead of dropped or guessed.versioned_mapping_record— the spec is stamped to the schema revisions it targets, so schema changes trigger a recheck.
It assumes the resolution mode is already chosen and does not decide it (integration_decision) — that is Ontology Mapping Workshop — and it records the translation rules but does not maintain their ownership and open ambiguities over time (semantic_owner, residual_ambiguity_log), which is Translation Register.
Related¶
- Instantiates: Schema Conflict Resolution — the executable translation layer that moves data once the correspondence is decided.
- Consumes: Schema Crosswalk Table — supplies the field-level correspondences this spec turns into concrete transforms.
- Sibling mechanisms: Boundary-Spanner Review Session · Case-Based Mapping Test · Glossary Alignment Table · Ontology Mapping Workshop · Schema Crosswalk Table · Semantic Interoperability Review · Taxonomy Reconciliation Review · Translation Register
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Data Mapping Specification operates as a non-executable information artifact that externalizes static or prospective structure because it a build-ready document that states exactly how each field moves from a source data schema to a target — the transform, the exception path for values that don't fit, and the version it was cut against.
Independent corroboration: The frozen evidence defines Data Mapping Specification as 'A build-ready document that states exactly how each field moves from a source data schema to a target — the transform, the exception path for values that don't fit, and the version it was cut against', so its operative form is Representation, Specification & Plan.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Enterprise application integration cohered field-level source-to-target mapping specifications with concrete transforms, exception handling, and pinned schema versions.
Review resolution: Database integration established field-level source-to-target mappings, conversions, and validation rules as a software artifact.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
Data Mapping Specification and Translation Register both center on translation rules, but they sit at opposite ends of the lifecycle: this spec is the build-time artifact an engineer implements once, while the register is the living ledger that tracks who owns each rule and which ambiguities stay open as schemas evolve. Cut the spec to build; keep the register to govern.
[n1] A canonical data model (from Hohpe & Woolf's Enterprise Integration Patterns) is a shared intermediate schema that each system maps to and from, so N systems need N mappings rather than N² point-to-point pairs — the standard antidote to integration spaghetti. ↩