This product is in Developer Preview

EDI Guides

Getting started

EDI Guides is Stedi's product for authoring, managing, and sharing EDI guides with your trading partners. With EDI Guides, you can create implementation guides for thousands of X12 EDI transaction sets, using a simple and modern online editor. EDI Guides allow for versioning, publishing, and sharing of EDI guides with your trading partners. EDI Guides are saved in a structured format that can be validated against using Stedi's suite of EDI Core products. All mapping guides are automatically available through an API upon creation, so you can immediately start integrating your own or your business partner's mapping guides into your existing EDI workflows.

Using EDI Guides in Terminal

Creating a mapping guide

To create a mapping guide, navigate to the "EDI Guides" tab in Terminal. Click "Create EDI Guide", give your new guide a name, and select an X12 release that you would like your guide to be based on. Click "Create".

On the editing screen, you will see a long list of all the elements pertaining to the transaction set you've chosen. For each of these, you can specify rules on how your business deals with EDI documents that match this transaction set. You can mark fields as required, optional, or not used. You can edit their descriptions to add nuance and provide extra context to your trading partners. You can also add relational rules to elements, to establish formal relationships between elements, such as marking an element required conditional on the presence of some other element.

For more detail on creating an EDI Guide, see Further detail on EDI guide creation below.

Publishing an EDI Guide

To publish an EDI guide, click the "Publish" link at the top right of the EDI guide editor. A version is the same document as a EDI guide, but immutable - it is a snapshot of your EDI guide that cannot be edited. You can create as many versions of an EDI guide as you'd like. Creating a version allows you to start sharing it with your trading partners. To do so, when creating a version you can select one of the following visibility rules:

  • PRIVATE: this EDI guide version will remain private to your Stedi organization. Anybody within your organization will be able to see this EDI guide version, call it's API endpoint, and validate EDI payloads against it. No one outside of your organization will be able to do so.
  • UNLISTED: this EDI guide version will be publicly accessible without authentication. You will be given a public URI which you can send to your trading partners, which will allow them to read the EDI guide details in a friendly format. They will also be able to call a public, read-only API endpoint to access the EDI guide, as well as validate EDI payloads against it.
  • PUBLIC: same as UNLISTED, except the EDI guide version will also show up in public search and be discoverable on

Validating EDI against an EDI guide

While EDI Guides are very useful on their own as mapping guide documentation, their real power is in being able to validate EDI. In this way, your organization can ensure that EDI documents that travel in and out of your systems conform to the expected EDI guide. To learn how to do this, see the validation section of our EDI Core product.

Further detail on EDI Guide creation


  • EDI Guide: An EDI mapping guide in JSON format, optimized for programmatic validation. An EDI guide is driven by the standard it applies to (X12) and the SEF (Standard Exchange Format) that expresses validation rules over the standard.
  • Mapping guide: A document (usually a PDF or SEF) used by a business to outline its EDI requirements for a specific transaction set.
  • Release: X12 periodically published new releases. EDI Guides need to define the release of the standard it follows.
  • Transaction Set: the type of information being defined in the EDI guide, as defined by X12.
  • Segment: Intermediate data structure in a transaction set. It consists of a segment identifier + one or more elements. A segment definition includes a requirement designator, a repetition designator, a position designator, relational conditions and semantic notes. Single data segments can be repeated more than once. When 2 or more segments are repeated together, they form a loop.
  • Element: Data elements are the smallest named unit of information in an EDI guide. They have context within a segment and a transaction set. Each element definition has a name, a requirement designator, a type designator and a length designator.
  • Loop: Loops are groups of two or more semantically related segments. They are given in id, a requirement designator and a repetition designator.
  • Requirement designator: Applied to loops, segments and elements, the values allowed in mapping guides are Mandatory (M), Conditional (C), Optional (O) or Not used. Please take note that some values are forced by the rules of the X12 standard and cannot be edited.
    • Mandatory: Shall be used.
    • Conditional: Only applies to elements. It means a condition defines the requirement rules for the element.
    • Optional: At the option of the sending party.
    • Not used: Shall not be sent. It will be ignored by the receiving party.
  • Repetition designator: Data segments and Loops may have a maximum occurrence of one, a finite number greater than one, or an unlimited number. The notation for an unlimited number of occurrences is ">1". The ">1" construct is used only if a specific maximum number of occurrences cannot be determined or is unknown.
  • Length designator or Min/Max: Minimum or maximum length of an element. It is defined differently depending on type.
  • Element Type: the main types are as described below.
    • Numeric: coded Nn where N indicates that it is numeric and n indicates the number of decimal positions to the right of the implied decimal point. If n is 0, it need not appear in the EDI guide; N is equivalent to N0.
    • Decimal number: coded R, a decimal contains an explicit decimal point and is used for numeric values that have a varying number of decimals.
    • Identifier and Identifier 2 : respectively coded ID and ID2, an identifier always contains a unique value from a single, predefined list of values or code list.
    • String: coded AN, a string is a sequence of characters.
    • Date: coded DT, the format is generally specified in the notes.
    • Time: coded TM.
  • Code List: used for ID elements, dictionaries list all code values and their description. If you mean to restrict the values that can be used for a given element, enumerate the values you mean to support in your EDI guide. Not enumerating them implies all codes in the dictionary are accepted.
  • Condition: also called syntax rules or relational conditions, a condition defines the requirement conditions between elements of a same segment in the form of a code prefixed with a type.
  • Appendix a free-form text field that is provided for extra information pertinent to the EDI guide, which does not neatly fit anywhere else. Examples might be specific business rules, or sample EDI snippets.
(P) Paired or MultipleIf any of the elements are present, all are required.
(R) RequiredAt least one of the elements is required.
(E) ExclusionOnly one of the elements may be present.
(C) ConditionalIf one element is present, other elements are required.
(L) List ConditionalIf one element is present, at least one of the other elements is required.

Best practices

With so many details encoded, creating or reproducing mapping guides is a very detail-oriented task. Here are some suggested steps to get you going:

  1. To limit your EDI guide's surface area, use the requirement designator not used for each segment/element that isn't included in the mapping guide. Alternatively, set it to optional or mandatory for each segment/element that is included.
  2. Then, going back to the top, dive into each segment and loop definition.
    1. For a segment:
      1. start with the repetition designator.
      2. go though the requirement of each element first to clean up the segment before diving into the other details.
      3. validate Type and Min/Max.
      4. enumerate code lists where necessary.
      5. review semantics, add notes and examples to ensure clarity for the reader.
      6. finally review the conditions set in the segment: make sure to remove unnecessary ones or adjust the pre-populated ones.
    2. For a loop:
      1. start with the repetition designator.
      2. for each segment in the loop, follow the checklist above.
      3. If there are nested loops, follow the same logic recursively.
  3. Review the specific validation rules you would like to enforce.
    1. You might have logic that warrants defining the same segment or a loop more than once. If you need to define a loop more than once, consider adjusting the loop id.
    2. In some cases, you might want to define validation rules that span more than one segment. Be sure to add notes and examples to help the reader navigate your requirements.
  4. Finally, after thoroughly reviewing your EDI guide for accuracy, you can publish it. Publication options allow reaching the widest audience or keep it private. Published mapping guides are versioned to help track changes made overtime.

More information on loop requirements

Loops are defined by X12 as "A segment group [that] may be repeated in a transaction set instance, if permitted by the transaction set definition". Loops can only be identified in EDI files by the presence of the first segment listed in its definition. Because of this, the first segment of a loop is always mandatory.

You may notice that, on some PDF guides, the requirement for the first segment of a loop is set to optional. When that's the case, it actually conveys the requirement for the loop.

Given how confusing that may be, in Stedi's EDI Guides, the requirement for a loop is broken out on its own ; the requirement for the first segment of a loop is always set to mandatory and cannot be edited.

If you have feedback, suggestions or a feature requests, please let us know — we are always eager to hear from you.

Parallels between a PDF mapping guide and an EDI guide

EDI Guides Discovery EDI Guides Storage