---
schema_version: "1"
id: ed0e34a7227f1aec8e76c5f50844433225a0996dc6e8bb5e130d7c0b7364d23a
title: X12 EDI Connector 2.17 - EDI Schema Language Reference
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/x12-edi-connector/2.17/x12-edi-schema-language-reference.md
canonical_url: https://docs.mulesoft.com/x12-edi-connector/2.17/x12-edi-schema-language-reference
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 7a4076e6802ed6a3f4be46a6f5f7ee55bf2d323e130befd6748a5c8ae85325ea
description: MuleSoft Documentation Site
release: "2.17"
latest: false
---
---
product: X12 EDI Connector
version: 2.17
---

# X12 EDI Connector 2.17 - EDI Schema Language Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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:

```yaml
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:

```yaml
- 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Structure Key/Section</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>id</p></div></div></td><td><div><div><p>Structure identifier</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>Structure name</p></div></div></td></tr><tr><td><div><div><p>class</p></div></div></td><td><div><div><p>A class of structure that is equivalent to an X12 functional group identifier. This is ignored in EDIFACT structure definitions.</p></div></div></td></tr><tr><td><div><div><p>heading</p></div></div></td><td><div><div><p>List of segments and groups within the heading section of the structure.</p></div></div></td></tr><tr><td><div><div><p>detail</p></div></div></td><td><div><div><p>List of segments and groups within the detail section of the structure.</p></div></div></td></tr><tr><td><div><div><p>summary</p></div></div></td><td><div><div><p>List of segments and groups within the heading section of the structure.</p></div></div></td></tr></tbody></table>

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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Segment Property</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>The referenced segment ID.</p></div></div></td></tr><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>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.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code definition:</p></div><div><ul><li><p><code>C</code> for Conditional</p></li><li><p><code>M</code> for Mandatory</p></li><li><p><code>O</code> for Optional</p></li><li><p><code>U</code> for Unused, the item should not appear at all in the data.</p></li><li><p><code>I</code> 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.</p></li></ul></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value that can be a number or the special value &gt;1 . This means any number of repeats. A count value of 1 is used if not specified.</p></div></div></td></tr></tbody></table>

Group definitions are shown in expanded form, with key-value pairs on separate lines. The values in
a group definition are:

<table><colgroup><col> <col></colgroup><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>groupId</p></div></div></td><td><div><div><p>The group identifier</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code definition:</p></div><div><ul><li><p><code>C</code> for Conditional</p></li><li><p><code>M</code> for Mandatory</p></li><li><p><code>O</code> for Optional</p></li><li><p><code>U</code> for Unused, the item should not appear at all in the data.</p></li><li><p><code>I</code> 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.</p></li></ul></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value that can be a number or the special value &gt;1 . This means any number of repeats. A count value of 1 is used if not specified.</p></div></div></td></tr><tr><td><div><div><p>items</p></div></div></td><td><div><div><p>List of segments and potentially nested groups that comprise the group.</p></div></div></td></tr></tbody></table>

## 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

```yaml
- 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Section</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>id</p></div></div></td><td><div><div><p>segment identifier</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>segment name</p></div></div></td></tr><tr><td><div><div><p>values</p></div></div></td><td><div><div><p>list of elements and composites within the segment</p></div></div></td></tr></tbody></table>

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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Section</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>The referenced element or composite ID.</p></div></div></td></tr><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>The value position within the segment starts at 1 and increases by 1 for each successive value. Generally not used.</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>The name of the value in the segment, by default the element or composite name is used.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code definition:</p></div><div><ul><li><p><code>C</code> for Conditional</p></li><li><p><code>M</code> for Mandatory</p></li><li><p><code>O</code> for Optional</p></li><li><p><code>U</code> for Unused, the item should not appear at all in the data.</p></li><li><p><code>I</code> 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.</p></li></ul></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value that can be a number or the special value &gt;1 . This means any number of repeats. A count value of 1 is used if not specified.</p></div></div></td></tr></tbody></table>

## 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`.

```yaml
- 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>id</p></div></div></td><td><div><div><p>composite identifier</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>composite name</p></div></div></td></tr><tr><td><div><div><p>values</p></div></div></td><td><div><div><p>list of elements and composites within the composite</p></div></div></td></tr></tbody></table>

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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>The referenced element or composite ID</p></div></div></td></tr><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>The value position within the segment, starts at 1 and increases by 1 for each successive value. Generally not used.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code definition:</p></div><div><ul><li><p><code>C</code> for Conditional</p></li><li><p><code>M</code> for Mandatory</p></li><li><p><code>O</code> for Optional</p></li><li><p><code>U</code> for Unused, the item should not appear at all in the data.</p></li><li><p><code>I</code> 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.</p></li></ul></div></div></td></tr></tbody></table>

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

```yaml
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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>id</p></div></div></td><td><div><div><p>Element identifier</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>Element name</p></div></div></td></tr><tr><td><div><div><p>type</p></div></div></td><td><div><div><p>Value type code (Binary data type is not currently supported):</p></div><div><ul><li><p><code>N</code> for an integer number</p></li><li><p><code>N0-N9</code> for a number with an implied decimal point at the indicated position (N0 is equivalent to N)</p></li><li><p><code>R</code> for a decimal number</p></li><li><p><code>ID</code> for an identifier</p></li><li><p><code>AN</code> for an alphanumeric string</p></li><li><p><code>DT</code> for a date</p></li><li><p><code>TM</code> for a time</p></li></ul></div></div></td></tr><tr><td><div><div><p>minLength</p></div></div></td><td><div><div><p>Minimum number of significant characters in the value.</p></div></div></td></tr><tr><td><div><div><p>maxLength</p></div></div></td><td><div><div><p>Maximum number of significant characters in the value.</p></div></div></td></tr></tbody></table>

## 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.

```yaml
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.

```yaml
- 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>The ID for the transaction set being modified.</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>The transaction set name, if used.</p></div></div></td></tr><tr><td><div><div><p>heading, detail, summary</p></div></div></td><td><div><div><p>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.</p></div></div></td></tr></tbody></table>

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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>The referenced segment ID. Verified if provided, but otherwise ignored. The position value is used to uniquely identify segments within the section.</p></div></div></td></tr><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>The segment position within the transaction set section.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code, <code>M</code> for Mandatory, <code>O</code> for Optional, <code>C</code> for Conditional, or <code>U</code> for Unused.</p></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value, which may be a number or the special value <code>&gt;1</code> meaning any number of repeats. The count value, if specified. Uses a base definition value if not specified.</p></div></div></td></tr></tbody></table>

Group overlays are shown in expanded form, with key-value pairs on separate lines.

<table><colgroup><col> <col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>groupIdRef</p></div></div></td><td><div><div><p>The referenced group ID. Verified if provided, but otherwise ignored. The position value is used to uniquely identify a group within a section.</p></div></div></td></tr><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>The segment position within the transaction set section.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code, <code>M</code> for Mandatory, <code>O</code> for Optional, <code>C</code> for Conditional, or <code>U</code> for Unused.</p></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value that can be a number or the special value &gt;1 . This means any number of repeats. The count value and a base definition value is used if a value is not specified.</p></div></div></td></tr><tr><td><div><div><p>items</p></div></div></td><td><div><div><p>List of segments and potentially nested loops making up the loop.</p></div></div></td></tr></tbody></table>

### 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.

```yaml
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 }
```

> [!NOTE] 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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>idRef</p></div></div></td><td><div><div><p>Segment identifier.</p></div></div></td></tr><tr><td><div><div><p>trim</p></div></div></td><td><div><div><p>Trim position in segment, if used, all values from this point on are marked as unused.</p></div></div></td></tr><tr><td><div><div><p>values</p></div></div></td><td><div><div><p>List of individual value modifications.</p></div></div></td></tr></tbody></table>

The values list references values in the segment by position. The key-value pairs for these
references.

<table><colgroup><col> <col></colgroup><thead><tr><th>Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>position</p></div></div></td><td><div><div><p>The value position within the segment.</p></div></div></td></tr><tr><td><div><div><p>name</p></div></div></td><td><div><div><p>The name of the value in the segment, if used. The base definition value used if not specified.</p></div></div></td></tr><tr><td><div><div><p>usage</p></div></div></td><td><div><div><p>Usage code, <code>M</code> for Mandatory, <code>O</code> for Optional, <code>C</code> for Conditional, or <code>U</code> for Unused.</p></div></div></td></tr><tr><td><div><div><p>count</p></div></div></td><td><div><div><p>Maximum repetition count value, which may be any number or the special value <code>&gt;1</code> meaning any number of repeats. The count value and a base definition value is used if a value is not specified.</p></div></div></td></tr></tbody></table>