Skip to main content
Two modes — strict for spec compliance, compatibility for real-world vendor tolerance — across three standards and eight HL7 versions.

Strict Mode

Every required field, data type, and code set is checked against the base specification. Use when building new interfaces or certifying compliance.

Compatibility Mode

Tolerates common vendor deviations. Use when testing against live systems where real-world messages deviate from spec.

​
Standards Coverage

StandardVersionsWhat’s Validated
HL7 v2v2.3, v2.4, v2.5, v2.5.1, v2.6, v2.7, v2.8Segment structure, required fields, data types, code sets, segment ordering
FHIR R4R4Required elements, cardinality, terminology bindings, 21 resource types, profile constraints
NCPDP SCRIPT2017071Transaction structure, NPI Luhn check, DEA format validation, required fields

​
Usage

pidgeon validate --file message.hl7 --mode strict
pidgeon validate --folder ./inbox --mode compatibility --profile epic_er

​
Example Output

Validating admit.hl7 with Strict mode...
ERROR: Validation failed with 2 error(s):
  HL7-TABLE-001: Field PV1.2 value 'Z' is not a valid code in HL7 table 0004 (Patient Class)
    Location: PV1.2
    Expected: One of: E (Emergency), I (Inpatient), O (Outpatient), P (Preadmit), R (Recurring)
    Actual:   Z
    Fix:      Use a valid value from HL7 table 0004 (Patient Class)
    Tip:      pidgeon lookup PV1.2

  HL7-REQ-001: Required field PID.5 (Patient Name) is missing or empty
    Location: PID.5
    Expected: Non-empty value of type XPN (Extended Person Name)
    Actual:   (empty)
    Fix:      Populate PID.5 with a valid XPN value
    Tip:      pidgeon lookup PID.5

WARNING: Warnings: 1
  HL7-REQ-002: Field EVN.1 (Event Type Code) is empty
    Location: EVN.1
    Tip:      pidgeon lookup EVN.1

Summary: 87 fields checked, 84 of 86 rules passed (97.7% conformance) in 3ms
Each validation issue includes the expected value, actual value, a fix suggestion, and a pidgeon lookup tip that opens the built-in standards reference for that field. Run pidgeon lookup PID.5 to see the full field definition, data type, valid values, and vendor-specific notes.

​
Structured Output for CI/CD

pidgeon validate --file message.hl7 --mode strict --output json
Returns the full ValidationResult as JSON — including isValid, all issues with diagnostic fields (expectedValue, actualValue, suggestion), and summary statistics (fieldsValidated, conformanceScore, validationTime). Exit code 0 on pass, 1 on fail.

​
Vendor Profile Validation

Validate against your vendor’s actual patterns instead of just the spec: 
pidgeon validate --file test.hl7 --profile epic_er
Compatibility mode with a vendor profile catches the issues that matter in your specific environment — not just spec violations, but deviations from how your vendor actually sends messages. See Vendor Profiles.