The short answer
Version every field-mapping change with the old and new source meaning, target field, transformation, effective boundary, affected population, backfill decision, downstream consumers, and acceptance tests. Never overwrite the old mapping or apply a new meaning to historical rows without an explicit restatement decision.
Key takeaways
- Mapping changes alter semantics, not just code.
- Define whether history remains, converts, or restates.
- Reconcile every downstream consumer across the version boundary.
Describe the semantic change before implementation
Record the source field and version, target field, valid values, normalization, defaults, null behavior, time zone, identifier relationship, old rule, proposed rule, reason, examples, and domain owner. Identify whether the source meaning changed or the earlier mapping was defective.
A label match does not prove semantic equivalence. Use source documentation and domain evidence, especially for balances, statuses, dates, and permissions.
Choose one historical treatment explicitly
Do not let deployment time accidentally decide which rows use which rule.
| Treatment | When it fits | Evidence requirement | Primary risk |
|---|---|---|---|
| Prospective | Old records remain valid under old meaning | Effective event/time and dual-version reporting | Mixed population misunderstood |
| Targeted correction | Known affected subset was wrong | Population query, correction lineage, rejects | Subset incomplete |
| Full restatement | Historical outputs require one new meaning | Approved scope, frozen baseline, reconciliation | Released reports change |
| No data change | Display or downstream interpretation only | Consumer tests and version note | Hidden derived impact |
| Hold | Meaning or population is uncertain | Owner and research plan | Pressure creates silent default |
Accept the rule across all consumers
Test representative normal, null, boundary, invalid, and previously failing values. Compare record counts, control totals, rejects, reports, integrations, search, exports, and any automation that reads the target field.
Retain the old mapping, new mapping, approval, deployment identity, backfill batch, exceptions, and rollback path. Close only when the effective population and downstream interpretations are recoverable from evidence.
Operational checklist
Mark your progress, then save a working copy. Selections reset when you leave this page. A checked box is not an approval or evidence of completion.
☐
Old and proposed semantics documented
☐
Domain owner confirms meaning
☐
Affected population bounded
☐
Historical treatment approved
☐
Boundary and version stored
☐
Downstream consumers tested
☐
Backfill and rejects reconciled
0 of 7 marked
Edge cases
- The source vendor changes status values without notice: freeze observed versions and investigate.
- One consumer already transformed the old value: avoid applying the new rule twice.
- A mapping correction changes a released owner report: route the report correction separately.
Sources and references
Follow each source to check the underlying claim. Access checks and professional review are different steps.
Continue the workflow
PMS migration acceptance criteriaHistorical report comparability after a PMS migrationPMS post-cutover defect triageRevision history
2026-09-18
Initial Phase 4 operational article with a distinct evidence artifact, failure states, source limits, and AI-assisted technical review.