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.
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.
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
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.
- 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
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.
Nindicates that it is numeric and
nindicates 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 2: respectively coded
ID2, an identifier always contains a unique value from a single, predefined list of values or code list.
AN, a string is a sequence of characters.
DT, the format is generally specified in the notes.
- Code List: used for
IDelements, 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.
|(P) Paired or Multiple||If any of the elements are present, all are required.|
|(R) Required||At least one of the elements is required.|
|(E) Exclusion||Only one of the elements may be present.|
|(C) Conditional||If one element is present, other elements are required.|
|(L) List Conditional||If one element is present, at least one of the other elements is required.|
With so many details encoded, creating or reproducing specifications is a very detail-oriented task. Here are some suggested steps to get you going:
- To limit your Specification's surface area, use the requirement designator
not usedfor each segment/element that isn't included in the mapping guide. Alternatively, set it to
mandatoryfor each segment/element that is included.
- Then, going back to the top, dive into each segment and loop definition.
- For a segment:
- start with the repetition designator.
- go though the requirement of each element first to clean up the segment before diving into the other details.
- enumerate code lists where necessary.
- review semantics, add notes and examples to ensure clarity for the reader.
- finally review the conditions set in the segment: make sure to remove unnecessary ones or adjust the pre-populated ones.
- For a loop:
- start with the repetition designator.
- for each segment in the loop, follow the checklist above.
- If there are nested loops, follow the same logic recursively.
- For a segment:
- Review the specific validation rules you would like to enforce.
- 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.
- 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.
- 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.
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.