Forward/Reverse Field-Mapping Specification¶
Document — instantiates Bidirectional Consistency Mapping
Records each directional mapping, loss, default, authority, and version.
A Forward/Reverse Field-Mapping Specification is the reference document that states, field by field, exactly how a value in A becomes a value in B and how it comes back — as two separately named transforms, never as one assumed-reversible arrow. Its defining idea is that forward and reverse mappings are distinct, individually reviewable functions: the forward map may collapse three source categories into one target code, and the reverse map cannot recover which of the three it was, so the specification writes down that loss on purpose rather than pretending the round trip is clean. Each entry records the forward rule, the reverse rule, what is lost or defaulted in each direction, unknown-versus-absent semantics, and the version of the mapping. It is the meaning that connectors derive their behavior from — the canonical semantics, not the running code.
Example¶
A hospital's clinical system syncs vaccination events to a national immunization registry. The spec's entry for vaccine_product reads: forward — map the EHR's granular NDC drug code to the registry's coarse CVX vaccine-group code (a documented many-to-one collapse); reverse — map CVX back to the EHR's vaccine_group_display, explicitly not to a specific NDC, because the product-level detail is unrecoverable. The dose_volume entry: forward converts millilitres to the registry's fixed-precision integer microlitres; reverse rounds back, with a noted tolerance of ±1 µL. The patient_deceased field entry distinguishes unknown (never reported) from absent (reported as no), so the reverse map never silently converts a missing value into a positive "alive."
The outcome is that a round-trip test on vaccine_product is written to expect equivalence under declared loss — CVX group preserved, NDC deliberately not — rather than exact string recovery, so the loss is documented design instead of a bug someone later files. Anyone building the connector reads this document to know what the transform must do and what it may not promise.
How it works¶
- Two named transforms per field. Forward and reverse are written separately, each with its own rule, so nobody assumes invertibility from the existence of a forward map.
- Loss and locality recorded as data. Many-to-one collapse, precision limits, defaults filled on reverse, and local-only fields that never map are all stated explicitly.
- Unknown/absent/deleted/not-applicable semantics. Each field declares how these edge values behave in each direction, because that is where silent fabrication hides.
- Invariant stated at the semantic level. For each field, what relation must hold — exact equality, transformed correspondence, or bounded tolerance — is written as the correctness target, not left to byte comparison.
- Versioned. Every mapping carries a version so changes are traceable and old and new semantics can coexist.
Tuning parameters¶
- Semantic level of the invariant — exact-equal, transformed-equal, or within-tolerance per field. Looser invariants tolerate real heterogeneity but must be justified so they do not hide corruption.
- Loss disclosure granularity — a blanket "lossy" flag versus an enumerated list of what is lost. Enumeration costs effort but makes round-trip expectations precise.
- Default policy on reverse — whether an unmappable reverse value becomes a documented default, an error, or a preserved local value; defaults are convenient and dangerous.
- Notation — prose, a rule table, or an executable mapping DSL. Executable notation reduces spec-to-code drift but raises authoring cost.
When it helps, and when it misleads¶
Its strength is making meaning explicit and reviewable before code is written: the two-direction, loss-annotated table is what lets a team treat non-invertibility as designed information rather than a test failure to suppress, and it gives round-trip tests a truthful target.[n1]
Its failure mode is the specification that lies by omission — a forward map documented, the reverse left implicit, and the loss unstated — which invites the connector to fabricate a plausible reverse value and call the round trip successful. The classic misuse is generating both directions from one arrow and assuming they invert. The guarding discipline is to require every field to state its reverse behavior and its loss explicitly, and to reject "same as forward, inverted" as an answer.
How it implements the components¶
directional_transformation_pair— its core: forward and reverse mappings authored, reviewed, and versioned as two separate functions.information_loss_and_locality_boundary— every entry declares many-to-one collapse, precision loss, defaults, and local-only fields, so "successful round trip" means equivalence under declared loss.bidirectional_correspondence_invariant— each field states the relation that must hold (exact, transformed, or bounded), which is the semantic correctness target.
It does not implement correspondence_health_and_migration_control — that is its document twin the Mapping-Version Backfill and Rollback Plan, which governs how a change to these very mappings is rolled out; this spec defines what the mapping IS, not how to migrate it.
Related¶
- Instantiates: Bidirectional Consistency Mapping — supplies the canonical two-direction semantics the pair is built on.
- Sibling mechanisms: Mapping-Version Backfill and Rollback Plan · Field-Level Authority Matrix · Round-Trip Property-Test Suite · Bidirectional Change-Data-Capture Adapter
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Forward/Reverse Field-Mapping Specification operates as a non-executable information artifact that externalizes static or prospective structure because it records each directional mapping, loss, default, authority, and version.
Independent corroboration: The frozen evidence defines Forward/Reverse Field-Mapping Specification as 'Records each directional mapping, loss, default, authority, and version', 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: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Bidirectional field mappings, defaults, loss, and version rules are data-integration and software schema-engineering artifacts.
Related originating lineages:
- Library & Information Science — Metadata crosswalk practice materially contributes authority and equivalence documentation.
- Medicine & Healthcare — Health-data interoperability standards contribute rigorous handling of codes, absence semantics, and authoritative mappings.
Review resolution: Both reviewers agree that computer_science is primary. I retain library_information_science, medicine_healthcare only as formative origin lineage(s), without treating every later application as an origin. cross_disciplinary_synthesis is appropriate because the exact artifact combines contributions from multiple professional lineages. Reach is multi_domain as a separate applicability judgment: it does not widen or narrow the recorded provenance. Encyclopedia synthesis is false because the artifact is already established enough that encyclopedia-specific synthesis is not required. The secondary differences are reconciled with no unresolved primary-provenance ambiguity.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
The specification is deliberately inert. It defines meaning; the adapter that reads it and the migration plan that changes it are separate, so a mapping can be corrected without touching delivery machinery, and a rollout can be planned without reopening what the mapping means.
[n1] A canonical data model is a shared, system-neutral definition of meaning that each system maps to and from, so translation logic lives in one reviewable place instead of being duplicated pairwise. This specification is the two-direction, loss-annotated form of that idea for a single mapped pair. ↩