StediDOCS
GuidesAPI Reference
This product is in Developer Preview

Specifications

Getting started

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

Using Specifications in Terminal

Creating a specification

To create a specification, navigate to the "Specifications" tab in Terminal. Click "Create specification", give your new spec a name, and select an X12 release that you would like your spec 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 a specification, see Further detail on specification creation below.

Publishing a specification

To publish a specification, click the "Publish" link at the top right of the specification editor. A version is the same document as a specification, but immutable - it is a snapshot of your specification that cannot be edited. You can create as many versions of a specification 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 specification version will remain private to your Stedi organization. Anybody within your organization will be able to see this specification 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 specification 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 specification details in a friendly format. They will also be able to call a public, read-only API endpoint to access the specification, as well as validate EDI payloads against it.
  • PUBLIC: same as UNLISTED, except the specification version will also show up in public search and be discoverable on edi.stedi.com

Validating EDI against a specification

While specifications 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 specification. To learn how to do this, see the validation section of our EDI Core product.

Further detail on specification creation

Terminology

  • Specification: An EDI mapping guide in JSON format, optimized for programmatic validation. A specification 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. Specifications need to define the release of the standard it follows.
  • Transaction Set: the type of information being defined in the specification, 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 specification. 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 specifications 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 specification; 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 specification. 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 specification, which does not neatly fit anywhere else. Examples might be specific business rules, or sample EDI snippets.
TypeDescription
(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 specifications is a very detail-oriented task. Here are some suggested steps to get you going:

  1. To limit your Specification'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 specification for accuracy, you can publish it. Publication options allow reaching the widest audience or keep it private. Published specifications 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 Specifications, 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 a specification

EDI Guides Storage EDI Guides Discovery

Getting startedUsing Specifications in TerminalCreating a specificationPublishing a specificationValidating EDI against a specificationFurther detail on specification creationTerminologyBest practicesMore information on loop requirementsParallels between a PDF mapping guide and a specification