Structure Definition Language

Structure definition language

The structure definition language uses XML to describe X12 message format. A message definition can be in a single file or in several. If the definition parser encounters an element (segment, composite, or table), which has not been previously defined, it tries to load the definition from the file with the same name and in the same directory. For example, if a loop mentions a segment named ‘ST’ and this segment is not defined, the parser will try to load and parse a file called ‘ST.xml’. This convention works for any name unless it conflicts with a Microsoft‘s device name, see Appendix B.

Each element in a structure definition (except ‘Definition’) must have an attribute called ‘name’. It is used to set/get respective content from Ruby. If an element‘s ‘name’ attribute cannot be a valid Ruby identifier (for example, ‘270’), the parser will prepend the name with ‘_’ (underscore). I.e., this expression is not valid:

@r.FG[1].270[1].ST.TransactionSetIdentifierCode

but his one is

@r.FG[1]._270[1].ST.TransactionSetIdentifierCode

Each XML file has to have a single root element, one of the following:

Definition

The ‘Definition’ element can have nested loops, segments, composites, and tables. It is used to provide ‘artificial’ root element for XML document when several definitions are in one physical file. For example, this is `misc/997single.xml’ (edited for size):

<Composite name="C030">
  <Field name="ElementPositionInSegment" type="long" required="n" min="1" max="2"/>
  <Field name="ComponentDataElementPositionInComposite" type="long" required="y" min="1" max="2"/>
  <Field name="RepeatingDataElementPosition" type="long" required="y" min="1" max="4"/>
</Composite>

<Segment name="AK1">
  <Field name="FunctionalIdentifierCode" min="2" max="2" validation="T479"/>
  <Field name="GroupControlNumber" type="long" min="1" max="9"/>
</Segment>

<Table name="T723">
  <Entry name="1" value="Mandatory data element missing"/>
  <Entry name="2" value="Conditional required data element missing."/>
  <!-- ... other entries -->
  <Entry name="13" value="Too Many Components"/>
</Table>

<!-- ... other segments or composites or tables -->

<Loop name="997">
  <Segment name="ST" min="1" max="1"/>
  <Segment name="AK1" min="1" max="1"/>
  <Loop name="L1000" max="999999" required="y">
    <Segment name="AK2" max="1" required="n"/>
    <Loop name="L1010" max="999999" required="n">
      <Segment name="AK3" max="1" required="n"/>
      <Segment name="AK4" max="99" required="n"/>
    </Loop>
    <Segment name="AK5" max="1" required="y"/>
  </Loop>
  <Segment name="AK9" max="1" required="y"/>
  <Segment name="SE"  max="1" required="y"/>
</Loop>

This element does not have any attributes and cannot be addressed from Ruby‘s API. Loop

The ‘Loop’ element is a main element to define either loops or whole messages. Loops can have nested segments and other loops.

Note, that a segment defined inside a loop takes precedence over previously defined segments. This is convenient if a special version of a segment is required. For example, this is a general definition of an ‘ST’ segment stored in a ‘ST.xml’ file:

If you want the X12 parser to look for a particular message type, say ‘997’, do this:

A loop can have the following attributes:

min - minimal number of repeats allowed, default is 0.
max - maximum number of repeats allowed, default is ‘inf’ (infinite).
required - if the loop is required (boolean), default is false. The true value implies min="1".
comment - ignored

Segment

Segments can only have nested fields. Attributes are as follows:

min - minimal number of repeats allowed, default is 0. Value min>0 implies required="y".
max - maximum number of repeats allowed, default is ‘inf’ (infinite).
required - if the segment is required (boolean), default is false. The true value implies min="1".
comment - ignored

All attributed except ‘name’ are ignored in standalone definitions outside any loop. Composite

Same as a segment.

Table

Tables can only have entries defined as name-value pairs. Order is not important. Only required attribute is ‘name’. Field

A field cannot have any nested elements, but its attributes are very important:

min - minimal number of characters allowed, default is 0. Value min>0 DOES NOT imply required="y" - the field can be missing, but may require a minimum length if present.
max - maximum number of characters allowed, default is ‘inf’ (infinite).
required - if the field is required (boolean), default is false. The true value DOES NOT imply min="1".
type - one of the ‘string’ (default), ‘integer’, ‘long’, or ‘double’. These abbreviations are also valid: ‘str’, ‘int’.
const - forces the field to have this value, if present.
validation - the name of a validation table, if any.
comment - ignored