The Data Mapping Spec

Core banking migrations rarely fail because the new platform doesn't work. They fail, or run months late, because the data doesn't arrive the way the business expected. Balances that differ by a few cents across thousands of accounts. Loans that come across with the wrong interest type. Joint accounts that turn into two separate customers. Standing orders that stop running on the first weekend. Each problem traces back to a decision about data that was never written down, or was written down too late. 

The document that prevents these problems is the data mapping specification. In many programmes it is treated as a technical spreadsheet that IT fills in once the platform is chosen. In practice, it is one of the most important business documents in the migration. This article explains what a good mapping spec contains, the gaps it typically exposes and why it needs to be right early. 

What the mapping spec actually is 

A data mapping spec describes, for every piece of data the new core system needs, three things: 

Where it comes from: the source system, table and field, or a combination of several. 

How it is transformed: the rules that turn the old value into the new one, including code conversions, calculations, defaults and what happens when the source data is missing or invalid. 

How we prove it arrived correctly: the reconciliation checks that confirm the migrated data matches the source. 

The first two parts are what most teams expect. The third is the one most often missing, and it is the one that decides whether the business can sign off go-live with confidence. 

What a good entry looks like 

A single mapping entry, written for business and technical readers alike, might read: 

MAP-LN-017: Loan account, interest rate type 

Target: interest rate type on the loan account in the new core (FIXED or VARIABLE). 

Source: the rate code on the legacy loan master record, with values F (fixed), V (variable) and M (mixed: fixed for an initial period, then variable). 

Rule: F becomes FIXED. V becomes VARIABLE. M becomes FIXED, with the rate reset date set to the end of the fixed period, if that date falls on or after the migration date. Otherwise it becomes VARIABLE. 

Missing or unknown values: no default. The loan goes to the exceptions list for Lending Operations to resolve before migration. 

Reconciliation: the number of loans and the total outstanding principal per rate type must match the source exactly, to the cent. 

Owner: Head of Retail Lending (business decision), BA (specification), migration developer (implementation). 

Two details matter. The mixed-rate case is a business decision: someone in lending has to agree what a mixed loan becomes on the new platform. And there is no default for unknown values, because a default would let the migration run smoothly while quietly giving some customers the wrong product. 

The gaps a mapping spec exposes 

Writing the spec field by field forces questions that workshops and high-level designs skip. In core banking migrations, the same kinds of gaps appear again and again. 

The same name, a different meaning. "Balance" in the legacy system may include accrued interest; in the new core, it may not. "Customer" may mean a person in one system and a relationship in another. The mapping spec is where these definitions are compared and settled, before anyone writes code. 

Code lists that don't line up. Product, status and transaction codes rarely map one to one, and some legacy codes have been reused over the years. Each needs an explicit decision. 

Dates and calendars. Booking date versus value date, business-day conventions, and the dates that drive interest, fees and statements. A wrong date convention can shift interest calculations for every account in a product. 

Rounding and precision. Interest accruals held to more decimal places in one system than another, or rounded differently, produce small differences per account and large ones in total. The spec must state the precision and rounding rule, and reconciliation must check totals, not just samples. 

The customer and party model. Joint accounts, powers of attorney, guarantors and the same customer held under several identifiers. These mappings affect everything from statements to KYC records. 

History and closed products. How much history moves, and what must stay available for complaints, audits and retention. 

Items in flight. Standing orders, scheduled payments, loans in arrears, card disputes, cheques in clearing. These are the cases most likely to go wrong over the cut-over weekend, and they need their own mapping and reconciliation rules. 

Defaults that hide problems. Any rule of the form "if empty, use X" deserves a challenge. Sometimes a default is right. Often it hides data that needs cleaning in the source system. 

Reconciliation criteria: how the business signs off 

A migration can't be accepted because the programme "ran without errors". The business needs evidence that the data is complete and correct, defined in the spec entry by entry. The checks that make it convincing: 

Counts: the number of customers, accounts, loans and active standing orders per product, before and after. 

Control totals: the sum of balances, outstanding principal and accrued interest per product and currency, matched to the cent. 

Business rule checks: for example, every loan has a repayment schedule, the schedule adds up to the outstanding amount, and every joint account has all its holders. 

Field-level samples: a statistically meaningful sample of records compared field by field, with extra samples drawn from known edge cases. 

Agreed tolerances: for each check, either zero tolerance or an explicitly agreed tolerance, signed off by the business owner before the first rehearsal, not after the results are known. 

These criteria become the go/no-go conditions for each migration rehearsal and for the final cut-over. When they are agreed in advance, the go-live decision is a comparison of results with criteria. When they aren't, it becomes a negotiation under time pressure. 

Why it has to be right early 

The mapping spec is often scheduled late, after the target platform is configured. That timing causes much of the pain in migration programmes, because so much depends on it: 

Data cleansing takes months. Duplicate customers, missing identifiers and inconsistent codes must be fixed at the source, and the spec is what finds them. 

Rehearsals need a stable spec. If the rules are still changing, mock migrations produce noise instead of evidence. 

Product configuration depends on it. A legacy product found late to have no equivalent can mean redesigning products. 

Testing depends on it. Test cases, test data and reconciliation reports are all derived from the spec. 

The Java developer's review pass 

A mapping rule that reads well to the business can still be ambiguous to implement. That is why every domain of the spec gets a review from a senior migration developer before it is frozen. The review checks that each rule is: 

Deterministic: the same input always produces the same output, with no hidden dependency on the order records are processed in. 

Complete: every possible source value, including empty, invalid and unexpected ones, has a defined outcome. 

Precise: numeric precision and rounding are stated, and dates use explicit conventions and time zones. 

Traceable: every rule has an identifier that will appear in code, tests and reconciliation reports. 

In the implementation, the rule ID travels with the code, so anyone can trace a migrated value back to the decision behind it: 

 1 // MAP-LN-017: interest rate type (see mapping spec v2.3) 
 2 static RateType mapRateType(String legacyCode, LocalDate fixedEndDate, LocalDate migrationDate) { 
 3     return switch (legacyCode) { 
 4         case "F" -> RateType.FIXED; 
 5         case "V" -> RateType.VARIABLE; 
 6         case "M" -> (fixedEndDate != null && !fixedEndDate.isBefore(migrationDate)) 
 7                 ? RateType.FIXED 
 8                 : RateType.VARIABLE; 
 9         default -> throw new MappingException("MAP-LN-017", "Unknown rate code: " + legacyCode); 
10     }; 
11 } 

 The unknown-value case throws an exception rather than guessing, exactly as the spec says, and the record goes to the exceptions list. 

Governance that keeps the spec reliable 

A few practices keep a spec of thousands of fields trustworthy: 

Business data owners sign off each domain, such as customers, deposits, loans and payments, not the whole document at once. 

The spec is versioned, and every change after a freeze goes through change control with an impact assessment on code, tests and reconciliation. 

Exceptions have owners and deadlines. Records rejected by a rule are assigned to an operations team to correct at the source before the next rehearsal. 

Rehearsal results feed back into the spec. Every reconciliation break is traced to a rule, and the rule or the source data is corrected. 

Closing thought 

The data mapping spec is where a core banking migration becomes concrete: every product, balance, relationship and in-flight payment, with a decision about how it moves and a check that proves it did. Treated as a business document, owned by the people who know what the data means and reviewed by the people who will implement it, it turns migration risk into a list of known decisions. Started early, it gives the programme its best chance of a go-live weekend that customers never notice.