HL7 v2.x is the most widely adopted messaging standard in healthcare for exchanging clinical and administrative data between disparate health systems. This document provides a comprehensive analysis of HL7 v2.x specifications (versions 2.1-2.8), common message types, conformance requirements, and implementation considerations for the HL7kit framework.
- First widely adopted version, initiated basic event-based messaging
- Supported core domains: ADT (Admissions/Discharges/Transfers), ORM (Orders), ORU (Results), and DFT (Financial)
- Foundation for all subsequent versions
- Limited data types and encoding rules
- Basic message structures
- Expanded data types for better expressiveness
- Enhanced message structures for laboratory and pharmacy workflows
- Improved acknowledgement message handling
- Additional segment definitions
- Major expansion of functionality
- Added extensive laboratory and clinical event workflows
- New message types:
- SIU (Scheduling Information Unsolicited)
- QRY (Query messages)
- Bedside monitoring support
- Greater granularity in segments and fields
- Support for repeatable and optional segments
- Errata and refinements to v2.3
- Improved clarity and bug fixes
- Most stable v2.3 release
- Widely adopted due to reliability
- Enhanced laboratory, blood bank, and radiology messaging
- New messages for diagnostic imaging
- Refined existing segments for better clarity
- Powerful scheduling support
- Additional patient care details
- Significant structural update
- Restructured documentation with improved organization
- Chapter 2A: Centralized dictionary of all data types
- Broadened message types for regulatory requirements
- Enhanced public health reporting support
- Better device integration capabilities
- Public health surveillance messaging
- Most widely implemented version
- Required standard for U.S. federal initiatives (Meaningful Use)
- Critical refinements and clarifications to v2.5
- Enhanced immunization reporting
- Comprehensive public health reporting support
- De facto interoperability standard in U.S. and internationally
- Corrections and improvements to message structures
- Enhanced telecommunication support
- Support for complex workflow scenarios
- Additional segment refinements
- Enhanced pharmacy messaging
- Improved diagnostic imaging support
- Clinical trials integration
- Standardized acknowledgment protocols
- Better message conformance specifications
- Further refinements and consistency improvements
- Expanded public health capabilities
- Enhanced clinical research support
- Advanced device integration
- Improved documentation structure
- Chapters 2 and 2A centrally define control and data types
- Easier implementation and maintenance
- All HL7 v2.x versions maintain backward compatibility
- Older systems can process newer messages by ignoring unknown fields/segments
- Highly flexible standard allows local customization
- Different implementations possible across vendors
Purpose: Manages patient administration events including admissions, discharges, transfers, and demographic updates.
Common Event Codes:
A01- Admit/Visit NotificationA03- Discharge/End VisitA04- Register a PatientA05- Pre-admit a PatientA08- Update Patient InformationA11- Cancel AdmitA12- Cancel TransferA13- Cancel Discharge
Message Structure:
MSH Message Header (Required)
EVN Event Type (Required)
PID Patient Identification (Required)
[PD1] Patient Additional Demographic (Optional)
[{NK1}] Next of Kin / Associated Parties (Optional, Repeating)
PV1 Patient Visit (Required)
[PV2] Patient Visit - Additional Info (Optional)
[{DB1}] Disability (Optional, Repeating)
[{OBX}] Observation/Result (Optional, Repeating)
[{AL1}] Allergy Information (Optional, Repeating)
[{DG1}] Diagnosis (Optional, Repeating)
[DRG] Diagnosis Related Group (Optional)
Key Segments:
- MSH - Message Header: Metadata about the message
- EVN - Event Type: Event that triggered the message
- PID - Patient Identification: Patient demographics
- PV1 - Patient Visit: Encounter details
- NK1 - Next of Kin: Emergency contacts
- AL1 - Allergy Information: Patient allergies
Key Fields:
PID-3- Patient Identifier ListPID-5- Patient NamePID-7- Date/Time of BirthPID-8- Administrative SexPV1-2- Patient Class (I=Inpatient, O=Outpatient, E=Emergency)PV1-3- Assigned Patient LocationPV1-7- Attending DoctorPV1-19- Visit Number
Purpose: Carries requests for clinical services including lab tests, procedures, medications, and other orders.
Common Event Codes:
O01- Order MessageO02- Order Response
Message Structure:
MSH Message Header (Required)
[{NTE}] Notes and Comments (Optional, Repeating)
[
PID Patient Identification (Required)
[PD1] Patient Additional Demographic (Optional)
[{NTE}] Notes and Comments (Optional, Repeating)
[PV1] Patient Visit (Optional)
[PV2] Patient Visit - Additional Info (Optional)
[{IN1}] Insurance (Optional, Repeating)
[GT1] Guarantor (Optional)
[{AL1}] Allergy Information (Optional, Repeating)
{
ORC Common Order (Required)
[
OBR Observation Request (Required)
[{NTE}] Notes and Comments (Optional, Repeating)
]
}
]
Key Segments:
- ORC - Common Order: Order control information
- OBR - Observation Request: Details about requested service
- TQ1 - Timing/Quantity: When and how often
Key Fields:
ORC-1- Order Control (NW=New, CA=Cancel, DC=Discontinue)ORC-2- Placer Order NumberORC-3- Filler Order NumberORC-5- Order StatusOBR-4- Universal Service Identifier (test/procedure code)OBR-7- Observation Date/TimeOBR-16- Ordering Provider
Purpose: Delivers results of observations, including laboratory, radiology, and other diagnostic results.
Common Event Codes:
R01- Unsolicited Observation MessageR03- Unsolicited Specimen Results
Message Structure:
MSH Message Header (Required)
{
[
PID Patient Identification (Required)
[PD1] Patient Additional Demographic (Optional)
[PV1] Patient Visit (Optional)
{
OBR Observation Request (Required)
[{NTE}] Notes and Comments (Optional, Repeating)
{
OBX Observation/Result (Required)
[{NTE}] Notes and Comments (Optional, Repeating)
}
}
]
}
Key Segments:
- OBR - Observation Request: Context for results
- OBX - Observation/Result: Actual result data
Key Fields:
OBR-4- Universal Service IdentifierOBR-7- Observation Date/TimeOBX-1- Set IDOBX-2- Value Type (NM=Numeric, ST=String, CE=Coded Entry)OBX-3- Observation IdentifierOBX-5- Observation Value (the actual result)OBX-6- UnitsOBX-7- References RangeOBX-8- Abnormal Flags (N=Normal, H=High, L=Low)OBX-11- Observation Result Status (F=Final, P=Preliminary)
Purpose: Acknowledges receipt and processing status of any HL7 message.
Message Structure:
MSH Message Header (Required)
MSA Message Acknowledgment (Required)
[{ERR}] Error (Optional, Repeating)
Key Segments:
- MSA - Message Acknowledgement: Status of received message
- ERR - Error: Details about errors
Key Fields:
MSA-1- Acknowledgment Code (AA=Accept, AE=Error, AR=Reject)MSA-2- Message Control ID (from received message)MSA-3- Text Message (description of error/success)ERR-1- Error Code and Location
Purpose: Requests specific information from another system, such as patient demographics or clinical data.
Common Query Types:
Q01- Query Sent for Immediate ResponseQ02- Query Sent for Deferred ResponseQ22- Find Candidates
Message Structure (QRY):
MSH Message Header (Required)
QRD Query Definition (Required)
[QRF] Query Filter (Optional)
Message Structure (QBP - Query by Parameter):
MSH Message Header (Required)
QPD Query Parameter Definition (Required)
[RCP] Response Control Parameter (Optional)
[DSC] Continuation Pointer (Optional)
Key Fields:
QRD-1- Query Date/TimeQRD-3- Query Format CodeQRD-8- Who Subject Filter (patient identifier)QPD-1- Message Query NameQPD-2- Query TagQPD-3+- Query parameters (varies by query type)
- Purpose: Schedule appointments and resources
- Events: S12=New Appointment, S13=Appointment Reschedule, S15=Cancel
- Purpose: Manage clinical documents and reports
- Events: T01=Create Document, T02=Edit Document
- Purpose: Financial transactions and billing
- Events: P01=Add Patient Accounts, P06=Purge Patient Accounts
- Purpose: Post charges and financial details
HL7 v2.x messages are pipe-delimited text with hierarchical structure:
Segment|Field1|Field2^Component1^Component2|Field3&Subcomponent1&Subcomponent2|...
- Segment Terminator: Carriage Return (
\ror\r\n) - Field Separator: Pipe (
|) - Component Separator: Caret (
^) - Subcomponent Separator: Ampersand (
&) - Repetition Separator: Tilde (
~) - Escape Character: Backslash (
\)
\.br\- Line break\F\- Field separator\S\- Component separator\T\- Subcomponent separator\R\- Repetition separator\E\- Escape character\Xnn\- Hexadecimal data
The MSH segment defines the message metadata:
MSH|^~\&|SendingApp|SendingFacility|ReceivingApp|ReceivingFacility|20240207120000||ADT^A01|MSG00001|P|2.5.1
MSH Fields:
MSH-1- Field Separator (|)MSH-2- Encoding Characters (^~\&)MSH-3- Sending ApplicationMSH-4- Sending FacilityMSH-5- Receiving ApplicationMSH-6- Receiving FacilityMSH-7- Date/Time of MessageMSH-9- Message Type (MessageType^EventCode)MSH-10- Message Control ID (unique identifier)MSH-11- Processing ID (P=Production, T=Training, D=Debugging)MSH-12- Version ID
| Type | Name | Description | Example |
|---|---|---|---|
| ST | String | General text | "Patient Name" |
| TX | Text | Long text, may contain formatting | "Clinical notes..." |
| FT | Formatted Text | Rich text with formatting | "\.br\New line" |
| NM | Numeric | Decimal number | 123.45 |
| SI | Sequence ID | Integer for ordering | 1 |
| DT | Date | Date in format YYYYMMDD | 20240207 |
| TM | Time | Time in format HHMMSS | 120000 |
| DTM (TS in v2.3) | Date/Time | Combined date and time | 20240207120000 |
| ID | Coded Value (defined tables) | Predefined code | M (for Male) |
| IS | Coded Value (user-defined) | User-defined code | Custom value |
| Type | Name | Components | Example |
|---|---|---|---|
| CE | Coded Element | Identifier^Text^CodingSystem | 410623003^Malaria^SNOMED |
| CX | Extended Composite ID | ID^CheckDigit^CheckDigitScheme^AssigningAuthority | 123456^^^Hospital^MR |
| XPN | Extended Person Name | FamilyName^GivenName^MiddleName^Suffix^Prefix | Smith^John^A^Jr^Dr |
| XAD | Extended Address | Street^OtherDesignation^City^State^Zip^Country | 123 Main St^^Boston^MA^02101^USA |
| XTN | Extended Telecommunication | [(999)]999-9999[X99999] | (617)555-1234 |
| EI | Entity Identifier | EntityID^NamespaceID | MSG00001^SendingSystem |
| HD | Hierarchic Designator | NamespaceID^UniversalID^UniversalIDType | Hospital^1.2.3.4^ISO |
| PL | Person Location | PointOfCare^Room^Bed^Facility^LocationStatus^PersonLocationType | 4E^401^B^Hospital^^N |
A conformance (or message) profile is a precise specification that defines:
- Required message structure
- Segment ordering and cardinality
- Field requirements and constraints
- Data type specifications
- Vocabulary bindings
- Business rules
- R - Required: Must be present
- O - Optional: May be present
- C - Conditional: Required under certain conditions
- X - Not Used: Should not be present
- B - Backward Compatibility: Deprecated but supported
[0..1]- Optional, maximum once[1..1]- Required, exactly once[0..*]- Optional, may repeat[1..*]- Required, may repeat[n..m]- Specific min/max repetitions
[]- Optional segment or group{}- Repeating segment or group[{}]- Optional and repeating
Example:
MSH
[{SFT}]
[{UAC}]
PID
[PD1]
[{PRT}]
[{ARV}]
[{ROL}]
[{NK1}]
PV1
[PV2]
-
Syntactic Validation
- Proper delimiters and encoding
- Valid segment structure
- Correct field data types
- Field length constraints
-
Semantic Validation
- Required fields present
- Cardinality constraints met
- Conditional rules satisfied
- Value set adherence
-
Business Validation
- Context-specific rules
- Cross-field dependencies
- Temporal consistency
- Clinical validity
-
Required Fields Must Be Present
- Missing required fields invalidate the message
- Empty required fields may be acceptable in some profiles
-
Data Type Constraints
- Values must match specified data type
- Numeric fields must contain valid numbers
- Dates must be valid and properly formatted
-
Length Constraints
- Field values must not exceed maximum length
- Truncation rules may apply
-
Value Set Binding
- Coded fields must use valid codes from specified value sets
- May be "required" (strict) or "extensible" (allow local codes)
-
Cardinality Rules
- Segments/fields must appear within specified repetition limits
- Order of segments must follow specification
Message Type: ADT^A04 Use Case: Register a new patient in the system Key Data: Demographics, insurance, emergency contacts
Message Type: ADT^A01 Use Case: Admit a patient to inpatient care Key Data: Patient info, admission location, attending physician
Message Type: ADT^A03 Use Case: Discharge patient from care Key Data: Discharge date/time, disposition, discharge location
Message Type: ADT^A02 Use Case: Move patient to different location/unit Key Data: New location, transfer reason, receiving physician
Message Type: ADT^A08 Use Case: Update patient demographic information Key Data: Changed fields (address, phone, insurance, etc.)
Message Type: ORM^O01 Use Case: Order laboratory tests Key Data: Test codes, specimen info, clinical questions
Message Type: ORU^R01 Use Case: Send lab test results Key Data: Test results, units, reference ranges, abnormal flags
Message Type: ORM^O01 Use Case: Order imaging studies Key Data: Procedure codes, clinical indication, urgency
Message Type: ORU^R01 or MDM^T02 Use Case: Send radiology report/interpretation Key Data: Findings, impressions, recommendations
Message Type: RDE^O11 or ORM^O01 Use Case: Order medications Key Data: Drug codes, dose, route, frequency, duration
- Lazy Parsing: Parse segments on-demand, not upfront
- Streaming: Process messages without loading entirely into memory
- Object Pooling: Reuse frequently created objects
- Efficient String Handling: Minimize string copies and allocations
- Copy-on-Write: Share data until modification
- Compact Representation: Use efficient data structures
- Selective Parsing: Only parse needed segments/fields
- Resource Management: Proper cleanup and deallocation
- Recoverable Errors: Continue parsing when possible
- Detailed Error Context: Provide segment/field location
- Validation Levels: Support different strictness levels
- Error Accumulation: Collect multiple errors in one pass
- Immutable Messages: Prefer immutable structures
- Actor-Based Processing: Use Swift actors for concurrent access
- Sendable Conformance: Ensure thread-safe types
- Async/Await: Use modern concurrency patterns
For comprehensive testing, the following test data sets should be created:
- Complete ADT^A01 (admission)
- Complete ORM^O01 (lab order)
- Complete ORU^R01 (lab results)
- Complete ADT^A03 (discharge)
- Complete ADT^A08 (demographics update)
- Minimal valid message (only required fields)
- Maximum repeating segments
- Special characters in text fields
- Very long field values
- Unicode/multi-byte characters
- Messages with all optional fields
- Messages with escape sequences
- Missing required segments
- Missing required fields
- Invalid data types
- Invalid date/time formats
- Cardinality violations
- Unknown segment types
- Malformed delimiters
- Invalid escape sequences
- Test data for each supported version (2.1-2.8)
- Version-specific segments and fields
- Deprecated elements
- Version migration scenarios
- Complex multi-segment messages
- Messages with multiple repetitions
- Nested group structures
- Batch/file processing (FHS/BHS)
- ACK generation scenarios
| Feature | v2.1 | v2.2 | v2.3 | v2.3.1 | v2.4 | v2.5 | v2.5.1 | v2.6 | v2.7 | v2.8 |
|---|---|---|---|---|---|---|---|---|---|---|
| Basic ADT | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ORM/ORU | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Scheduling (SIU) | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Query (QRY) | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| MDM | - | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Immunization | - | - | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
| Public Health | - | - | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
| Enhanced Data Types | - | - | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ |
- HL7 v2.x Standard Documentation: http://www.hl7.org/
- HL7 v2 Implementation Guide: https://v2.hl7.org/
- HL7 Conformance Methodology: https://v2.hl7.org/conformance/
- NIST General Validation Tool: https://hl7v2-gvt.nist.gov/
- HAPI Parser: https://hapifhir.github.io/hapi-hl7v2/
- HL7 Version 2 Product Suite: https://www.hl7.org/implement/standards/product_brief.cfm?product_id=185
- HL7 Message Examples: Various GitHub repositories and community resources
This document is part of the HL7kit project and will be updated as implementation progresses.