How to read X12 specifications

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.

001 cover

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:

002 bottom

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.

003 data 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.


2.1 Sections

Usually every transaction set contains 3 sections – Header, Details and Summary. I believe they are self-explanatory:

004 sections

in this sample segments ST and BSN belong to the Header section, and HL, TD1 and TD5 belong to the Details.


2.2 Loops

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).

008 loops

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):

009 loops in loops

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).

010 loops repeat

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.

011 loops notes

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:

012 loops notes

 


2.3 Segments

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).

005 segments

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.

006 pos

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

010 HL
020 LIN
030 SN1
040 SLN
050 PRF
...

But HL(O) implementation of this loop will be just

010 HL
050 PRF

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:

007 pos2

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:

013 segment req

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:

014 segment loop req

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”

015 segment max

2.3.5 Notes

There might be segment-related Notes and/or Comments, the same idea as loops’s notes/comments (see 2.2.2)

2.3.6 Usage

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”

016 segment usage

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).

016 segment no column title

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.

017 segment not used

 

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

030 loop details

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:

018 segment


4.1 Segment page header

It usually contains the same information as the one in the data structure table:

019 segment header

  • 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:

4.2.1 Ref

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.

020 element ID

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.

4.2.2 Id

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.

022 element req

See 4.2.11 for more details.

4.2.5 Type

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.

024 element type

4.2.6 Min/Max

Minimum/Maximum length of this element. Self explanatory.

025 element min max

4.2.7 Usage

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)

026 element usage

4.2.8 Description

There might be a free-form description.

023 element desc

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”.

028 element codes

Sometimes there are user notes about different qualifiers, explanation on their usage:

029 element codes comments

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. 

4.2.10 Semantics

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:

021 element semantics

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.

022 element req

 

4.2.12 Comments

A free form description about this segment usage.

027 element comments

 

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 🙂

Gennady Kim

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s