View the full OpenApi example here:
EDI Segment Identification
Each EDI segment is identified by its ID. All the information below is also applicable to EDI composite data elements.
Use the x-edination-segment-id OpenAPI extension to set the segment ID.
Use the x-edination-composite-id OpenAPI extension to set the composite data element ID.
EDI Segment Structure
The structure of each segment/composite element 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 data elements, their id's (the EDI codes to identify each composite or simple data element), the usage (mandatory or not) and the repetitions in the same position. Additionally, every simple data element has a data type and minimum/maximum length. A description is also available for some or all data elements but it is not essential.
The following concepts must be used to convert the depicted structure above into OpenAPI Schema object:
-
Position
The position of the data elements is inferred from the order in the schema definition. The top item (NM101) is in position 0, the next item (NM102) is in position 1, etc.
-
Usage
Use OpenAPI "required" attribute to mark all mandatory items.
-
Repetitions
All non-repeatable items are defined as properties of type "string" for simple data elements:
and a Reference object for composite types:
All repeatable items are defined as OpenAPI "array" where the item's type is "string" for simple data elements and a Reference object for composite elements.
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.