X12 EDI Connector 2.7 - EDI Schema Language Reference - Mule 4
The Anypoint B2B Connectors use a YAML format called EDI Schema Language (ESL) to represent EDI schemas. Basic ESLs define the composition of EDI messages with structures, segments, composites, and elements. ESL supports the following Connectors:
-
Anypoint Connector for X12 EDI (X12 EDI Connector)
-
Anypoint Connector for EDIFACT (EDIFACT Connector)
-
Anypoint Connector for TRADACOMS (TRADACOMS Connector)
-
Anypoint Connector for HL7 (HL7 Connector)
Components of an ESL Document
The top-level definitions in an ESL document show:
-
the EDI standard
-
the version of that standard
-
an optional list of import ESLs
-
any combination structures, segments, composites, and element definitions.
The following example shows what these top-level definitions look like from an /x12/005010/850.esl schema:
form: X12
version: '005010'
imports: [ '/x12/005010/basedefs.esl' ]
structures:
- id: '850'
name: Purchase Order
class: PO
...There is an ESL for each X12 and EDIFACT version named basedefs.esl, providing the standard segment, composite, and element definitions. This example shows an 850 purchase order that imports these to reuse the definitions representing the purchase order structure.
Readability
YAML uses a combination of lists and sets of key-value pairs. The order of values is not important, as long as the required items are present. Quotes (such as single or double) are used around values that consist of digits but are meant to be interpreted as strings (otherwise the YAML parser treats the values as numbers). Indentation is used to show the nesting of lists.
The ESL structures shown here define all simple key-value pairs before any lists that are part of the same definition.
Structure Definitions
These represent X12 transaction sets or EDIFACT messages and are composed of key-value pairs for standard characteristics with lists of segments that comprise the actual structure. Segment lists are organized into heading, detail, and summary sections. These can be further refined into groups consisting of a potentially repeated sequence of segments.
This example shows a sample structure definition from the /x12/005010/850.esl schema:
- id: '850'
name: Purchase Order
class: PO
heading:
- { idRef: 'ST', position: '0100', usage: M }
- { idRef: 'BEG', position: '0200', usage: M }
- { idRef: 'CUR', position: '0400', usage: O }
- { idRef: 'REF', position: '0500', usage: O, count: '>1' }
- { idRef: 'PER', position: '0600', usage: O, count: 3 }
- { idRef: 'TAX', position: '0700', usage: O, count: '>1' }
- { idRef: 'FOB', position: '0800', usage: O, count: '>1' }
- { idRef: 'CTP', position: '0900', usage: O, count: '>1' }
- { idRef: 'PAM', position: '0950', usage: O, count: 10 }
- { idRef: 'CSH', position: '1100', usage: O, count: 5 }
- { idRef: 'TC2', position: '1150', usage: O, count: '>1' }
- groupId: 'SAC'
usage: O
count: 25
items:
- { idRef: 'SAC', position: '1200', usage: O }
- { idRef: 'CUR', position: '1250', usage: O }
- { idRef: 'ITD', position: '1300', usage: O, count: '>1' }
- { idRef: 'DIS', position: '1400', usage: O, count: 20 }
...The basic structure values are:
| Structure Key/Section | Description |
|---|---|
id |
Structure identifier |
name |
Structure name |
class |
A class of structure that is equivalent to an X12 functional group identifier. This is ignored in EDIFACT structure definitions. |
heading |
List of segments and groups within the heading section of the structure. |
detail |
List of segments and groups within the detail section of the structure. |
summary |
List of segments and groups within the heading section of the structure. |
The lists of segments for each section of the structure use the same form. Each item in the list is either a segment reference or a group definition. Segment references use a compact YAML syntax: the values for each are shown as comma-separated key-value pairs enclosed in curly braces.
The values are:
| Segment Property | Description |
|---|---|
idRef |
The referenced segment ID. |
position |
The segment position within the section. With the EDI convention these are numeric values that can include leading zeros, so these are quoted and handled as strings. |
usage |
Usage code definition:
|
count |
Maximum repetition count value that can be a number or the special value >1 . This means any number of repeats. A count value of 1 is used if not specified. |
Group definitions are shown in expanded form, with key-value pairs on separate lines. The values in a group definition are:
| Value | Description |
|---|---|
groupId |
The group identifier |
usage |
Usage code definition:
|
count |
Maximum repetition count value that can be a number or the special value >1 . This means any number of repeats. A count value of 1 is used if not specified. |
items |
List of segments and potentially nested groups that comprise the group. |
Segment Definitions
Segment definitions are comprised of certain key-value pairs for standard characteristics along with lists of values such as elements and composites that make up the actual segment. The following example shows a portion of a sample segment definition, from the /x12/005010/basedefs.esl schema
M is mandatory
O is Optional
- id: 'BAK'
name: Beginning Segment for Purchase Order Acknowledgment
values:
- { idRef: '353', usage: M }
- { idRef: '587', usage: M }
- { idRef: '324', usage: M }
- { idRef: '373', usage: M }
- { idRef: '328', usage: O }
- { idRef: '326', usage: O }Segment definition values are:
| Section | Description |
|---|---|
id |
segment identifier |
name |
segment name |
values |
list of elements and composites within the segment |
The values list references elements and composites by ID, and use a compact YAML syntax: the values for each are shown as comma-separated key-value pairs enclosed in curly braces.
| Section | Description |
|---|---|
idRef |
The referenced element or composite ID. |
position |
The value position within the segment starts at 1 and increases by 1 for each successive value. Generally not used. |
name |
The name of the value in the segment, by default the element or composite name is used. |
usage |
Usage code definition:
|
count |
Maximum repetition count value that can be a number or the special value >1 . This means any number of repeats. A count value of 1 is used if not specified. |
Composite Definitions
Composite definitions are very similar to segment definitions. They are composed of certain key-value pairs for standard characteristics along with lists of values such as elements and composites that make up the actual composite. This example shows a portion of a composite definition, from the /x12/005010/basedefs.esl schema.
- id: 'C022'
name: 'Health Care Code Information'
values:
- { idRef: '1270', usage: M }
- { idRef: '1271', usage: M }
- { idRef: '1250', usage: C }
- { idRef: '1251', usage: C }
- { idRef: '782', usage: O }Composite definition values are:
| Name | Description |
|---|---|
id |
composite identifier |
name |
composite name |
values |
list of elements and composites within the composite |
The values list references elements and composites by ID, and use a compact YAML syntax: the values for each are shown as comma-separated key-value pairs enclosed in curly braces.
| Name | Description |
|---|---|
idRef |
The referenced element or composite ID |
position |
The value position within the segment, starts at 1 and increases by 1 for each successive value. Generally not used. |
usage |
Usage code definition:
|
Element Definitions
Element definitions are simple with only basic key-value pairs for standard characteristics.
This example shows this from the /x12/005010/basedefs.esl schema:
elements:
- { id: '1', name: 'Route Code', type: AN, minLength: 1,
maxLength: 13 }
- { id: '100', name: 'Currency Code', type: ID, minLength: 3,
maxLength: 3 }
- { id: '1000', name: 'Service Characteristics Qualifier',
type: AN, minLength: 2, maxLength: 3 }Element definition values are:
| Name | Description |
|---|---|
id |
Element identifier |
name |
Element name |
type |
Value type code (Binary data type is not currently supported):
|
minLength |
Minimum number of significant characters in the value. |
maxLength |
Maximum number of significant characters in the value. |
Specify a Schema According to Your Implementation Convention
You can define your implementation convention with an Overlay Schema. Overlay schemas specify how to use implementation conventions with a particular trading partner to extend and customizes the standard. These are very similar in structure to complete schemas but instead of providing all the details of the schema structure they only list changes.
You create an overlay schema with the following process:
-
Create an overlay schema that imports the base schema you want to customize, for example,
X12 005010 850. -
Customize the overall structure for segment usage, positions, groups, and counts.
-
Customize segments, including usage and counts.
The following example shows a portion of a sample overlay schema that modifies the basic X12 005010 850 transaction set definition.
This example customizes the CUR segment and specifies that it is unused, thereby ensuring it is hidden from the mapping structures in Anypoint Studio.
form: X12
version: '005010'
imports: [ '/x12/005010/850.esl' ]
structures:
- idRef: '850'
name: Purchase Order
class: PO
heading:
- { idRef: 'CUR', position: '0400', usage: U }Structure Overlay
A structure overlay details modifications to the base schema definition of an X12 transaction set. Most often these modifications take the form of marking segments or groups in the base definition as unused, but any usage or repetition count change is allowed.
The modifications in this example specify that the CUR and PER segments of the standard 850 heading are not being used, along with the segments in the N9 loop.
- idRef: '850'
heading:
- { idRef: 'CUR', position: '0400', usage: U }
- { idRef: 'PER', position: '0600', usage: U }
- groupIdRef: 'N9_Loop'
position: '2950'
items:
- { idRef: 'DTM', position: '2970', usage: U }
- { idRef: 'PWK', position: '3050', usage: U }
- { idRef: 'EFI', position: '3080', usage: U }The key-value pairs at the structure level are:
| Key | Description |
|---|---|
idRef |
The ID for the transaction set being modified. |
name |
The transaction set name, if used. |
heading, detail, summary |
List of segment and group modifications within each section of the structure. If used, each is only used when there are modifications to that section. |
The lists of segment modifications for the different sections of the structure such as heading, detail, summary all use the same structure. Each item in the list is either a segment reference or a group definition. Segment references are shown using a compact YAML syntax where the values for each reference are given as comma-separated key-value pairs enclosed in curly braces.
| Key | Description |
|---|---|
idRef |
The referenced segment ID. Verified if provided, but otherwise ignored. The position value is used to uniquely identify segments within the section. |
position |
The segment position within the transaction set section. |
usage |
Usage code, |
count |
Maximum repetition count value, which may be a number or the special value |
Group overlays are shown in expanded form, with key-value pairs on separate lines.
| Key | Description |
|---|---|
groupIdRef |
The referenced group ID. Verified if provided, but otherwise ignored. The position value is used to uniquely identify a group within a section. |
position |
The segment position within the transaction set section. |
usage |
Usage code, |
count |
Maximum repetition count value that can be a number or the special value >1 . This means any number of repeats. The count value and a base definition value is used if a value is not specified. |
items |
List of segments and potentially nested loops making up the loop. |
Segment Overlays
A segment overlay delineates modifications to the base schema definition. These modifications can take the form of marking elements or composites in the base definition as unused. Any usage or repetition count change is allowed. The following example uses the compact form for segment modifications that only involve a truncation, while modifications that make changes to individual values are expressed in expanded form. As with all the other YAML examples, the two forms are actually equivalent and are used interchangeably.
segments:
- { idRef: AMT, trim: 3 }
- idRef: BEG
values:
- { position: 4, usage: U }
- { idRef: DTM, trim: 3 }
- idRef: ITD
values:
- { position: 4, usage: U }
- { position: 6, usage: U }| Segment overlays do not automatically apply to all uses of a segment, they are only effective for segments referenced within a structure overlay. The structure overlay doesn’t need to make any changes to the usage of the segment, but must reference the segment at the appropriate position(s) so that the segment overlay is used to modify the base definition. |
The key-value pairs in a segment overlay.
| Key | Description |
|---|---|
idRef |
Segment identifier. |
trim |
Trim position in segment, if used, all values from this point on are marked as unused. |
values |
List of individual value modifications. |
The values list references values in the segment by position. The key-value pairs for these references.
| Key | Description |
|---|---|
position |
The value position within the segment. |
name |
The name of the value in the segment, if used. The base definition value used if not specified. |
usage |
Usage code, |
count |
Maximum repetition count value, which may be any number or the special value |