Reference the HL7 v2 to FHIR mapping tables published in the HL7 FHIR specification (https://hl7.org/fhir/v2maps.html) and the HL7 v2 to FHIR Implementation Guide for validated field-level mappings.
Map the PID segment to a FHIR Patient resource: PID-3 → Patient.identifier[], PID-5 → Patient.name[], PID-7 → Patient.birthDate (reformatted), PID-8 → Patient.gender (with value translation: M→male, F→female, U→unknown).
Map the PV1 segment to a FHIR Encounter resource: PV1-2 patient class → Encounter.class (using HL7 v3 ActCode system), PV1-44 → Encounter.period.start, PV1-45 → Encounter.period.end.
Map OBX segments (observation results) to FHIR Observation resources: OBX-3 (observation identifier, usually LOINC) → Observation.code, OBX-5 (value) → Observation.value[x] (type based on OBX-2), OBX-11 (result status) → Observation.status.
Handle data type translation explicitly: CWE/CE (coded with exceptions) components map to FHIR CodeableConcept with coding[]; NM (numeric) maps to valueQuantity; TX/FT (text) maps to valueString.
Validate the mapped FHIR resources against the relevant profiles (US Core where applicable) and check for required fields that have no corresponding v2 source field.
Known gotchas
HL7 v2 to FHIR mappings are approximate; many v2 fields have no direct FHIR equivalent and require extensions or are intentionally dropped; do not assume all v2 data is mappable to standard FHIR.
Coded fields in HL7 v2 may use local coding systems that do not map to standard FHIR terminology; a terminology lookup or mapping table may be needed before populating FHIR CodeableConcept.coding.
The mapping is not reversible without data loss; FHIR resources have richer structure than v2 segments; round-trip conversion is not a safe assumption for operational workflows.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp