Blog — June 22, 2022
Getting started with the X12 file format
Alex DeBrie
This post mentions Stedi’s EDI Core API. Converting EDI into JSON remains a key Stedi offering, however EDI Core API has been superseded by Stedi Core, an event-driven EDI system that allows you to configure integrations without being an EDI or development expert.
This document is the tl;dr of EDI. It won’t contain everything. It may not answer all your questions. It will only apply to X12. But it will save you a ton of time if you’re trying to decipher your first EDI document.
For this document, I’ll be using an 856 Ship Notice as an example. If you’re wondering what the heck an 856 Ship Notice is, you’re in the right place. Anyway, here’s the example.
ISA*00* *00* *ZZ*MYORG *ZZ*Interchange Rec*200831*2324*U*00501*100030537*0*P*>~
GS*SH*MYORG*Interchange Rec*20200831*2324*200030537*X*005010~
ST*856*300089443~
BSN*00*P1982123*20200831*2324*0001~
DTM*011*20200831*2324~
HL*1**S~
TD1*CTN*1****G*2*LB~
TD5**2*FDE*U********3D*3D*3D~
DTM*011*20200831~
N1*ST*SOO KIM*92*DROPSHIP CUSTOMER~
N3*26218 QUENTIN TURNPIKE~
N4*REANNAFORT*MS*51135~
HL*2*1*O~
PRF*1881225***20200831~
HL*3*2*P~
MAN*CP*037178019302492~
HL*4*3*I~
LIN*1*VC*11216.32*SK*RGR-11216.32~
SN1*1*1*EA~
PID*F****ALL TERRAIN ENTRY GUARD KIT 2020 JEEP WRANGLER J~
CTT*4~
SE*20*300089443~
GE*1*200030537~
IEA*1*100030537~
What is EDI?
EDI a structured way for businesses to send documents back and forth. It can be:
- a purchase order (“I want to buy this!”),
- an invoice (“Pay me for this!”),
- a ship notice (“I sent you this!”),
- or any of 300+ other transaction types.
Think of it as a JSON Schema to cover all possible business transactions and details, but before JSON, or XML, or the World Wide Web were invented.
You might hear people talk about X12 EDI. This is just a specific format of EDI. Another common one is EDIFACT. We’ll focus on X12 EDI here.
You might also hear of 5010 or 4010 . These are specific versions (formally known as releases) of EDI. Think of a versioned API, which might have small but breaking changes as you increase versions. EDI is an old standard and it required some changes over the years.
Structure
Segments, elements, and separators
When you first look at the 856 Ship Notice, you’ll see the following:
ISA*00* *00* *ZZ*MYORG *ZZ*Interchange Rec*200831*2324*U*00501*100030537*0*P*>~
GS*SH*MYORG*Interchange Rec*20200831*2324*200030537*X*005010~
ST*856*300089443~
BSN*00*P1982123*20200831*2324*0001~
DTM*011*20200831*2324~
…
This feels overwhelming. Don’t let it be.
Notice that the example of this particular EDI document is split into 5 lines. (The full document has 24 lines, as you can see at the start of the article.) Each line is called a segment. Each segment is broken into multiple elements.
Let’s start by breaking down what’s happening on line 1.
- It starts with
ISA. This is the segment name. We’ll often refer to the segment by its name. “Ohh, they’re missing an ABC segment”, or “That’s an invalid value in the XYZ segment”. This is the ISA segment. - There are a bunch of letters and numbers separated by
*. An asterisk serves as a separator between elements (technically, the fourth character—right afterISA—is the element separator, but it’s commonly a*). Elements are often referred to by their numerical index within a particular segment. For example, notice the200831near the end of the ISA segment. That is called ISA09 as it is the ninth element in the ISA segment. When you look at the definition of the segment, you’ll see that it refers to the Interchange Date in YYMMDD format. Thus,200831is August 31, 2020.
In the file we’ve looked at so far, each segment is on a different line. Sometimes you’ll get a file that’s all on one line. EDI documents will generally use
~ or a newline \n to distinguish between segments. (It’s technically the 105th byte in the ISA segment.) When reviewing a document, I find it much easier to split it into new lines based on the segment delimiter.Common segments
Now that we know the basics of segments, elements, and separators, let’s look at some common segments. Specifically, we’re going to look at
ISA, GS, and ST.ISA
We looked at the ISA segment in the previous section. This will always be the first line in an EDI document. It’s called an interchange and contains metadata that applies to the document as a whole. This includes the document’s date and time, a control number (similar to an auto-incrementing primary key), whether it’s a test document, and more.
Typically, there’s only one ISA segment in a document, but some organizations combine multiple EDI documents into one.
GS
The GS segment will always be next. It’s the functional group and it includes additional metadata about the transactions within the group. The most important value is the last one (GS08) which indicates the X12 version that is used by the document. In the example above, the value of this element is
005010. That indicates it’s using the 5010 version.The X12 spec allows multiple functional groups in a single document.
ST
The ST segment is for the actual transaction being sent. This is the star of the show and the reason we’re all here. It could be an invoice, a purchase order, or any other of the many transaction types.
Each functional group can have multiple transactions.
ST01 identifies the transaction type for the given transaction. In the example above, it says
856, which maps to a ship notice.Other common transaction types are:
- 214 Transportation Carrier Shipment Status Message
- 810 Invoice
- 850 Purchase Order
- 855 Purchase Order Acknowledgement
- 940 Warehouse Shipping Order
- 945 Warehouse Shipping Advice
- And a few hundred more…
Closing segments
Finally, for each of these key sections, there is a closing segment (formally a trailer segment) to indicate when they end. These closing segments include a checksum and a control number.
The code fragment above shows the last three lines of our ship notice example. The SE segment indicates the end of the ST block. SE01 refers to the number of segments within the ST block. The value
20 indicates there were 20 segments in that transaction. SE02 is a control number that matches the control number from the ST segment.Likewise, the GE segment indicates the end of the functional group, which started with GS. GE01 states how many transactions were included within the functional group, and GE02 is a control number for the group. Same thing with IEA which closes the ISA block.
Implementation guides
The X12 spec is expansive, and most companies don’t need all of it. Accordingly, companies will limit what they support. The terms may be dictated and standardized by the trading partner with the most market power, or it may be by mutual agreement between the two trading partners.
As a result, you may get an implementation guide indicating what is supported by a your trading partner. We’ll take a look at an example for a mapping guide for an 856 Ship Notice. There are two kinds of pages here: the overview page, and the segment detail page.
Overview
Another look at the example document shows multiple iterations of the HL loop.
Details
The overview usually doesn’t take up more than a page or two. The rest of the implementation guide is made up of segment detail pages. Here’s one for the PRF segment.
At times, an element will accept a small number of codes that map to specific values, similar to an enum. You can see an example of that on the details page for DTM.
Transforming EDI
So far, we’ve looked at a raw EDI document and you may have noticed that the format is hard to use with your favorite programming language. It would take a lot of string parsing, array indexing, and other tedium. Stedi offers an EDI parser, converter, and validator called EDI Core.
We can take our EDI example and give it to EDI Core. EDI Core will return a JSON representation of the EDI that we call JEDI.
{
"interchanges": [
{
"interchange_control_header_ISA": {
"authorization_information_qualifier_01": "no_authorization_information_present_no_meaningful_information_in_i02_00",
"authorization_information_02": "",
"security_information_qualifier_03": "no_security_information_present_no_meaningful_information_in_i04_00",
"security_information_04": "",
"interchange_id_qualifier_05": "mutually_defined_ZZ",
"interchange_sender_id_06": "MYORG",
"interchange_id_qualifier_07": "mutually_defined_ZZ",
"interchange_receiver_id_08": "Interchange Rec",
"interchange_date_09": "200831",
"interchange_time_10": "2324",
"repetition_separator_11": "U",
"interchange_control_version_number_12": "00501",
"interchange_control_number_13": "100030537",
"acknowledgment_requested_14": "no_interchange_acknowledgment_requested_0",
"interchange_usage_indicator_15": "production_data_P",
"component_element_separator_16": ">"
},
"groups": [
{
"functional_group_header_GS": {
"functional_identifier_code_01": "ship_notice_manifest_856_SH",
"application_senders_code_02": "MYORG",
"application_receivers_code_03": "Interchange Rec",
"date_04": "20200831",
"time_05": "2324",
"group_control_number_06": "200030537",
"responsible_agency_code_07": "accredited_standards_committee_x12_X",
"version_release_industry_identifier_code_08": "005010"
},
"transaction_sets": [
{
"set": "856",
"heading": {
"transaction_set_header_ST": {
"transaction_set_identifier_code_01": "856",
"transaction_set_control_number_02": "300089443"
},
"beginning_segment_for_ship_notice_BSN": {
"transaction_set_purpose_code_01": "original_00",
"shipment_identification_02": "P1982123",
"date_03": "20200831",
"time_04": "2324",
"hierarchical_structure_code_05": "shipment_order_packaging_item_0001"
},
"date_time_reference_DTM": [
{
"date_time_qualifier_01": "shipped_011",
"date_02": "20200831",
"time_03": "2324"
}
]
},
"detail": {
"hierarchical_level_HL_loop": [
{
"hierarchical_level_HL": {
"hierarchical_id_number_01": "1",
"hierarchical_level_code_03": "shipment_S"
},
"carrier_details_quantity_and_weight_TD1": [
{
"packaging_code_01": "CTN",
"lading_quantity_02": "1",
"weight_qualifier_06": "gross_weight_G",
"weight_07": "2",
"unit_or_basis_for_measurement_code_08": "pound_LB"
}
],
"carrier_details_routing_sequence_transit_time_TD5": [
{
"identification_code_qualifier_02": "standard_carrier_alpha_code_scac_2",
"identification_code_03": "FDE",
"transportation_method_type_code_04": "private_parcel_service_U",
"service_level_code_12": "three_day_service_3D",
"service_level_code_13": "three_day_service_3D",
"service_level_code_14": "three_day_service_3D"
}
],
"date_time_reference_DTM": [
{
"date_time_qualifier_01": "shipped_011",
"date_02": "20200831"
}
],
"party_identification_N1_loop": [
{
"party_identification_N1": {
"entity_identifier_code_01": "ship_to_ST",
"name_02": "SOO KIM",
"identification_code_qualifier_03": "assigned_by_buyer_or_buyers_agent_92",
"identification_code_04": "DROPSHIP CUSTOMER"
},
"party_location_N3": [
{
"address_information_01": "26218 QUENTIN TURNPIKE"
}
],
"geographic_location_N4": {
"city_name_01": "REANNAFORT",
"state_or_province_code_02": "MS",
"postal_code_03": "51135"
}
}
]
},
{
"hierarchical_level_HL": {
"hierarchical_id_number_01": "2",
"hierarchical_parent_id_number_02": "1",
"hierarchical_level_code_03": "order_O"
},
"purchase_order_reference_PRF": {
"purchase_order_number_01": "1881225",
"date_04": "20200831"
}
},
{
"hierarchical_level_HL": {
"hierarchical_id_number_01": "3",
"hierarchical_parent_id_number_02": "2",
"hierarchical_level_code_03": "pack_P"
},
"marks_and_numbers_information_MAN": [
{
"marks_and_numbers_qualifier_01": "carrier_assigned_package_id_number_CP",
"marks_and_numbers_02": "037178019302492"
}
]
},
{
"hierarchical_level_HL": {
"hierarchical_id_number_01": "4",
"hierarchical_parent_id_number_02": "3",
"hierarchical_level_code_03": "item_I"
},
"item_identification_LIN": {
"assigned_identification_01": "1",
"product_service_id_qualifier_02": "vendors_sellers_catalog_number_VC",
"product_service_id_03": "11216.32",
"product_service_id_qualifier_04": "stock_keeping_unit_sku_SK",
"product_service_id_05": "RGR-11216.32"
},
"item_detail_shipment_SN1": {
"assigned_identification_01": "1",
"number_of_units_shipped_02": "1",
"unit_or_basis_for_measurement_code_03": "each_EA"
},
"product_item_description_PID": [
{
"item_description_type_01": "free_form_F",
"description_05": "ALL TERRAIN ENTRY GUARD KIT 2020 JEEP WRANGLER J"
}
]
}
]
},
"summary": {
"transaction_totals_CTT": {
"number_of_line_items_01": "4"
},
"transaction_set_trailer_SE": {
"number_of_included_segments_01": "20",
"transaction_set_control_number_02": "300089443"
}
}
}
],
"functional_group_trailer_GE": {
"number_of_transaction_sets_included_01": "1",
"group_control_number_02": "200030537"
},
"release": "005010"
}
],
"interchange_control_trailer_IEA": {
"number_of_included_functional_groups_01": "1",
"interchange_control_number_02": "100030537"
},
"delimiters": {
"element": "*",
"segment": "~",
"sub_element": ">"
}
}
],
"__version": "jedi@2.0"
}
This is more verbose, but it’s much easier to deal with from code. You can see the EDI and the JSON side-by-side by using the Inspector. It’ll show an explanation of each segment, too.
Getting started
This is certainly not all you need to know, but it’s enough to get you started. Don’t forget to check out our blog for more information on working with EDI.
Featured
EDI Reference
The ultimate EDI resource
EDI Reference provides users with documentation on all transaction sets, segments, and elements of every X12 release, and all message types, segments and elements of every EDIFACT version.
EDI Inspector
Human-readable EDI
EDI can be tough to look at, so Inspector turns EDI into a format that is readable by humans. Quickly visualize and debug any X12 or EDIFACT document. Share EDI files easily with trading partners.
Share
Subscribe
Get blog posts delivered to your inbox.