HL7v2-AST

Health Level 7 Version 2 Abstract Syntax Tree.

hl7v2-ast is a specification for representing HL7v2 messages as an abstract syntax tree. It implements unist and provides a structured, lossless representation of HL7v2 segments, fields, field repetitions, components, and subcomponents.

Introduction

This document defines a format for representing HL7v2 messages as an abstract syntax tree.

hl7v2-ast was created to support parsing, validation, transformation, and linting of HL7v2 messages in a structured way.

The specification follows the Unist model to benefit from the ecosystem of utilities and the Unified processing pipeline.

Where this specification fits

• hl7v2-ast extends unist with HL7-specific node types.
• Integrates with editor tooling, validators, and transformers.

Types

TypeScript types are published with the package:

npm install @rethinkhealth/hl7v2-ast

Node Hierarchy

The AST reflects the full HL7v2 delimiter hierarchy:

root
└── segment
    └── field (|)
        └── field-repetition (~)
            └── component (^)
                └── subcomponent (&)

• Every field always contains one or more field-repetition nodes, even if there is no ~.
• Every component always contains one or more subcomponent nodes, even if there is no &.
• Only subcomponent nodes carry value.

Nodes (abstract)

Literal

interface Literal <: UnistLiteral {
  value: string
}

Represents a leaf HL7v2 node containing a value. In this AST, the leaf is always a subcomponent.

Parent

interface Parent <: UnistParent {
  children: [HL7v2Node]
}

Represents a container node such as a segment, field, or component.

Nodes (concrete)

Root

interface Root <: Parent {
  type: 'root'
  children: [Segment | Group]
}

Root of an HL7v2 AST. Can represent a full message or a fragment.

Segment

interface Segment <: Parent {
  type: 'segment'
  name?: string
  children: [Field]
}

Represents an HL7v2 segment such as MSH, PID, or OBX.

The name property can be used to identify the segment without traversing the field hierarchy. When present, it contains the segment identifier (e.g., "MSH", "PID", "OBX").

Group

interface Group <: Parent {
  type: 'group'
  name: string
  children: [Segment]
}

Represents a repeating or optional group of related segments (e.g., ORC+OBR+OBX).

Field

interface Field <: Parent {
  type: 'field'
  index: number
  children: [FieldRepetition]
}

Represents a field inside a segment. Always contains one or more field-repetition nodes.

FieldRepetition

interface FieldRepetition <: Parent {
  type: 'field-repetition'
  index?: number
  children: [Component]
}

Represents one ~-separated instance of a field. Always contains one or more component nodes.

Component

interface Component <: Parent {
  type: 'component'
  index: number
  children: [Subcomponent]
}

Represents a ^-separated component. Always contains one or more subcomponent nodes.

Subcomponent

interface Subcomponent <: Literal {
  type: 'subcomponent'
  index: number
  value: string
}

Represents an &-separated subcomponent and holds the actual text value.

Position

All nodes may include a position property following unist:

interface Position {
  start: Point
  end: Point
}

interface Point {
  line: number
  column: number
  offset: number
}

Content model

type HL7v2Content =
  Root | Segment | Group | Field | FieldRepetition | Component | Subcomponent

Extensions

The AST is designed for:

• Validation plugins (segment rules, field presence)
• Annotation plugins (map to FHIR, metadata)
• Transformers (to JSON, FHIR, XML)

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code of Conduct

To ensure a welcoming and positive environment, we have a Code of Conduct that all contributors and participants are expected to adhere to.

License

Copyright 2025 Rethink Health, SUARL. All rights reserved.

This program is licensed to you under the terms of the MIT License. This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for details.