X12 EDI Connector 2.6 - 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:

  • C for Conditional

  • M for Mandatory

  • O for Optional

  • U for Unused, the item should not appear at all in the data.

  • I for Ignored, this can be present in data, as in the case of the HL segments it must be present, but is not visible for the user in metadata.

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:

  • C for Conditional

  • M for Mandatory

  • O for Optional

  • U for Unused, the item should not appear at all in the data.

  • I for Ignored, this can be present in data, as in the case of the HL segments it must be present, but is not visible for the user in metadata.

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:

  • C for Conditional

  • M for Mandatory

  • O for Optional

  • U for Unused, the item should not appear at all in the data.

  • I for Ignored, this can be present in data, as in the case of the HL segments it must be present, but is not visible for the user in metadata.

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:

  • C for Conditional

  • M for Mandatory

  • O for Optional

  • U for Unused, the item should not appear at all in the data.

  • I for Ignored, this can be present in data, as in the case of the HL segments it must be present, but is not visible for the user in metadata.

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):

  • N for an integer number

  • N0-N9 for a number with an implied decimal point at the indicated position (N0 is equivalent to N)

  • R for a decimal number

  • ID for an identifier

  • AN for an alphanumeric string

  • DT for a date

  • TM for a time

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:

  1. Create an overlay schema that imports the base schema you want to customize, for example, X12 005010 850.

  2. Customize the overall structure for segment usage, positions, groups, and counts.

  3. 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, M for Mandatory, O for Optional, C for Conditional, or U for Unused.

count

Maximum repetition count value, which may be a number or the special value >1 meaning any number of repeats. The count value, if specified. Uses a base definition value if not specified.

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, M for Mandatory, O for Optional, C for Conditional, or U for Unused.

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, M for Mandatory, O for Optional, C for Conditional, or U for Unused.

count

Maximum repetition count value, which may be any number or the special value >1 meaning any number of repeats. The count value and a base definition value is used if a value is not specified.