@rethinkhealth/hl7v2-lint-required-message-header

A unified lint rule for HL7v2 that warns when the message header segment (MSH) is missing or not the first segment in a message. This helps ensure all HL7v2 messages begin with the required header, improving interoperability and data quality.

HL7v2 messages must always begin with a message header segment, known as MSH. This rule checks that the first segment in a message is MSH and warns if it is missing or replaced by another segment.

What is this?

This package validates the segment header in HL7v2 syntax trees produced by parsers like @rethinkhealth/hl7v2-parser.

It reports a message when the first segment of an HL7v2 message is not a segment header (MSH).

When should I use this?

Use this rule to enforce canonical HL7v2 segment identifiers across messages, catch typos (e.g., PID1, Obx, MS), and improve downstream processing reliability.

Presets

This plugin is included in the following presets:

| Preset | Options | | - | - | | @rethinkhealth/hl7v2-lint-recommended | |

Install

This package is ESM only. In Node.js (v16+), install with npm:

npm install @rethinkhealth/hl7v2-lint-required-message-header

Use

On the API:

import { unified } from 'unified'
import { hl7v2Parse } from '@rethinkhealth/hl7v2-parser'
import hl7v2LintRequiredMessageHeader from '@rethinkhealth/hl7v2-lint-required-message-header'
import { reporter } from 'vfile-reporter'

const msg = `MSH|^~\\&|...`
const file = await unified()
  .use(hl7v2Parse)
  .use(hl7v2LintRequiredMessageHeader)
  .process(msg)

console.error(reporter([file]))

API

unified().use(hl7v2LintSegmentHeaderLength[, options])

Warn when a segment header is not a three-letter uppercase code.

Returns

A unified Transformer that adds messages to the file.

Recommendation

This helps ensure that HL7v2 messages are well-formed and can be reliably parsed and processed by downstream systems. If the message does not start with MSH, a warning is reported indicating which segment was found instead.

Why is this important?

• The MSH segment contains metadata required for routing and interpreting the message.
• Missing or misplaced MSH segments can cause interoperability issues and data loss.

When to disable:

You should only disable this rule if you are intentionally working with non-standard HL7v2 messages that do not require a message header segment, which is rare in practice.

It’s recommended to enable this rule in most pipelines.

Examples

ok.hl7

In

MSH|^~\&|... 
PID|1||12345^^^HOSP^MR||DOE^JANE||...
OBX|1|TX|...

Out

No messages.

not-ok.hl7

In

PID|1||12345||DOE^JANE||...

Out

Message header (MSH) segment is required. Received PID instead.

Security

This plugin only transforms AST nodes and does not execute code. Ensure you trust the source of HL7v2 messages before processing.

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.