HL7 VID Data Type: Version Identifier

The VID (Version Identifier) data type was introduced in HL7 v2.3 to make the message version explicit and machine-readable. Before v2.3, MSH-12 was a single string carrying values like 2.1 or 2.2; v2.3 promoted it to a composite so senders could additionally declare an internationalization code (the national profile the message conforms to) and the version of that international profile.

VID appears in exactly one place — MSH-12 — and that one field is what every parser reads first. The version number determines which structural grammar to apply, which fields are present in each segment, and which data types every component expects.

Purpose

VID solves three problems in one composite:

Parser version selection. A receiver that supports multiple HL7 versions reads VID.1 first to decide which parser to load. ADT_A01 in v2.3 has a different segment list than ADT_A01 in v2.8.1; the parser must know which to expect before it reads anything past MSH.
National-profile declaration. Many countries publish HL7 v2 national profiles — German Profile, Australian Profile, Finnish Profile — that constrain the base US standard with country-specific value sets, required fields, and additional segments. VID.2 declares which profile applies.
National-profile version pinning. National profiles themselves evolve. VID.3 records the exact version of the national profile the sender conforms to, so receivers can apply the correct constraint set.

The international-code mechanism is the reason VID is a composite at all. A bare version number is sufficient for US-domestic exchange; cross-border and within-country-profiled exchange require all three components.

Component reference

Source: HAPI HL7v2 v2.8.1 javadocs — VID. VID has three components separated by ^. Length is not published in the javadocs (—).

Seq	Name	Data Type	Length	Req	Table	Description
VID.1	Version ID	id	—	R	[HL70104]	HL7 v2 version — `2.1`, `2.2`, `2.3`, `2.3.1`, `2.4`, `2.5`, `2.5.1`, `2.6`, `2.7`, `2.7.1`, `2.8`, `2.8.1`, `2.8.2`.
VID.2	Internationalization Code	cwe	—	O	[HL70399]	National profile identifier drawn from ISO country codes — `DE` Germany, `AU` Australia, `FI` Finland, `JP` Japan, etc. Composite (CWE) so it can carry display text and coding system.
VID.3	International Version ID	cwe	—	O	—	Version of the national profile identified by VID.2 — e.g. `2.5+i+DE 1.0` for the German Profile v1.0 against HL7 v2.5. Composite (CWE).

Most-used components

VID.1 Version ID — read first and read by every parser. The single most important version-control field in the entire message.
VID.2 Internationalization Code — present in national-profile traffic (German, Australian, Finnish profiles, etc.). Omitted in US-domestic exchange.
VID.3 International Version ID — present when VID.2 is present; pins the exact national-profile version. Omitted in US-domestic exchange.

Where it's used

VID appears in exactly one field across all of HL7 v2:

MSH-12 Version ID — the canonical home of VID. Every conforming v2.3+ message carries a VID in MSH-12.

That single placement is read by every parser before any other field in the segment graph — because the parser must know the version before it can correctly interpret any subsequent field's structure.

Version differences

v2.1 / v2.2 — No VID composite. MSH-12 was a plain ID field carrying 2.1 or 2.2.
v2.3 — VID composite introduced. VID.2 Internationalization Code and VID.3 International Version ID added.
v2.4 / v2.5 / v2.5.1 — No structural changes. New version values added to HL70104 as each version shipped.
v2.6 / v2.7 — VID.2 and VID.3 conformance descriptions refined to clarify their use for national-profile declaration.
v2.7.1 — Internationalization-code value set (HL70399) curated against ISO 3166 country codes.
v2.8 / v2.8.1 / v2.8.2 — Structurally stable. HAPI v2.8.1 javadoc shows three components, with VID.2 and VID.3 typed as CWE.

Common mistakes

Sending VID.1=2.5 with v2.8.1-only fields populated. The single most common VID bug: the sender uses a modern emitter library that populates fields introduced after v2.5 (CX.11 Security Check, CWE.14–CWE.22 OID/value-set, OBX-29 Observation Type) but declares VID.1=2.5. A receiver that trusts MSH-12 loads the v2.5 parser, the v2.5 parser does not know those fields exist, and either rejects the message or silently drops the data. Always emit the VID.1 that matches the actual structures populated.
Sending VID.1=2.8.1 to a receiver that only supports v2.5. The inverse problem: the sender legitimately conforms to v2.8.1 but the receiver has no parser for it. The receiver should reject the message; some receivers permissively retry against v2.5 and silently lose fields.
VID.2 populated without VID.3. A national-profile claim without a version is ambiguous — the German Profile has shipped multiple versions, and constraints differ between them.
VID.1 with leading zeros or padding. 02.8.1 and 2.08.1 are not in HL70104. The conformant values are exactly 2.8.1, 2.7.1, 2.5.1, etc.
Versions invented for internal use. 2.8.1-INTERNAL or 2.8.1+CUSTOM are non-conformant. Local extensions belong in a conformance profile referenced by MSH-21, not in MSH-12.
VID.1 mismatched against MSG.3. Declaring VID.1=2.8.1 with MSG.3=ADT_A04 (a structure ID that was canonical in earlier versions but is not the modern v2.7+ structure for A04) is internally inconsistent. Strict profiles flag this.

Examples

Minimal US-domestic value:

2.8.1

Earlier versions still in active production traffic:

2.3
2.3.1
2.4
2.5
2.5.1

National-profile values:

2.5^DE^DE 1.0           ; German Profile v1.0 against HL7 v2.5
2.7.1^AU^AU 2.1          ; Australian Profile v2.1 against HL7 v2.7.1
2.5.1^FI^FI 1.94         ; Finnish Profile v1.94 against HL7 v2.5.1

With explicit CWE coding-system on VID.2:

2.7.1^DE^HL70399^DE 1.0

In context — full MSH segment from a production v2.8.1 ADT^A01:

MSH|^~&|EMR|MERCY^2.16.840.1.113883.19.5^ISO|EHR|MERCY|20260624101530-0500||ADT^A01^ADT_A01|MSG-ADT-77321|P|2.8.1
EVN|A01|20260624101530-0500
PID|1||MR884412^^^MERCY&2.16.840.1.113883.19.5&ISO^MR||TESTPATIENT^ALEX^Q||19720508|F

In context — German Profile v2.5 message:

MSH|^~&|KIS|UKEHH^DE-UKEHH^L|LIS|UKEHH|20260624101530+0100||ADT^A01^ADT_A01|MSG-DE-001|P|2.5^DE^DE 1.0

Common pitfall — VID mismatched with payload:

MSH|^~&|EMR|MERCY|EHR|MERCY|20260624101530-0500||ADT^A01^ADT_A01|MSG-ADT-77321|P|2.5
PID|1||MR884412^^^MERCY&2.16.840.1.113883.19.5&ISO^MR||TESTPATIENT^ALEX^Q||19720508|F|||||||||||||||||||||||||||||||VAR^Variant^HL70445

VID.1=2.5 but the PID segment populates fields introduced after v2.5. A v2.5 parser does not know about those fields and will either reject the message or strip the trailing data without warning.

Common pitfall — leading-zero padding:

MSH|^~&|EMR|MERCY|EHR|MERCY|20260624101530-0500||ADT^A01^ADT_A01|MSG-ADT-77321|P|02.08.01

02.08.01 is not in HL70104. Strict parsers reject; lenient parsers may pattern-match it to 2.8.1 and proceed, which masks the underlying emitter bug.

FHIR mapping

The HL7 v2-to-FHIR Implementation Guide does not publish a per-datatype ConceptMap for VID. The version concept does not have a single canonical FHIR target because version selection in FHIR is per-resource (Resource.meta.profile) rather than per-message.

Conceptually:

HL7 v2	FHIR target
VID.1 Version ID	`MessageHeader.meta.tag` with system `http://terminology.hl7.org/CodeSystem/v2-0104` and code `2.8.1`
VID.2 Internationalization Code	`Bundle.meta.profile` referencing the national-profile FHIR IG, where one exists
VID.3 International Version ID	profile URL version anchor on `Bundle.meta.profile`

Round-tripping HL7 v2 → FHIR → HL7 v2 typically requires the converter to carry the original VID alongside the converted Bundle so the outbound HL7 emitter can reconstruct MSH-12 exactly. Without this, the round-trip loses the national-profile declaration.

Engine considerations

Parser selection. Receivers that support multiple versions must read MSH-12 before anything else and load the version-specific parser. HAPI exposes per-version parsers in distinct packages — ca.uhn.hl7v2.model.v25.* versus ca.uhn.hl7v2.model.v281.* — and the wrong choice silently corrupts every field-level access.
Version negotiation. Bi-directional interfaces should agree on a minimum version up front and reject messages claiming a higher version unless the receiver is known to support it. Permissive auto-downgrade is dangerous because it loses fields introduced after the downgrade version.
National-profile handling. VID.2-aware engines load the national-profile constraint set in addition to the base US standard. The constraint set typically narrows value sets (German Profile constrains race / ethnicity code systems to local registries) and requires fields that the base standard treats as optional.
Schema-version drift. Long-lived production interfaces sometimes ship with senders advancing to a newer version while receivers stay on an older one. VID.1 changing on a familiar interface should fire an alarm, not be silently accepted.
HAPI typing. ca.uhn.hl7v2.model.v281.datatype.VID exposes getVersionID() returning ID, and getInternationalizationCode() / getInternationalVersionID() returning CWE. Code that reads MSH-12 as a plain string misses VID.2 and VID.3 entirely.
Conformance profile cross-check. When MSH-21 (Conformance Profile Identifier) is also populated, the engine should cross-check it against VID — a conformance profile declared for v2.7 should not appear on a message claiming VID.1=2.5.

How Vorro parses and produces VID

Vorro treats VID as the primary parser key. On inbound, the very first action the message processor performs is reading MSH-12 to select the correct version-specific HAPI parser; only then is the rest of the segment graph touched. National-profile constraint sets are loaded lazily when VID.2 is present.

When VID.1 disagrees with the actual segment shapes (for example, a message claiming v2.5 that carries v2.7+ fields), Vorro records a profile-drift warning and routes the message to a quarantine queue rather than risking silent data loss in the v2.5 parser path.

On outbound, Vorro emits VID.1 from a per-destination configuration that is the negotiated minimum agreed at interface go-live; messages are never optimistically advanced to a newer version without explicit destination opt-in. VID.2 and VID.3 are emitted whenever the destination is configured for a national profile.

Sources

← Back to HL7 v2 Guide