View the full OpenApi example here:
EDI Message Identification
Each EDI message, or transaction set, is identified by the following three values:
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.
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.
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 X12.org
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:
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:
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.
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.