OpenAPI EDI Message

  View the full OpenApi example here:

EdiNation X12 837P OpenAPI example

EDI Message Identification

Each EDI message, or transaction set, is identified by the following three values:

  1. EDI Standard

    This could be X12, EDIFACT or other, denoting the particular EDI dialect. It is mandatory and allows transactions for different EDI standards to be batched together in the same OpenAPI definition.

    Use the x-edination-message-standard OpenAPI extension at the top level to set the standard. 

  2. EDI Version

    This is the edition and release of the transaction set, for example 004010 or D96A. It is optional given that no other transaction sets with the same ID will be used in the same OpenAPI definition, otherwise it is mandatory.

    Use the x-edination-message-version OpenAPI extension at the top level to set the version.

  3. Transaction Set ID

    This is the transaction set ID as specified by the standard, for example, 850 is the ID for purchase order in the X12 standard and ORDERS is the ID for purchase order in the EDIFACT standard. It is mandatory.

    Use the x-edination-message-id OpenAPI extension at the top level to set the ID.

EDI Message Structure

The structure of each transaction set is usually depicted in their implementation guidelines with schemas more or less similar to the one below:


The image is copyrighted by

The schema defines the positions (the order) of all segments and loops, their id's (the EDI codes to identify each segment and loop), the usage (mandatory or not) and the repetitions in the same position. A description is also available for some or all segments/loops but it is not essential.

The following concepts must be used to convert the depicted structure above into OpenAPI Schema object:

  1. Position

    The position of the segments, loops and data elements is inferred from the order in the schema definition. The top item (ST) is in position 0, the next item (BHT) is in position 1, etc.


    When the guideline shows two or more items to be in the same position like the two NM1 Loops above in position 0200, then a new object must be created to contain all the items in the same position.


    This new object must not contain any Extension objects and must only repeat once.


    The items in the same position can be repeatable though:

  2. Usage

    Use OpenAPI "required" attribute to mark all mandatory items. ST and SE segments don't need to be marked as required, the API internally marks them as required.

  3. Repetitions

    All non-repeatable items are defined as reference properties. 


    All repeatable items are defined as OpenAPI "array" where the item's type is a reference to the repeatable item.

    Use OpenAPI "array" "minItems" and "maxItems" attributes to define the repetitions range.


Use OpenAPI "description" attribute to pass in additional comments at each level of the EDI segment/composite element.

Was this article helpful?
0 out of 0 found this helpful