StediDOCS

Older JEDI Formats

There's a new JEDI format available - learn more about it here.

JEDI 1.0 is an older JSON representation of an EDI document. Normally, an EDI document is represented in X12 EDI Format and looks something like this.

ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*/*00801*123456789*1*T*:~
GS*SO*00*00*20210902*1200*987654321*X*008010~
ST*326*0000~
SE*2*0000~
GE*1*987654321~
IEA*1*123456789~

It's a compact format, well suited for sending over the wire, but it isn't convenient when you want to process it in code. Most programming languages have support for working with JSON, so it would be nice to have the same data in JSON format and that's what JEDI provides.

{
  "interchanges": [
    {
      "groups": [
        {
          "transaction_sets": [
            {
              "heading": {
                "0100_ST": {
                  "01": "326",
                  "02": "0000"
                },
                "1100_SE": {
                  "01": "2",
                  "02": "0000"
                }
              }
            }
          ],
          "GS": {
            "01": "SO",
            "02": "00",
            "03": "00",
            "04": "20210902",
            "05": "1200",
            "06": "987654321",
            "07": "X",
            "08": "008010"
          },
          "GE": {
            "01": "1",
            "02": "987654321"
          }
        }
      ],
      "delimiters": {
        "element": "*",
        "segment": "~",
        "sub_element": ":",
        "repetition": "/"
      },
      "ISA": {
        "10": "1200",
        "11": "/",
        "12": "00801",
        "13": "123456789",
        "14": "1",
        "15": "T",
        "16": ":",
        "01": "00",
        "02": "          ",
        "03": "00",
        "04": "          ",
        "05": "ZZ",
        "06": "               ",
        "07": "ZZ",
        "08": "               ",
        "09": "210902"
      },
      "IEA": {
        "01": "1",
        "02": "123456789"
      }
    }
  ]
}

Structure

The purpose of an EDI file is to exchange business documents: invoices, requisition orders, shipping instructions, you name it. Each such a document is a transaction set in EDI parlance.

An EDI file often contains multiple transaction sets and they don't all need to be of the same type. It's no problem, for example, to send invoices and requisition orders all in one go. However, when you receive such a file, it's convenient if you can tell which transaction sets are intended for the finance department and which should be sent to the warehouse. This is where functional groups can help out. You put all the invoices in one functional group and all the requistion orders in another, and now it's easy to route them within your organization.

It's even possible to put transaction sets intended for different organizations into one EDI file. In that case, you wrap them in an interchange.

So, an EDI file contains one or more interchanges, an interchange contains one or more functional groups, and a functional group contains one or more transaction sets. This same structure is reflected in JEDI.

{
  "interchanges": [{
    "groups": [{
      "transaction_sets": []
    }]
  }]
}

Segments

In EDI, all data is represented in the form of a segment. A segment starts with an identifier, which lets you know what type of segment you're dealing with. It's followed by a list of values. If you want to know what those values mean, you have to take the segment identifier and look it up. For example, the ST segment marks the start of a new transaction set and has three elements: identifier code, control number, and implementation convention reference. In that order.

In X12 EDI Format, a segment looks like this.

ST*810*1~

The elements in the segment are delimited with a * and the end of the segment is marked by a ~. The identifier ST marks this as the start of a transaction set. 810 is the code for an invoice. 1 is the number of this transaction set within the functional group. The third element for this segment is optional and it's omitted here.

In JEDI, the same segment would look like this.

"0100_ST": {
  "01": "810",
  "02": "1"
}

That seems clear enough for the most part, but where does the 0100_ come from?

A transaction set is based on a specification. The specification tells you which segments make up a transaction set. If you take a look at the specification for an invoice, you'll see that each segment has a sequence number. One type of segment can appear multiple times in a transaction set. For example, an invoice contains multiple REF segments. The sequence number helps to uniquely identify each segment. In X12 EDI Format, the sequence number is implicit based on the position of the segment in the transaction set, but JEDI makes the sequence number explicit by putting it in front of the segment identifier.

Transaction sets

Within a transaction set, segments are grouped into three sections: heading, detail, and summary. This is reflected in JEDI, where a transaction set has the following structure.

{
  "heading": {},
  "detail": {},
  "summary": {}
}

Not all sections have to be present. For example, the following invoice doesn't include details.

{
"heading": {
  "010_ST": {
    "01": "810",
    "02": "0000"
  },
  "020_BIG": {
    "01": "20210902",
    "02": "AB01010101"
  }
},
"summary": {
  "010_TDS": {
    "01": "999"
  },
  "080_SE": {
    "01": "4",
    "02": "0000"
  }
}

Loops

A transaction set can have a collection of segments that belong together and can occur multiple times. This is called a loop. For example, an invoice can have multiple items. In JEDI, that would look like this.

{
  "detail": {
    "0100_IT1": [
      {
        "0100_IT1": {
          "01": "PL123",
          "02": 3,
          "03": "H4",
          "04": 1250,
          "05": "ST"
        },
        "0200_CUR": {
          "01": "CY",
          "02": "NZL"
        }
      },
      {
        "0100_IT1": {
          "01": "PL897",
          "02": 1,
          "03": "H4",
          "04": 825,
          "05": "ST"
        },
        "0200_CUR": {
          "01": "CY",
          "02": "NZL"
        }
      },
      {
        "0100_IT1": {
          "01": "SQ555",
          "02": 10,
          "03": "4G",
          "04": 20,
          "05": "ST"
        },
        "0200_CUR": {
          "01": "CY",
          "02": "NZL"
        }
      }
    ]
  }
}

This loop contains three items. Note the following.

  • The key for the loop is the same as the segment identifier of the first item in the loop (0100_IT1 in the example above).
  • The items in the loop are contained in an array.
  • Each item is its own JSON object.

Repeated segments

Sometimes, a segment may be repeated even outside of a loop. For example, an invoice has a Note segment (NTE) that can be repeated, allowing a note with many lines. In X12 EDI Format, this segment simply appears many times.

NTE**This is a note~
NTE**With many a line~
NTE**A segment repeated~
NTE**Can store this just fine~

JEDI puts these repeated segments into an array, with one object per segment.

{
  "heading": {
    "0300_NTE": [
      {
        "02": "This is a note"
      },
      {
        "02": "With many a line"
      },
      {
        "02": "A segment repeated"
      },
      {
        "02": "Can store this just fine"
      }
    ]
  }
}

Repeated elements

Some elements can be repeated within their segment. For example, the last element of the Request Validation segment (AAA) can contain one or more error reason codes. In X12 EDI Format, that looks like this.

AAA*Y****NF/NR/TO~

The last element contains three values, delimited by a /. The delimiter for repeated elements is specified in the ISA header. In JEDI, the values are collected in an array.

"0300_AAA": [
  {
    "01": "Y",
    "05": [
      "NF",
      "NR",
      "TO"
    ]
  }
]

Composite elements

A single element can be made up of multiple values if it's a composite element. Where a repeated element has multiple values for the same field, a composite element is like a structure with its own fields. For example, the Provider Information segment (PRV) has a composite element Provider Specialty Information (CO35) and that element has three fields of its own. The values in a composite element are delimited by a :. The delimiter for composite elements is specified in the ISA header.

PRV*LA****ORT:HS:Y~

JEDI represents a composite element as an element nested in an element.

"2400_PRV": {
  "01": "LA",
  "05": {
    "01": "ORT",
    "02": "HS",
    "03": "Y"
  }
}

Delimiters

The X12 EDI Format uses delimiters to separate segments and elements. By default, segments are delimited by a ~ and elements by a *. Values in composite and repeated elements are delimited by whatever you specify in the ISA header. The JEDI format doesn't need these delimiters. Still, if you want to translate an EDI document from JEDI to X12 EDI Format, EDI Core has to add delimiters, so JEDI stores the delimiters in a required field called delimiters.

{
  "interchanges": {
    "delimiters": {
      "element": "*",
      "segment": "~",
      "sub_element": ":",
      "repetition": "/"
    },
    "groups": ...,
    "ISA": ...,
    "IEA": ...
  }
}