HL7 v2 message structure (segments, groups, cardinality)
An HL7 v2 message is an ordered sequence of segments, each a line starting with a 3-character code (MSH, PID, PV1) and ending with a carriage return. The message type in MSH-9 (message code ^ trigger event ^ abstract structure, e.g. ADT^A01^ADT_A01) names an abstract message structure that defines which segments appear, in what order, whether each is required or optional, whether it repeats, and how segments nest into groups (an ORU result groups OBX observations under the OBR order that produced them).
| Segment | One line, 3-character code, fields separated by | |
|---|---|
| Message type | MSH-9: message code ^ trigger event ^ abstract structure |
| Cardinality | Per segment: required or optional, repeating or single |
| Groups | Named nestings of segments that repeat together (e.g. an order group with its observations) |
| First segment | Always MSH, which declares the delimiters, type, version, and control ID |
Example
MSH|^~\&|PIDGEON^^L|PIDGEON_FACILITY|TARGET^^L|TARGET_FACILITY|20260722160847||ADT^A01^ADT_A01|984078|P|2.3||||||8859/8|zh^Chinese^ISO639^^^
EVN|A01|20260720052826|20260722160847|03|ID744093^Tillman^Sheilah^^^^^^^A^6^M11^MS^|
PID|1||EA1VOECPYL^9^ISO^^MS|EA1VOECPYL^9^ISO^^MS|Byrd^Rodolfo^^^^^^^|Jones^Jayne^^^^^^^|19360121||Byrd^Rodolfo^^^^^^^||258 Walnut Street^^Boston^AZ^10001^USA^H^^^||^BPN^PH^individual389@healthcare.org^35|(412)735-2985^ORN^BP^^57^^^^|de^German^ISO639^^^|M||EA1VOECPYL^9^ISO^^MS|||ID366900^9^M11^^DS^|GBR|Y|Y|79||ID932834^^^ID398632^^|CAN^Canada^ISO3166^^^|20260722160847|The first 3 segments of an engine-generated ADT^A01 (`pidgeon generate ADT^A01 --seed 42`, HL7 v2.3; the full message continues with PV1, OBX, DG1, GT1, IN1 and more; timestamps vary per run). MSH-9's third component names the abstract structure ADT_A01 that defines the segment order and cardinality the rest of the message follows.
Validation context
- strict Strict mode checks each field against its published length; the generated MSH-9 above (15 characters against a v2.3 max of 7) raises a length warning with a per-field fix suggestion.(HL7-LEN-001)
This answer, in your terminal
pidgeon lookup PIDWire it into your AI agent:
claude mcp add pidgeon -- npx -y @pidgeonhealth/mcpDownload Post free to browse this reference with generation attached.