Skip to main content

X12 Schemas and Available Tools

This page provides an overview of the InterSystems IRIS® data platform tools that you can use to work with X12 schemas and documents.

Using the X12 Schema Structures Page

The Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page enables you to import and view X12 schema specifications.

For general information on using this page, see Using the Schema Structures Page

To determine the schema structures, InterSystems IRIS extracts details from the .SETS, .SEGS, .COMS, .ELMS, and .CODES sections of the SEF file that was imported to define the structure of this X12 document. The description of a document is extracted from the .INI section of the SEF file that defines this X12 schema; an example is Healthcare Claim Status Request.

Loading X12 Schemas into InterSystems IRIS

To load an X12 schema into InterSystems IRIS from the Schema Structures page, click Import and select your file. You can load either SEF or XSD files.

For suggestions on where to find SEF files (X12 schemas) to import, see Standard Exchange Format (SEF) Files.

Loading SEF Files Programmatically

To load X12 schema files programmatically:

  1. Start a Terminal session.

  2. Change to an interoperability-enabled namespace and issue the following command:

    Do ##class(EnsLib.EDI.SEF.Compiler).Import(filename)

    Where filename is the full pathname of the schema file.

    This command imports the data from the schema file and make it available as a schema definition within InterSystems IRIS.

  3. InterSystems IRIS creates a name for the new schema category from the first piece of the first line in the .INI section of the SEF file. For example, in 837_X097.SEF you might see this line:

    .INI 837_X098,,004 010 X098,X,X12-4010,Healthcare Claim: Professional

    The extracted schema category would have this name:


    Due to the schema naming convention, if you want to edit a schema file to customize it, InterSystems suggests you first change the text in the schema file that provides its category name, so that you can distinguish your version from any other schema file that you also import into InterSystems IRIS.

  4. A schema file may contain syntax errors. If so, InterSystems IRIS issues an error message and identifies the location of the error in the schema file.

Viewing a Document Structure

To view the internal organization of a document structure, select its name from the DocType Structures tab on the Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page. InterSystems IRIS displays the segment structure of the document using the system of visual cues explained below. The following example shows the HIPAA_4010:820 document structure on this page. On the Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page, select HIPAA_4010 in the left part of the page and select 820 in the right part. This displays the X12 Document Structure page.

Structure of the HIPAA_4010:820 document, which includes various loops


  • Segments are listed in blue text and link to the relevant segment structure page.

  • Loops are listed in black text.

  • The segments that comprise the document structure are listed in sequential order, from left to right and top to bottom.


    In accordance with the X12 standard, permitted repetitions of a segment or subloop type may appear in any order prior to the next segment or subloop type in a document. For example, if a schema specifies that eight REF segments must appear prior to a CRC segment, the REF segments may appear in any order. However, they may not be interspersed with other segment types.

  • The name of each document segment is displayed: BPR, NM1, DTM, etc. This name indicates the type of segment that exists at this location in the X12 document structure.

  • Green dotted lines enclose segments that are optional.

  • Brown solid lines enclose segments that, if present, may repeat several times.

  • Yellow solid lines enclose segments that are part of a group.

  • A segment may be both repeating and optional (see segment NM1 above).

  • When you are viewing a segment diagram, if you hover the cursor over a three-letter segment name, a tooltip displays the syntax for referring to this segment in a virtual property path.

Raw Definition

To see the document structure in a raw text format, click Show Raw Definition Text. The raw definition of the HIPAA_4010:820 document structure is as follows:

Raw definition of a HIPAA_4010:820 document, which includes abbreviations, tildes, curly brackets, and square brackets to den


Loops in X12 can have custom names. Note in the above raw definition sample for HIPAA_4010:820 that loop titles directly follow open bracket characters “[,{,(” unlike segment names, which are separated from bracket characters by a tilde “~”. To use a custom loop name, type in your custom name in the place of the default loop name within the schema file prior to importing the schema into InterSystems IRIS.

Legacy Document Structure

You can view the old document structure viewer for schemas by clicking Go to Validation Structure. The legacy document structure also provides some information that is not available in the default document structure viewer. For example, the legacy document structure can provide code tables, the number of loop repetitions allowed, and syntax notes.

Implementation Guide

This code identifies the relevant ASC X12 Implementation Guide which can be found at in a new tab. The identifier is unique across all document structures and schemas.

Viewing a Segment Structure

To view the structure of a document segment, click on its name in any page similar to the example shown in the previous section. InterSystems IRIS displays a table that lists all the fields in that segment. This is the Schema Segment Structure page.

For example, if you click on the PER segment in the HIPAA_4010:276 document structure, InterSystems IRIS displays the following page.

Detailed list of the properties in a particular segment of a HIPAA_4010:276 document

The columns are as follows:

  • Elem—the number to use to access the element within the segment (if you prefer numbers).

  • Description —a short description of the element.

  • Data Type—a one to two letter symbol representing the element data type. See the table below for details.

    Nn for numeric, R for decimal, ID for identifier, AN for string, DT for date, TM for time, and B for binary

  • Required—displays R for required, O for optional.

  • Length—the number of characters that can be in the element. If only one number is present, it represents the maximum number of characters. If two numbers are separated by a hyphen, it is the range of characters that can be in the associated element (minimum-maximum).

  • Max Repeats—the maximum number of times the element can repeat.

  • Alternate Description—a second, longer description of the element.

You can use this information, particularly the Property Name column, to build virtual property paths for InterSystems IRIS in the format segment:elem. The following are examples of virtual property paths involving simple elem values from the PER segment in the HIPAA_4010:276 document structure. The () shortcut syntax indicates all available instances of a repeating field, whereas (1) indicates the first instance:


Viewing a Composite Structure

When you select a name in the Composite Structure column, InterSystems IRIS displays all the elements in that data structure. This is the Composite Structure page. The column values are identical to those of the previous section.

Choosing a Different Category

It is a feature of the X12 standard that a document structure can differ by X12 version, even when the structure has the same name and number. For example, both X12 HIPAA_4010 and X12 HIPAA_5010 define a document structure called 277, but these definitions contain some differences in segments and segment repetitions. InterSystems IRIS provides the document structure definitions HIPAA_4010:277 and HIPAA_5010:277. The X12 Document Structure page makes it easy to see the differences between the two definitions, as the following two figures show.

Two X12 document structures shown side by side

Using the X12 Document Viewer Page

InterSystems IRIS provides a Document Viewer page for X12. You can use this page to display, transform, and export X12 documents (either external files or documents from the production message archives).

To access this page, select Interoperability > Interoperate > ASC X12 > ASC X12 Document Viewer.

Selecting Options

To specify the document to display:

  1. For Document Source, select File, Message Header ID, or Message Body ID.

  2. Specify the document to display:

    • If you selected File, use Browse to choose a file. For Document Number in File, type the number of the document to display.

    • If you selected Message Header ID or Message Body ID, type the ID of the message header or message body to display.

  3. Specify how to parse the document. To do so, select one of the following options for Document Structure or Schema:

    • As received by a Business Service—Use the schema as assigned by a business service. If you select this, select a business service from the drop-down list.

      This option enables you to determine the DocType to which a particular business service would assign this document.

    • Use a specific Schema Category/Version—Choose a document category from the drop-down list.

    • Use a specific DocType—Enter the name of an document structure (<MessageStructure>) in the format category:structure. The parser uses this document structure.

    • Use content-declared Version:Name—Use the document structure associated with the document type declared in the document.

    • Use object's stored DocType—Use the DocType as declared in the document body object. (This option does not apply to documents loaded from a file.)

    • None—Do not use any DocType to parse the document. Instead, display the raw segment without showing any of them as links.

    This option enables you to try interpreting documents from a particular data source as different schema category types to determine which DocType is the right one to use when handling documents from that source. There are a variety of reasons why you might need to do this. For example, you might find when you update an external application that it has changed the actual version of the documents it sends, but has neglected to update the type declaration that it sends in these documents. It is also useful in determining which of the built-in categories to use as a schema base, when a document uses a custom document structure.

  4. Optionally click Transform Document? and specify the transformation details. See Testing a Transformation.

  5. Click OK.

Parsing the Document

To parse the document, set the options described above and click OK. The Document Viewer displays the following on the right side of the screen:

  • A summary of the document which contains following basic information:

    • The Data Transformation applied, if applicable

    • The Document ID

    • The DocType

    • The DocType description, if available

    • The number of segments

    • The Document ID of parent documents, if applicable

  • The document data, which has one row for each segment in the document structure. Each row contains:

    • Segment number

    • Segment name, such as ISA or DN1

    • Element contents and separators, as contained in the document

If the document matches the schema you have selected, segments and elements appear as links to the relevant structure page.

X12 Document Viewer page for a HIPAA_4010:837D document


Due to the multiplicity of X12 DocType structures that use the same transaction set identifier code (ST:1), InterSystems IRIS checks the additional reference identification numbers ST:3, GS:8, or REF:2 and uses the first implementation guide version number found to uniquely identify document types. For example, examine HIPAA_4010:837P and HIPAA_4010:837D. Both documents have a transaction set identifier of 837, however each has a distinct reference identification number. See Implementation Guide.

Displaying the Segment Address

To display a segment address, hover the cursor over a segment name in the shaded column. The tooltip displays the following:

  • Segment address to use in a virtual property path

  • Descriptive name of this segment

Cursor hovering over a segment name and a tooltip showing the segment address and name, Individial or Organizational Name

Displaying the Element Address

To display the Element address, hover the cursor over a field within the document structure. The tooltip displays the following:

Cursor hovering over an element and a tooltip showing the element address

Viewing X12 Interchanges

When viewing Transaction Sets nested in Groups and Interchanges the Interoperability > Interoperate > ASC X12 > ASC X12 Document Viewer page allows you to walk through the document structure one level at a time.

The following display is the result of using the X12 document viewer to view a 4010:Interchange document.

The Document Viewer assigns the group document the identifier <38>.

ASC X12 Document Viewer page showing the highest level structure for a HIPAA_4010:Interchange document

When you click on a group document link in an X12 Interchange document display, a new browser window opens to display the group document. The document Viewer window, with the top-level parent, remains open in the original browser window.

The next display is the result of clicking the link to Group document <38>.


If there are more than 10 Groups in an Interchange or more than 10 Transaction Sets in a Group, the Document Viewer displays links to the first five and last five documents. Between the lists is a text field, into which you can enter any identifier number between the first and last numbers. After you enter a number, click Other. A new browser window opens to display the document.

ASC Document Viewer page for a HIPAA_4010:Group document

The next display is the result of clicking the Transaction Set <39>. You can return to either the Group or the Interchange by clicking their respective Document ID number links.

ASC X12 Document Viewer page for a HIPAA_4010:837D document

When you are done viewing documents in the batch document hierarchy, you can close all the pop-up browser windows until the top-level parent document remains in the original document Viewer window. From here, you may return to other Management Portal activities.

Testing a Transformation

To test a transformation:

  1. Check Transform Document?.

  2. For Choose Data Transformation, select a data transformation.

  3. For Choose Display Option, select one of the following:

    • Transformation Result Only—Display only the transformed document.

    • Original Message and Result Together—Display both the original document and the transformed document.

  4. Now do either or both of the following:

    • Click OK to display the transformed document.

    • Click Save Result To File? to save the transformed document to a file. In this case, also specify a path and filename.

      The default directory is the management directory for the active namespace.

X12 Classes

For reference, this section lists the classes that InterSystems IRIS provides to enable you to work with X12 documents.

Item Classes Notes
X12 business services* Each of these X12 business service classes uses a different adapter, as indicated by the class name.
X12 business process* EnsLib.MsgRouter.VDocRoutingEngineOpens in a new tab This class is the standard virtual document business process.
X12 business operations* Each of these X12 business operation classes uses a different adapter, as indicated by the class name.
Messages EnsLib.EDI.DocumentOpens in a new tab (automatically used by the business host classes) This is a specialized message class to carry X12 documents as virtual documents.
Search table EnsLib.EDI.X12.SearchTableOpens in a new tab This is a specialized search table class for X12 documents.
Validation and Batch Handling These two classes allow for validation and handling of X12 batches and documents. This includes generating replies and splitting batches in two (one containing children which pass validation and the other containing those which failed validation).

*When you configure a production to work with X12 documents, the Management Portal automatically selects the appropriate business host class.

You can also create and use subclasses of these classes.

The business host classes include configurable targets. The following diagram shows some of them:

Diagram showing the flow from a business process to a routing process that includes a routing rule set and transformation

For information on other configurable targets, see Reference for Settings.

Creating Custom X12 Schemas

You can create custom X12 schemas in any of the following ways:

  • Create a .x12 file using an XML editor.

  • Import an existing schema using the X12 Schemas Management Portal page. Select Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures to get to the X12 Schemas page.

  • Create an XML file in an IDE and give it an .x12 extension.

You are now ready to edit your file to add and remove XML statements from the <Category> block. The basic editing steps are as follows:

  1. Define custom segments using <SegmentStructure> elements.

  2. Define custom <MessageStructure> elements that contain the custom segments.

  3. Define custom <MessageType> elements that contain the custom message structures.

  4. Try viewing the new category definition from the Management Portal. See Portal Tools.

For information on creating custom schema categories, see Creating Custom Schema Categories.

Defining X12 Search Tables

The X12 search table class, EnsLib.EDI.X12.SearchTableOpens in a new tab, automatically indexes the X12 document ID, which it gives the name Identifier.

If you need more items to search, you can create a subclass. The subclass inherits the Identifier property, plus the infrastructure that makes search tables work. For details, see Defining a Search Table Class.

Be sure to perform all tasks in the same namespace that contains your production. Do not use reserved package names; see Reserved Package Names. Also see Overriding the Validation Logic.

See Also

FeedbackOpens in a new tab