Committee Approval Date:

Order & Observations: March 5, 2020 - Minutes: 2020-03-05 - Main

Publishing Lead:

Keith Boone

Contributing or Reviewing Work Groups:

Orders & Observations, Patient Administration, Financial Management, Infrastructure & Messaging, Modeling & Methodology, FHIR-I

v2 Management Group, FMG

Development Project Insight ID:


Scope of coverage:

The Implementation Guide provides standard mapping between HL7 v2 elements (messages, segments, data types, vocabulary) to HL7 FHIR components (resources, data types, vocabulary) where there is known, actual usage of HL7 v2 elements.

The initial scope focuses on a small representative set of commonly used HL7 v2 messages, while it will expand over time in subsequent versions to all actively used HL7 v2 elements. 

The main focus is on establishing agreed to mappings, but the implementation guide also includes downloadable, computable mappings for mapping engines to ingest, as well as a Bundle message profile to establish minimum guidance when the HL7 v2 message is being expressed in an equivalent HL7 FHIR message for subsequent communication with the final receiver.

The scope initially does not include HL7 FHIR to HL7 v2 mappings.  While many mappings can be reversed as-is, that is not the case in all situations and would require additional/different guidance.  This aspect may be addressed in a future version through a separate project.

Content location:

Proposed IG realm and code:



Maintenance Plan:

OO will work with relevant workgroups to update the v2-to-FHIR Mappings IG as new versions of HL7 v2 and FHIR are being published.

The goal is that this will be as concurrent as possible after the initial release is published, while building out the full scope of actually used HL7 v2 elements over time as well.

Short Description:

The HL7 V2 to FHIR Implementation Guide supports the mapping of HL7 Version 2 messages segments, datatypes and vocabulary to HL7 FHIR Release 4.0 Bundles, Resources, Data Types and Coding Systems.

Long Description:

This implementation guide provides the mappings of HL7 Version 2 messages segments, datatypes and vocabulary to HL7 FHIR Release 4.0 Bundles, Resources, Data Types and Coding System, as well as the FHIR Concept Maps and references to the Mapping Spreadsheets used to edit and generate the downloadable content, and any additional information and material to support validation and testing of implementations.

This guide is organized into six main sections:

  1. Introduction
    This section provides an overview of the project, and explains how mapping is performed.

  2. Mapping Guidelines
    This section provides the rules and guidelines used to document the mappings such as identification of each HL7 v2 element with a mapping, the conditions under which the HL7 v2 element may map to one or more HL7 FHIR components, as well references to more specific mappings considering context, e.g., when to map PID data to Patient vs. RelatedPerson, or a CWE encoded element to either CodeableConcept, Coding, or code.
  3. Mappings
    This section provides an index to the mappings produced by this project, organized by message, segment, datatype, or vocabulary mapping.

  4. Implementation and Use
    This section covers implementation considerations and validation, and provides example test conversions.

  5. Profiles
    This section provides the profiles for the HL7 FHIR ConceptMap that describes the data maintained in Concept Maps for each of the message, segment, data type, and vocabulary mapping, as well as a profile for HL7 FHIR Bundle that establishes the basic structure/content of a HL7 FHIR message resulting from an HL7 v2 message.
    This section provides downloadable content of the entire guide, specific mappings, and examples in either json, xml, ttl, or csv format. 

Involved parties:

HL7 workgroups that own HL7 v2 chapters, primarly OO, PA, FM, and InM, 

EHR and integration/mapping engine vendors, such as Allscripts, Altarum, Audicious Inquiry, CDC, Cerner, Charteris Consulting, Google, LabCorp, Microsoft

Providers such as Ascension.

Expected implementations:

Mapping engines are expected to ingest the mappings to establish an initial model, from which they can tailor for local implementations.

Organizations listed above are progressing efforts to use the mappings in their solutions.

Content sources:

HL7 v2


Example Scenarios:


  • ADT_A01 message mapping to FHIR resources such as MessageHeader, Patient, Encounter.
  • PID segment mapping to Patient and RelatedPerson
  • CWE data type mapping to CodeableConcept, Coding, and code

Mapping Ingestion

  • Integration engine ingesting the mappings to establish model maps that then are further localized on specific

IG Relationships:



Initial content ballot: May, 2020
Second content ballot for first version publication: September, 2020

FMG Notes