This article is about reading and understanding typical ANSI X12 specifications, generated with tools like SpecBuilder in PDF or MS Word format. Usually specifications are straight-forward, but there are some nuances you should be aware of.
An X12 specification is a particular implementation of X12 transaction, defined by a company to be used with its partners.
Prerequisites: you should be familiar with X12 components, such as transactions, loops/groups, segments and elements.
1. Cover Page
Often (but not always) it starts with a Cover page which contains X12 transaction set number (such as 850 for Purchase Order or 810 for Invoice), version, publication date, author, logo and some other things.
The most important information is Transaction Set number (856 on the picture above) and X12 version (4010). Also I usually check the publication date to make sure it is not too old – if it is from 1990s, I would probably ask if it is the latest version.
X12 version (release) is important. Since v4010 is the most used versions now, people often do not expect to see something like 3020 or 7010 – so check it just in case. And do not mix it up with the document version (1.0 on the picture above) – X12 version uses 4 digits like 4010, 2002, 3020 and so on.
Sometimes X12 version has a prefix of 00, like 004010 – it is still 4010, and you should use 4010.
“4010” is pronounced as “fourty-ten”, not “four thousand and ten” 🙂
If there is no Cover page, you can often find X12 version at the bottom of each page:
2. Data structure table
A typical X12 specification has a section which describes the data structure. It looks like a table and this is a very important part of document – it allows you to see the whole structure.
This data structure describes all the loops and segments used in this transaction, their position, number of repetitions, optionality and other things.
Also, and it is very important, this table defined the order of loops and segments in the transaction. I.e. if you see on the picture above that TD1 is placed before TD5, your data should contain TD1 first and then – TD5, not the opposite!
Let’s review the main components of this table.
Usually every transaction set contains 3 sections – Header, Details and Summary. I believe they are self-explanatory:
in this sample segments ST and BSN belong to the Header section, and HL, TD1 and TD5 belong to the Details.
Loops are groups of segments (see below) or other loops. Every loops contains at least one segment, it goes first in the loop and always mandatory (otherwise we won’t be able to recognize when the loop starts in many cases).
Loops are usually marked with bold font and grey background (see the picture).
Since loops might include segments or other loops, there is a special visual approach to show their content in specifications – loops has top, right and bottom borders which “encompass” its content (hope it is clear):
As you can see, loop HL includes loops N1 and another HL (which includes 3rd HL loop in its turn):
- Loop HL
- Loop N1
- Loop HL
- Loop HL
It is important to know how to read these “lines” and be able to understand nested structures.
Usually loops have just a few parameters – maximum number of repetition (mandatory) and notes/comments.
2.2.1 Maximum number of repetition (loop)
I hope it is clear – this is the maximum this loop can be repeated in the document (top-level loop) or in another loop (if it is a nested loop).
2.2.2 Notes/comments (loop)
Often there is a column for optional references to notes/comments. Notes describe the usage rules, while comments are more a free-form text.
C2/010L means “comment 2/010 for this loop” (a note would start with “N”), to find its content scroll down to the end of the page – you’ll see this:
Every row (except loops) describes a data segment, used in this transaction and always contains the segment ID and Name. In most cases it also contains other important characteristics (will be described below).
The picture above contains HL, TD1, TD5, REF, DTM, N1, N2, N3, N4, and HL segments (see column Id).
As I wrote above, the order is important – the segments should be placed in the same sequence as it is defined in this table.
2.3.1 Positions (Pos)
Positions (usually column “Pos”) are unique counters. They used for segments unambiguous identification – for example, if you have 2 REF segments, one at the header level and another at the details, they will have different X12 positions (let’s say 670 and 3220) so people can recognize which one is which one.
Positions are counters, usually the next position is +10 (or +100) to the previous one, so there might be things like 010, 020, 030 or 0100, 0200, 0300.
Since X12 specifications (in most cases) do not list segments/loops which are not used, you can see some “gaps” in between values. For example, the standard HL loop contains
But HL(O) implementation of this loop will be just
because 020, 030 and 040 are skipped.
Anyway, I wouldn’t say I’ve seen anybody using these positions. People prefer (and so do I) to use terms like “REF at the header” or paths like “PO1/REF” (meaning a “REF segment which belongs to PO1 loop”). In EDIFACT they use group numbers, like “Group 30” but it is a different story.
PS One the picture above you can see that there are duplicate positions, for example these 2 HLs share the same position of 010:
This is technically incorrect, the person who created this spec copied/pasted HL loops in 856 document (which is great if you know how X12 856 are organized) but forgot to recalculate positions (for example, SpecBuilder has a function for it). But as I mentioned above, positions are usually not used so it is not that important.
2.3.2 Segment Name and Id
These two are self-explanatory so I wouldn’t dwell on them.
2.3.3 Required/Optional (Req)
This column might contain 2 values – M (Mandatory) or O (Optional) and describe how the standard (!) defines this segment:
As you should know, first segment in the loop always mandatory, i.e. if we have an N1 loop then you cannot have N2 or N4 without N1. In the Data Structure table however you can see that sometimes first segment is marked as “O” (Optional). It means that the entire loop is optional – but if you use it, N1 is mandatory:
2.3.4 Max Use
The Max Use column defines the maximum number of repetitions per document or loop, similar to loops’ “Repeat” column (see 2.2.1).
First segment in every loop always has “1” in this column. “>1” means “Unlimited”
There might be segment-related Notes and/or Comments, the same idea as loops’s notes/comments (see 2.2.2)
This is an important column. Since every company usually adopts the standard for its requirements, they might want to make some segments mandatory (even if they are optional per standard). They cannot do the opposite though, i.e. they cannot mark a segment defined mandatory per standard as optional (if they do that it is not a good sign). Every segment mandatory per standard OR marked as mandatory by the author will have “Must use” in this column.
If it is optional and no other conditions are defined – it will be marked as “Used”
Another possible value here is “Recommended” or “Desirable”. It means this segment is optional, but the company finds it helpful to have this additional data in this document.
Sometimes there is no “Usage” title, just letters – “M” (mandatory), “O” (Optional) or “R” (Recommended)/”D” (Desired). Sometimes it could be just “M” for mandatory and nothing for the rest (which means they are optional).
This “Usage” column overwrites value defined in “Req” column (see 2.3.4). I.e. if something is marked as “O” in Req column but “Must use” in Usage – it means it is mandatory and the data without it will be rejected.
In very rare cases the specification might contain segments which are not used. They are marked as “Not used” and you should ignore them. As for me, it doesn’t make any sense to include such things in the specification – it creates noise and prevents you from seeing the structure clearly.
After the data structure table (see above), the specification starts describing segments and (in some rare cases – loops, but usually loops do not have any separate pages).
3. Loop details
As I wrote above, usually loops’ details are not described – it is considered that the data structure table is enough to understand the structure of the document and how loops/segments are organized. But sometimes you can see separate pages for every loop
Usually it carries a straight-forward information, hope it is clear.
4. Segment details
Usually every segment starts a separate page and looks like this:
4.1 Segment page header
It usually contains the same information as the one in the data structure table:
- Segment Id and Name for segment identification (2.3.2)
- Pos – position in the document, a unique counter (2.3.1)
- Required/Optional (Req) – segment optionality (2.3.3)
- Max – maximum number of repetitions (2.3.4)
- Loop – loop this segment belongs to, or “N/A” for the top-level segments
- Elements – number of elements used (it might contain 5 elements, but if only 2 are used then Elements will contain “2”)
- User Option (Usage) – Usage (2.3.6)
4.2 Segment content / Elements
Elements (and rare composite elements/sub elements) are organized as a table – Element Summary. It contains the following data:
This is Element reference. In X12 world element might be defined as segment name + element position. For example, 1st element in DTM segment might be identified as DTM01 (or DTM-01). It is a typical approach, and 99% of X12 developers use it.
Note: In EDIFACT world developers use element/sub-element IDs instead, like BEG/1225 or DTM/C507/2005. You should never use this in X12, because in X12 not only element ID, but also its position in segment define element’s role. I.e. there might be more than one element with the same IDs, but on different positions and with absolutely different meaning.
Element Id uniquely identifies its type. For example, elements with Id of 373 are always dates in CCYYMMDD format. Also, if the data type is ID (qualifier), there is a list of values this element might contain (with some rare exceptions when this list is not a part of X12 standard).
For example, on the picture above DTM01 has Id of 374, and DTM02 – of 373.
4.2.3 Element Name
Element Name contains… the name of element 🙂 But as I wrote above, sometimes there are more than just one element with the same ID, or you need more detailed information – in this case you should check if there is Semantics section with element usage explanation.
See 4.2.10 for more details.
4.2.4 Required/Optional/Conditional (Req)
Similar to 2.3.3, it is about element’s optionality. But there might be not only “M” (mandatory) or “O” (optional), but also “X” or “C” – conditional. It means that this element depends on the other elements the way it is described in Syntax Rules section.
For example, element DTM02 is described as conditional, and Syntax Rule #1 says that R020305 – “At least one of DTM02, DTM03 or DTM05 is required.“. Since there is no DTM03 or DTM05, DTM02 becomes mandatory (otherwise the data won’t match the Syntax Rules). This is very important, some developers think that if it is not “M” (mandatory) or Usage is just “Used” they can omit this value in the data – no, they should check the syntax rules.
See 4.2.11 for more details.
This is data type. Might be AN (alpha-numeric), DT (date), TM (time), ID (qualifier), R (real) or NX where X is one of 0, 1, 2, … – numeric with with implied decimal positions.
Minimum/Maximum length of this element. Self explanatory.
Similarly to 2.3.6, this parameter defines if the company which created this specification considers this element mandatory or desired and might be used to overwrite the original optionality defined by the standard (but one more time – optional element might be marked as mandatory, but not the opposite).
Might be “Must use”, “Used”, “Desired”/”Recommended” and in some cases “Not used” (should be ignored)
There might be a free-form description.
4.2.9 Code List Summary
This section is used for elements with the type of ID (qualifier) and contains the list of element the company supports. For example, if it sells eggs, their units of measure would be “dozen” or “each”, but not “meters” or “miles per hour”.
Sometimes there are user notes about different qualifiers, explanation on their usage:
Sometimes it says “All valid standard codes are used”. This is not a good sign, I haven’t seen a single company which really uses all of the codes from the standard.
This section explains the element usage. For example, segment TDS from X12 810 Invoice contains 4 elements with the same Id of 610 (Amount). To understand, why there are 4 elements with the same Id and how to use them you should check Semantics section:
4.2.11 Syntax Rules
As it was described above, this (optional) section contains all the rules applied to the elements in this segment. If data does not match any of them – such document will be rejected.
Rules are coded, here is the list of codes:
C – conditional
Dependence of the optionality of one element (s) on the existence of another (the first in the description):
|C0302 – If PO103 is present, then PO102 is required.C060504 – If PR106 is present, then PR105 and PR104 are required.|
P – paired of multiple
Dependence of the optionality of a group of elements (if at least one of the group is present, then the rest are required):
|P0607 – If either PO106 or PO107 is present, then the other is required.P040506 – If either AT904, AT905 or AT906 are present, then the others are required.|
L – list conditional
Dependence of three or more elements among themselves, when in the case of the existence of the first element in the description, at least one of the others is required:
|L13101112 – If PO413 is present, then at least one of PO410, PO411 or PO412 is required.|
R – required
At least one of the listed elements is obligatory:
|R1012 – At least one of PR110 or PR112 is required.R020607 – At least one of AT302, AT306 or AT307 is required.|
E – exclusion
Only one of the listed elements may be present:
|E0309 – Only one of PSD03 or PSD09 may be present.E020607 – Only one of AT302, AT306 or AT307 may be present.|
A free form description about this segment usage.
5. Data samples
Some specifications, maybe 3-5% of them, contain data samples with some explanation. I personally respect a lot such documents, especially for complex cases, like ASNs with multi-layer packaging.
However there might be discrepancies between the specification itself and the data samples (saw it many times). In such cases you should ask for explanation.
This information should be enough for you to start reading and (more important) understanding X12 specs 🙂