The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


X12::Parser::Readme - understanding configuration (cf) files for X12::Parser

X12 transactions

ASC X12 standards define commonly used EDI transactions. The standards define a structure/format for exchange of EDI data.

Each transaction type is called a "transaction set". The smallest data item in a transaction is called an "element". Groups of related elements form a data segment. A data element separator separates the elements within a segment. A segment starts with a element which is called the segment ID, and ends with a segment terminator.

Logical groups of segments are called loops. There are some segments, which are used only to identify the beginning of a loop, these are called as control segments. A logical set of loops together form a "transaction set".

Similar transaction sets can be lumped together by enclosing them in data segments that are known as functional group headers and trailers. Functional groups are grouped together using interchange control headers and trailers.


Unlike XML/HTML parsers which relies on "<" and ">" tags to determine start and end of data blocks, X12 transactions rely on pre-defined values (segment IDs) to indicate start and end of related data blocks (loops). Developing a parser that would work for all X12 transactions poses a challenge in this respect, as each transaction has its own hierarchy of loops and start/end indicators.

This lead to the development of the X12 configuration file (cf) specification. The cf specification is created to specify details regarding the blocks/loops and start/end information in a simple format. Cf files can be created for the different transaction sets. (see section Building a cf file).

Now you can parse your X12 data file by invoking the X12::Parser specifying the cf file to use. This allows you to parse any X12 transaction data files just by building the cf file for that transaction type.

Cf file specification for X12::Parser

The cf file specifies any transaction in a hierarchical form. It identifies the loops and segments in a transaction. This information is used to parse the transaction file. The X12::Parser uses the X12::Parser::Cf module to read the cf file information before parsing a transaction file. Since the X12::Parser parses files based on the cf file it allows the user to parse different X12 transaction types just by using the appropriate cf file. The user can use the cf files that are bundled with this package or create new cf files. The cf provided with this package is for the HIPAA X12 Ver 4010 X12 transactions.

A cf file has two types of information: section and key=value pairs. A section contains information in key=value pairs.


Sections are identified by the square brackets ("[" and "]"). Section represents loops (or logical blocks) in a X12 transaction. The name of the loop or the block is specified in square brackets. The section [LOOPS] is mandatory in a configuration file. It consists only the names of the top level loops instead of key=value pairs. The X12::Parser::Cf cf file reader starts reading a cf file from the [LOOPS] section.


There are two predefined keys, which are recognized by the Cf file reader, namely: segment and loop. Segment key is used to define the segments that are part of the current section/loop. The loop key is used to define the sub-loops or the child loops for the current section/loop.

Note: The term section and loop is used interchangeably as a section in the cf file represents a loop in a X12 transaction.

Within a section, the first key=value pair represents the start of the loop. Each section/loop should have atleast one key=value pair for the X12::Parser to identify the loop in the X12 transaction file. Although the X12::Parser::Cf modules reads all the key=value pairs, the X12::Parser uses only the first key=value pair to identify the loops. The user may specify only the first key=value pairs for each loop.

Value itself consists of 6 fields separated by ':'. All values are not currently used.


When parsing a X12 transaction file, the values help the X12::Parser determine if a segment is the start of a loop.


value1, is the segment id for a segment in a X12 transaction. The first key=value pair within a section tells the X12::Parser how to identify the loop.

value2 and value3

In some cases, to identify a loop correctly it is not enough to look at the segment id, you need to look at the qualifier too.

value2 and value3 are used to specify this. value2 is used to specify the position on the segment that the X12::Parser should look for value3. value3 consists of a COMMA separated list of qualifiers.


value4 is a description of the segment. (value4 is not currently used by Parser).


value5 indicates if the segment is required or situational. (value5 is not currently used by Parser).


value6 indicates the allowable repeat count for the segment. (value6 is not currently used by Parser).

Currently values 1, 2 and 3 are used for parsing the transaction file. The others may be used in later versions of this package.


The X12::Parser::Cf module does not do validation of the Cf files. Since the goal of the X12::Parser module is to parse X12 files, the X12::Parser::Cf module is very minimal. The user should ensure that the cf files are appropriate.

Do not put extra spaces after [ ] sections. Do not have leading spaces for section name and key=value pairs. Lines with a leading #, are considered comments.

To validate if X12::Parser::Cf is reading the cf file correctly try something like

    use X12::Parser::Cf;

    my $cf = new X12::Parser::Cf;

This would print the loop hierarchy. You can validate this to ensure you have the correct structure.

Building a cf file

Lets take the case of building a cf file for Version 004010 of ANSI ASC X12.85, Health Care Claim Payment/Advice (835) transaction.

835 transaction

A 835 transaction structure would contain the following loops.

    |-- GS
        |-- ST
            |-- 1000A
            |-- 1000B
            |-- 2000
                |-- 2100
                |-- 2110
        |-- SE
    |-- GE

The above diagram shows the hierarchy of the loops. The data segments are not shown.

Sample cf file

     | ### start of the configuration file ###         |
 (1) | [LOOPS]                                         |
 (2) | ISA                                             |
     | IEA                                             |
     |                                                 |
     | #--- start of loop details ---#                 |
 (3) | [ISA]                                           |
 (4) | segment=ISA:::Interchange Control Header:R:1    |
 (5) | loop=GS                                         |
     |                                                 |
 (6) | [GS]                                            |
     | segment=GS:::Functional Group Header:R:1        |
     | loop=ST                                         |
     |                                                 |
 (7) | [ST]                                            |
     | segment=ST:1:835:Transaction Set Header:R:1     |
 (8) | loop=1000A                                      |
     | loop=1000B                                      |
     | loop=2000                                       |
     |                                                 |
     | [1000A]                                         |
 (9) | segment=N1:1:PR:Payer Identification:R:1        |
     |                                                 |
     | [1000B]                                         |
     | segment=N1:1:PE:Payee Identification:R:1        |
     |                                                 |
     | [2000]                                          |
     | segment=LX:::Header Number:S:1                  |
     | loop=2100                                       |
     | loop=2110                                       |
     |                                                 |
     | [2100]                                          |
     | segment=CLP:::Claim Payment Information:R:1     |
     |                                                 |
     | [2110]                                          |
     | segment=SVC:::Service Payment Information:S:1   |
     |                                                 |
     | [SE]                                            |
     | segment=SE:::Transaction Set Trailer:R:1        |
     |                                                 |
     | [GE]                                            |
     | segment=GE:::Functional Group Trailer:R:1       |
     |                                                 |
 (3) | [IEA]                                           |
     | segment=IEA:::Interchange Group Trailer:R:1     |
     | ### end of the configuration file ###           |


(1) LOOPS section is mandatory. Add the main loops under this section. Here we have added ISA and IEA loops (2). These are the top level loops. The ISA, IEA are interchange group header and trailer segments. But we treat them as a loop with one segment. And so are GS and GE functional group header and trailer record.

(3) Create a section for each of the loops mentioned under LOOPS.

(4) Use the segment key to specify how the X12::Parser should determine the start of the ISA loop. We will explain the fields better when we come to (9).

(5) Specify the sub-loops for ISA segment. In the above example GS is a sub loop for ISA. In there are more than one sub loops under ISA specify them too using the loop keyword. See (8) how three sub loops are specified.

(6) create a section for all loops specified under section ISA. Here it is GS. Use the section key and if there are any sub loops use the loop key to define their values.

Follow the same procedure to define all the loops and sub-loops.

(9) Here's a description of the fields of the values for segment.

       segment=N1:1:PR:Payer Identification:R:1
               |  |  |            |         | |
              (a)(b)(c)          (d)       (e)(f)

(a) specify the segment id here. Loop 1000A starts with N1 so specify N1 here.

(b) and (c), there are cases when the segment id does not uniquely identify a loop. For eg. Loop 1000A and 1000B both start with N1 segment id. When parsing a transaction file, if the parser encounters a segment starting with N1, it needs additional information to decide if it is Loop 1000A or 1000B. This is done by specifying the qualifier information in the fields (b) and (c).

(b) specify the position in the X12 segment where the parser should look for the qualifier specified in (c).

If there are multiple qualifiers which identify a loop, specify all of them in position (c) separated by a comma.

(d) This is the description of the segment. You may leave this blank. (*not used)

(e) Specify if the segment is required or situational. (*not used)

(f) Specify the number of times the segment can be repeated (*not used)

The fields (d) (e) and (f) are not used currently, but later releases may support these fields.


For details on Transaction sets refer to: National Electronic Data Interchange Transaction Set Implementation Guide. Implementation guides are available for all the Transaction sets.

X12::Parser, X12::Parser::Tree, X12::Parser::Cf

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.


Prasad Balan,


Copyright 2009 by Prasad Balan

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.