Skip to content

Versioning

How the standard has changed from version 2.1 to 2.9, and what that means for compatibility.

HL7v2 has been revised many times since its first widely implemented release in 1990, and messages from versions as early as 2.3 remain common in production. Each message declares its version in the header, in MSH-12, and a destination uses this value to select the definitions against which it interprets the message. This selection matters because HL7v2 messages are not self-describing: the version's definitions determine what every field means. Two properties determine how versions interact in practice: each release adds to the previous one without removing elements, and installed systems change versions infrequently.

Releases

VersionYearNotable for
2.11990First widely implemented release. ADT, orders, results, and billing in approximately their current form.
2.21994Incremental additions; the last small release before the expansion of the standard in 2.3.
2.31997Scheduling (SIU), document management (MDM), and patient referral messages. Many long-lived systems were built on this version.
2.3.11999Message structure codes (MSH-9.3) and the coded types CWE and CNE. Still common in production.
2.42000Laboratory order (OML), query by parameter (QBP), and the first conformance-profile methodology.
2.52003The DTM data type, the current ERR segment built on CWE, and MSH-21 retyped as the message profile identifier.
2.5.12007A corrections release, required by the US immunization, laboratory reporting, and syndromic surveillance guides.
2.62007TS replaced by DTM, and CE by CWE or CNE, in every field; UAC user-authentication segment.
2.72011Lengths become advisory; truncation character #; many IS fields retyped to CWE. Together with 2.6, the largest set of data type changes in the standard.
2.7.12012Errata to 2.7.
2.82014Incremental additions across every chapter.
2.8.12014Errata and additions to 2.8.
2.8.22015Errata and additions to 2.8.1.
2.92019The current release.

HL7 International also maintains V2+, a reformulation of the standard as machine-readable definitions that can be published more frequently than a full release. Versions after 2.5.1 are less common in production, and version 2.9 is rarely implemented. Most production interfaces use versions 2.3 through 2.5.1, and newer vendor products increasingly use the data types introduced in versions 2.6 and 2.7.

Change rules

Each release adds to the previous one. New fields are appended to the end of existing segments, never inserted between existing fields. New segments are added as optional elements of existing message structures. New trigger events, data types, and table values are added alongside existing ones. Elements are not removed from the standard; they are marked instead.

An element that is no longer to be used is marked withdrawn (W): it remains in the definition to preserve the positions of the elements that follow it, and it must not be populated. An element marked for backward compatibility (B) has a newer alternative and is retained so that messages from earlier versions remain valid. PID-19, the social security number, was marked B from version 2.4 through 2.6, because the identifier belongs in PID-3 with the patient's other identifiers, and it has been marked W since version 2.7, as has PID-2, the external patient ID.

Data types change more often than segments. A field's type can be widened to a type that contains the old type as its first component, such as IS to CWE, CE to CWE, or TS to DTM, so that a value written in the old form remains valid in the new one. F is a valid CWE, and 20230630120000 is a valid DTM. Data types lists the main changes.

Tables change the most. HL7-defined tables gain values, user-defined tables receive new suggested values, and a few tables are deprecated in favor of external vocabularies. A code that was valid in version 2.3 is usually still valid in version 2.8, but a code added in a later version is not valid in an earlier one, and the display text of a code can change between versions.

Compatibility

The standard states its compatibility rule from the destination's side: a system that implements a given version should accept messages from any earlier version. Because a message from an earlier version contains a subset of the later definition, with fewer fields, fewer segments, and narrower types, a version 2.8 destination can read a version 2.3 message by treating the missing elements as empty.

Forward compatibility, the acceptance of messages from a later version, is addressed by the rules for destination systems. A destination ignores segments it does not recognize, ignores fields beyond the last field it defines, and does not reject a message because the message contains more than expected. A version 2.3 destination that follows these rules can accept a version 2.8 message by discarding the elements it does not define.

Both rules apply at the level of syntax: a message from any version can be read by a system built for any other version, and the fields that both versions define are in the same positions. At the level of meaning, the guarantees are weaker. A version 2.3 destination that discards PID-39, tribal citizenship, loses information that the source intended to convey. A version 2.8 source that populates the later components of XPN sends data that a version 2.3 destination ignores. A source that declares version 2.8 in MSH-12 but populates PID as defined in version 2.3 misstates the content of its messages, and this mismatch is common.

Backward compatibility is not guaranteed

HL7v2 is designed for backward compatibility, but implementations do not always follow the compatibility rules. Some systems accept one version and reject all others. Some interpret a message according to the version in MSH-12, and others ignore it. Interfaces should therefore be tested with the actual source and destination systems rather than relying on the declared version.

Declared version

MSH-12 identifies the version that the source declares, which does not necessarily correspond to the fields the message contains. Systems typically declare the version that their vendor's documentation was written against, often the version on which the product was originally built, regardless of the fields the product populates in its current release.

Three discrepancies are common:

  • A system declares version 2.3 but sends fields introduced in version 2.5, because the fields were added in a later product release and the declared version was not updated.
  • A system declares version 2.5.1 because a regulation requires it, while its message content is unchanged from version 2.3.
  • An interface engine rewrites MSH-12 in transit, so that the destination sees the version it is configured for, regardless of the version the source declared.

As a result, MSH-12 identifies the reference definition against which to interpret a message, but it does not indicate what the message contains. The contents of a message are specified by the interface's profile.

Selection

The version used for a new interface is usually determined by external constraints.

When a regulation or an implementation guide applies, it specifies the version. Most public-health reporting, laboratory, and immunization interfaces in the United States use version 2.5.1 because the applicable guides specify it, and national guides in other countries specify versions in the same way.

Otherwise, the version is constrained by the less flexible of the two systems, which is usually the older one: a recently built destination accepts a version 2.3 message, but a system built in 1998 may not accept a version 2.8 message. The interface is built to the lower version, and fields that a source built for a newer version would have populated are either omitted or carried in Z-segments.

When neither constraint applies, version 2.5.1 is the usual choice. It includes CWE, the current ERR segment, and MSH-21; it is fully supported by widely used HL7v2 libraries and interface engines; and most reference material and tooling target it.

The newest release, version 2.9, is rarely chosen, because few production systems implement it.

Trade-offs

The additive rule gives the standard stability, at the cost of accumulation and slow adoption:

  • Stability. A new version does not require existing interfaces to change. Interfaces built for early versions remain in service alongside newer ones, and each interface adopts new elements only when it needs them.
  • Accumulation. Elements are never removed, so each version is larger than the one before. The PID segment defines forty fields in version 2.9, several of them withdrawn or retained only for backward compatibility, and ambiguities from earlier versions remain in the standard, annotated rather than resolved.
  • Slow adoption. An installed system usually changes versions only when it is replaced. Recent work on the standard, such as V2+ and the alignment of tables with FHIR terminology, therefore reaches production systems slowly.

Further reading