HL7 v2 Z-segments (locally defined segments)
A Z-segment is any segment whose 3-character code starts with Z. The letter Z is reserved by the standard for locally defined content: the segment's fields, datatypes, and meaning are agreed bilaterally between the sending and receiving systems, not published in the specification. Z-segments are how vendors carry data the standard has no field for, and they are one of the most common sources of interface-onboarding surprises.
| Naming | Any code starting with Z (ZPI, ZIN, ZOR...); the rest is the implementer's choice |
|---|---|
| Defined by | The interface partners, in an interface specification, never the HL7 standard |
| Parsing | Delimiters and encoding rules still apply; only the field semantics are local |
| Placement | Wherever the interface spec says; commonly after the standard segment they extend |
Example
MSH|^~\&|PIDGEON^^L|PIDGEON_FACILITY|TARGET^^L|TARGET_FACILITY|20260722160847||ADT^A01^ADT_A01|984078|P|2.3||||||8859/8|zh^Chinese^ISO639^^^
...standard segments...
ZPI|1|CUSTOM^Vendor extension data|20260722The MSH line is engine output (`pidgeon generate ADT^A01 --seed 42`); the ZPI line is a hand-authored local segment appended to show the shape. Running the combined message through pidgeon validate produced the mode behavior recorded below.
Validation context
- strict Strict mode flags an unrecognized Z-segment with a warning: no schema is available to validate it, so its contents pass unchecked.(HL7-SEG-UNKNOWN)
- compatibility Compatibility mode accepts unknown Z-segments without a finding, matching how production interfaces treat locally defined content.
This answer, in your terminal
pidgeon validate message.hl7 --mode strictWire it into your AI agent:
claude mcp add pidgeon -- npx -y @pidgeonhealth/mcpDownload Post free to browse this reference with generation attached.