The X12 file format, explained: envelopes, segments and elements
An X12 file looks like a wall of asterisks until you know its four layers. Select any line of this ship notice to see what it says, then learn to read your partner’s guide.
The outer envelope. It names the sender and receiver, the date and time, the X12 version, a control number, and whether this is a test or production file. It also declares the delimiters the rest of the file uses.
Sample data. Select a line to see its elements; positions follow the magenta tags used in the Weredi portal, for example BSN02.
Four layers, like envelopes inside envelopes
Every X12 file has the same structure. The business document is the innermost part; everything around it exists so that the right system receives it and can prove nothing was lost.
| Layer | Opens | Closes | What it holds |
|---|---|---|---|
| Interchange | ISA | IEA | One transmission between two partners |
| Functional group | GS | GE | Documents of the same kind, in one X12 version |
| Transaction set | ST | SE | One business document: an order, a ship notice, an invoice |
| Segment | its ID | ~ | One line of data, made of elements |
Reading a segment
A segment starts with its ID, two or three characters such as BSN, followed by its elements. Elements are named by position: BSN02 is the second element of BSN. An empty position is still counted, which is why you see runs like **.
The separators aren’t fixed by the standard; the file declares them. The character right after ISA separates elements, ISA16 gives the separator for components inside an element, and the character after ISA16 ends every segment. Asterisk, greater-than and tilde are common, not mandatory.
Dates, times and codes
Dates are digits with no punctuation: ISA09 uses a six-digit YYMMDD, most other dates use eight-digit CCYYMMDD. Many elements hold codes from a list rather than free text: HL03 is S, O or I, and ISA15 is P for production or T for test.
Control numbers and counts
Each opening segment carries a control number that its trailer repeats: ISA13 and IEA02, GS06 and GE02, ST02 and SE02. The trailers also count what they enclose. If a number or a count doesn’t match, the receiver rejects the file instead of guessing, and its 997 says so. More on that in 997 vs 855.
Loops and hierarchy
Some segments repeat as a group, called a loop: every PO1 line of an order, for instance. Ship notices go further and build a tree with HL segments, each pointing to its parent: shipment, then order, then pack, then item. The 856, line by line walks through that tree in detail.
Your partner’s guide decides the rest
X12 defines everything a document may contain. Each retailer publishes an implementation guide saying what it actually requires, and that guide is what your files are checked against. It has two kinds of pages:
- The segment list: which segments are mandatory or optional, in what order, how many times each may repeat, and how they nest into loops.
- The element details: for each element, whether it is required, its minimum and maximum length, its data type, and the codes the partner accepts.
The Weredi network publishes these guides for many retailers, segment by segment. For example, here is Canadian Tire’s 856 guide, and what the retailer expects overall on its EDI requirements page.
Check a file against a guide, free
Every published guide in the network comes with a validator. Paste or upload a document and it is checked against that partner’s rules: segment order and repetition, required elements, field lengths, data types and accepted codes. Nothing is stored, and you can load the partner’s own sample to see what a valid file looks like.
Worth knowing: the validator checks against the partner’s published guide only. It is not a full X12 conformance test, and passing it doesn’t guarantee the partner will accept the file.
The documents you’ll meet first
| Set | Document | Read more |
|---|---|---|
850 | Purchase order | How orders change: 850, 860, 865 |
855 | Purchase order acknowledgment | 997 vs 855 |
856 | Ship notice (ASN) | The 856, line by line |
810 | Invoice | Anatomy of an 810 |
997 | Functional acknowledgment | 997 vs 855 |
In Weredi, you rarely type X12
Your 855, 856 and 810 are built from the purchase order they answer, every field shows its X12 position, and each document is validated against your partner’s guide before it goes out. New to all of this? Start with getting started with EDI.
Questions
What is the difference between 4010 and 5010?
They are versions of the X12 standard, like editions of a dictionary. Segments and codes change a little between them. Your partner’s guide says which one to use, and GS08 in the file states it.
Can the separators be different from * and ~?
Yes. Each file declares its own in the ISA segment, and the validator reads the ones in your file. Check your partner’s guide in case it asks for specific characters.
Why does my file have a 997 rejection when the data looks right?
Often it is the envelope, not the data: a control number that doesn’t match its trailer, a wrong count in SE01, or a sender or receiver ID that differs from what the partner set up.
Keep reading
All articles →Read X12 without decoding it by hand
Weredi shows every element with its position and meaning, and builds your documents from the order, so you rarely type a segment at all.