Writing an EDI Mapping Specification Logistics Teams Can Maintain

The analyst who built the carrier maps left eighteen months ago. What remains is a translator project, a partner PDF with handwritten notes, and a spreadsheet last saved before two partners changed versions. When a freight invoice suddenly posts at a hundred times its value, nobody can say whether the map, the partner or the spreadsheet is wrong, so the fix becomes an afternoon of reading map code line by line.

A maintained EDI mapping specification ends that. It records, for every element a partner sends, how your systems read it, what they do with it and what breaks if it is wrong, in rows that people can review, diff and test. With one in place, a map change starts from reviewed text instead of reverse-engineered code, new partners start from a known baseline and can show auditors why a freight charge or a stock movement posted the way it did.

• What this guide covers: the row structure of a field-level spec, readable transform rules, code list crosswalks, the freight, stock and GST consequences of key fields, and version control.
• What it adds: a sample spec row in YAML, a timestamped implied-decimal failure, a worked defect cost in US dollars and rupees, and a maintenance checklist.

Why a trading partner guide is not your mapping specification

A partner's implementation guide tells you what they send; your mapping specification tells you what your systems do with it. The two answer different questions, and treating the partner PDF as your spec leaves every transform, default and validation living only inside map code.

X12 defines a Type 3 technical report, or TR3, as a report that addresses the use of one or more transaction sets for one specific business purpose, and each one is specific to a single version of the standard. Retailers, carriers and 3PLs publish their own guides in the same spirit, narrowing the standard to the segments and codes they use. None of them can say which column in your WMS receives W01-02, or what happens when it carries a code you have never seen.

Our article on EDI 940 and 945 mapping and error handling works through one transaction pair and its error queues. This article is about the document behind every map, whatever the transaction: how to write it, who owns it and how to keep it true after the people who wrote it move on.

Columns every field-level mapping row should carry

One row per mapped element, with the same columns for every partner, is the structure that keeps a spec maintainable. Free-text paragraphs per segment read well once and then drift, because nobody can diff a paragraph against a map or tell which sentence a change touched.

• Element reference: transaction, segment, element and loop position, for example 856 HL-O, MAN-02.
• Standard attributes: X12 data type (ID, AN, Nn, R, DT or TM), minimum and maximum length, and the standard's requirement designator.
• Partner usage: whether this partner sends the element always, sometimes or never, copied from their guide with its version.
• Target field: system, table and column, with the target data type and precision.
• Transform and default: the rule in plain words plus a short expression, and whether a default is ever allowed.
• Validation and failure action: what is checked and whether a failure rejects the document, holds the line or raises a warning.
• Business effect: what goes wrong downstream if the element is wrong or missing.
• Test case and owner: the ID of at least one test that exercises the row, and the person accountable for it.

The sample below shows two rows in YAML, one for a carrier freight invoice charge and one for a pallet SSCC on a ship notice. YAML or CSV both work, as long as the file lives in version control and a reviewer can see exactly which attribute changed between two versions.

- row_id: 210-L3-05
  partner: CARRIER-XMPL          # fictional SCAC for illustration
  x12_release: "004010"
  element: L3-05 Charge
  x12_type: N2                   # two implied decimal places
  length: 1/12
  partner_usage: always
  source_sample: "148250"
  target: freight_invoice.total_charge DECIMAL(12,2)
  transform: value / 100        # "148250" becomes 1482.50
  default: never
  validation: digits only; result > 0; within 10% of rated amount
  on_fail: hold invoice in audit queue
  business_effect: payable and freight accrual amount
  test_cases: [TC-210-07, TC-210-08]
  owner: edi-analyst-carriers

- row_id: 856-MAN-02
  partner: RETAILER-DC-04
  element: MAN-02 Marks and Numbers (when MAN-01 = GM)
  x12_type: AN
  length: 1/48
  transform: keep last 18 digits after AI (00); store as text
  validation: 18 digits; GS1 mod-10 check digit over first 17
  on_fail: reject ship notice line
  business_effect: pallet receipt and putaway at the DC
  test_cases: [TC-856-12]
  owner: edi-analyst-retail

An EDI mapping specification row for an X12 210 L3-05 charge should record type N2, length 1 to 12, divide-by-100 transform, no default, a 10% tolerance against the rated amount and a linked test case. Rows missing a test case or owner should block map release, keeping production behaviour traceable to approved text.

Transform rules written so analysts can read them without the map

Write every transform so an analyst can predict the output from the input without opening the translator. "See map" or "standard logic" in a spec row is a promise that nobody will be able to check the behaviour after the developer leaves.

Numeric types cause the quietest damage. X12 numeric types such as N2 carry implied decimal places, so a transmitted 148250 means 1,482.50, while the decimal type R carries the decimal point in the value itself. A map that treats an N2 element as R reads the same characters as 148,250. Dates follow a similar trap: DTM-02 in 004010 is an eight-character CCYYMMDD date, and a partner sending six characters needs a written rule, not a guess about the century.

• Numbers: state the X12 type and the arithmetic, for example "N2: divide by 100; R: parse as written; reject commas".
• Dates and times: state the source format, the time zone assumed and the target type, including what an empty time element means.
• Identifiers as text: SSCCs, GTINs, GSTINs and PO numbers are stored as text so leading zeros survive; GS1 guidance makes the same point for SSCCs.
• Units of measure: name the crosswalk table used and the conversion factor source, never a factor typed into the map.
• Concatenation and splitting: show an input example and the exact output, including separators and trimming.

Readable rules also make partner conversations shorter. When a carrier disputes a short payment, the analyst can send the row, the sample value and the transform, and the carrier's own EDI team can confirm or correct it the same day. Unit conversion pitfalls in particular are covered in our guide to unit of measure conversion master data.

Code lists and crosswalks kept as separately versioned tables

Code values belong in lookup tables with their own version and effective date, never hard-coded inside the map. Partners tend to add codes more often than they change structure, and a table change can be reviewed and released in minutes without rebuilding a map.

Typical logistics crosswalks include partner unit-of-measure codes such as CA for case and EA for each, N1-01 entity qualifiers such as ST for ship-to, SF for ship-from and BT for bill-to, carrier SCACs, shipment status and reason codes, and partner location codes mapped to your own sites. Each table needs an owner who knows what the internal code means, which is usually master data rather than the EDI team.

• Effective dating: every crosswalk row carries valid-from and valid-to dates, so historical documents replay with the codes in force at the time.
• Partner scoping: the same partner code can mean different things for two partners, so the key is partner plus code, not code alone.
• Unmapped code handling: one documented action per table, normally reject with a named error, reviewed before any change to a default.
• Change review: a new code is approved by the owner of the internal list, then released with a minor version of the crosswalk.

Fields that change freight bills, stock balances and receipts

A small set of elements moves money and stock directly, and those rows deserve the strictest validation and the most test cases. Prioritise them by the size of the error they can cause, not by how often they appear in the partner guide.

On a 940 warehouse shipping order, W01 quantity and unit drive what is picked. On a 945 warehouse shipping advice, the W12 shipped quantity drives what the client is invoiced and what leaves stock. On an 856 ship notice, the SSCC in MAN-02 decides whether a pallet can be received by scan. On a 210 freight invoice, L3 weight and charge flow straight into freight audit and the month-end freight accrual.

1. Mon 18:05, deployment: map version 3.3.0 for carrier XMPL is deployed under change ticket CHG-4471, described as a refactor of 210 charge parsing. The spec row 210-L3-05 is not edited, and the regression run covers only the 214 status map.
2. Tue 02:10, first invoice: interchange control 000004812 arrives with L3-05 = 148250. The new parser treats the element as R and writes 148250.00 to freight payable staging record FPS-90311.
3. Tue 07:30, accrual: the nightly accrual job posts journal ACR-2211 for 37 such invoices, overstating freight accrual by about $4.4 million.
4. Wed 09:15, detection: the freight audit tolerance flags invoices more than ten times their rated amount and holds all 37; finance reverses ACR-2211.
5. Controlled version: with test case TC-210-07 linked to row 210-L3-05, the pipeline would have run it for any change touching 210 parsing, and the build would have failed on Monday at 18:00.

EDI freight invoice mapping must treat the X12 210 L3-05 charge as type N2, so a transmitted 148250 posts as $1,482.50. Linking that specification row to a regression test, and holding any invoice above ten times its rated amount in freight audit, stops a 100-fold accrual error before month-end close.

GST fields an Indian-facing map has to carry and validate

When a partner integration feeds Indian invoicing, transport or e-invoice systems, the spec must carry GST fields as validated, owned rows rather than free text. A wrong GSTIN or truncated HSN code is not an EDI warning; it produces a tax document that does not meet the rules.

• GSTIN: stored as a 15-character text field, validated for length and structure, and matched to the party master rather than typed per document.
• HSN code: under Notification No. 78/2020-Central Tax, from 1 April 2021 a tax invoice carries 4 HSN digits where prior-year turnover is up to ₹5 crore and 6 digits above that; the row validates digit count against the supplier's band.
• Place of supply and state codes: mapped through a crosswalk from partner location codes, because they decide whether integrated or central and state tax applies.
• E-invoice and e-way bill hand-off: where the mapped document feeds an IRN or e-way bill, the row names the downstream field it populates; our article on generating e-way bills from the e-invoice IRN covers that data flow.

The worked figures below compare the cost of one mapping defect in each market. Both are illustrative, but the pattern holds: the defect itself is one wrong attribute, and almost all of the cost is the clean-up that follows when nobody can trace the behaviour back to a reviewed specification row.

Version numbers, change logs and partner-specific branches

Number the spec, not just the map, and make every production map point to exactly one spec version. When those two drift apart, the specification becomes a historical document and analysts go back to reading code.

A three-part number works well. Increase the major number when the partner moves to a new X12 release or a new transaction set, the minor number when rows are added or behaviour changes, and the patch number for wording fixes that change no behaviour. X12 itself has published its standard on an annual release cycle since 2019, with 008030 as the 2022 version and 008040 as the 2023 version, and partners move between releases on their own timetable, so each spec version records the release it targets.

• One repository: spec rows, crosswalk tables, sample files and test cases live together, so one commit can show a row change and its new test.
• Partner branches sparingly: start each partner from a shared baseline for the transaction, and record deviations as overrides rather than copying the whole spec.
• Change log entries: each version lists the change request, rows touched, the reason, the tester and the deployment date.
• Rollback ready: the previous map build and spec version stay deployable until the new one has processed a full business cycle.

EDI mapping specification versions should follow MAJOR.MINOR.PATCH: major for a new X12 release such as 004010 to 005010, minor for changed behaviour, patch for wording. X12 has released its standard annually since 2019, so each spec version records the partner, release and linked test cases rerun before deployment.

Which mapping checks are hard validations and where AI drafts rows

Length, type, check-digit and code-list checks are arithmetic and must run in the translator on every document. Language models are useful for the slow drafting work around a spec, such as turning a partner PDF into candidate rows, but an analyst must review every row they propose before it reaches a map.

The boundary matters because a drafted row that looks plausible is the hardest error to catch. Require the analyst to record the partner guide page for every drafted row, and keep drafted rows in a separate status until a test case has run against a real partner sample file.

A maintenance routine for the spec owner and partner manager

A specification stays true only if someone checks it against production on a schedule. A quarterly review of each high-volume partner, plus a check on every partner guide update, keeps drift small enough to fix in an afternoon.

Testing the integration end to end, with ERP and WMS outcomes, is covered in our ERP and WMS integration test cases. Bringing a new partner live from this baseline, with test cycles and a cutover plan, is the subject of our EDI trading partner onboarding guide. The checklist below keeps the specification itself complete and current.

Track three numbers: rows without a linked test, documents failing on unmapped codes, and days between a partner guide update and the matching spec release. More EDI and integration guides sit in the logistics and supply chain library. If you need a mapping specification rebuilt from existing maps, or a partner onboarding baseline, tell us about your partners and transactions through the RFP page.