C-CDA on FHIR, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 2.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/ccda-on-fhir/ and changes regularly. See the Directory of published versions

Mapping General and Structural Guidance

Reading the C-CDA ↔ FHIR Mapping Tables

How to Read Mapping Tables and Transform Steps?

The header row of the mapping table provides links to the respective profiles in FHIR (e.g. US Core AllergyIntolerance) and templates in C-CDA (e.g. Allergy Intolerance observation)and specifies the "base" that each of the rows will build on. All FHIR elements use a simplified dot notation and the CDA elements use simplified slash notation. Always use the underlying standards, provided via header row links, to ensure conformance when building FHIR resources or C-CDA clinical documents.

Rather than repeating cardinality, conformance, and other criteria from FHIR Resources or a C-CDA templates defined outside this implementaiton guide, external references are shown in tables as bold hyperlinks (e.g. US Core Patient or C-CDA US Realm Header). Unbolded links refer to guidance contained within this guide (e.g. CDA ↔ FHIR Name, Address, and Telecom mapping). When criteria for selecting XML elements from C-CDA is required, you will see XPath notation with the respective criteria within brackets (e.g. /entryRelationship[@typeCode="MSFT"]).

The "Transform Steps" column of the table will provide guidance for mapping content between C-CDA and FHIR, those steps will be listed in the following order:

1. Constraint (labeled in bold): Only perform the action when this constraint is fulfilled
2. Structural Guidance (Bidirectional guidance shown as ↔): Generalized narrative guidance on structural transform between CDA and FHIR elements. This links to sections on this current page
3. ConceptMap (Terminology mapping direction shown as →): Link to a computable map between CDA and FHIR vocabularies. This links to conceptMaps developed in this guide
4. Notes (no label): Other notes specific to this element mapping

What Examples are Included?

Examples for C-CDA to FHIR transforms are provided based on a consensus of various vendors performing mappings. All vendors received the sample input (e.g. C-CDA Document) and generated output (e.g. FHIR Resource) which were then iterated through group discussion to a consensus. For FHIR to C-CDA, a single vendor provided examples which are included.

The highlighted output images were created using an open source tool for C-CDA ↔ FHIR Mapping developed as part of this project.

Missing Maps

If you have data in an input artifact that is defined in the source specification and for which no map is specified here, that means that this team did not find a target for which we could build consensus. In most cases, this means that the data is unusual enough that the target specification did not address it (e.g., treatments for allergy reactions, which would probably be reported in the Problems or Procedures section rather than the Allergies section). In these cases, the team felt that converging on one design from the many solution possible patterns was not an optimal investment of resources. If readers identify elements for which this seems insufficient, they should comment.

CDA id ↔ FHIR identifier

Identifiers in both FHIR and CDA can divide the identifier value from its namespace: FHIR as the identifier.system and CDA as the id.root. In many cases, this correspondence works well.

However, the FHIR system can be any URI, including OIDs & UUIDs as well as URLs. CDA roots must be UIDs, which consist of OIDs and UUIDs only. CDA roots can often be used as FHIR systems, but FHIR systems must often be translated. In some cases, the URI has a registered equivalent OID, for example, an identifier with a FHIR system of http://hl7.org/fhir/sid/us-ssn can be represented with a CDA root of 2.16.840.1.113883.4.1.

If there is no such OID, and if the FHIR identifier is a URL, we can use the URL specification itself as the system, and that specification - urn:ietf:rfc:3986 - has a registered OID equivalent, 2.16.840.1.113883.4.873. The FHIR identifier.value can be appended to the system for the CDA extension. These ids can be represented as below.

Cases where the FHIR system uses a scheme with no OID present a problem. The UID type is primitive, represented only as an XML attribute, and it cannot have a null flavor. One solution may be to generate a UUID, but expectations around the UUID's persistence and recognizability may vary.

CDA id → FHIR Identifier with Example Mapping

1. This approach should not be used for known identifier systems like SSN or NPI. Even if there is no nullFlavor, sending the system OID as a value is inappropriate.
2. UUIDs from CDA are uppercase (per Abstract Datatypes 2.1.5.1); UUIDs from FHIR are lowercase (per FHIR uri Datatype). Transform case when converting.
3. UUID's are unique by themselves and rarely have extensions, so this scenario is rare.
4. This is the URN OID equivalent of urn:ietf:rfc:3598. These examples are the reverse of the concatenation example listed below.

If a CDA id contains a @nullFlavor (or a known coding system such as SSN or NPI with no extension), a FHIR Identifier may be created using a data-absent-reason extension explaining the missing data. If the CDA id has a @root, place the extension on the Identifier.value element (for example, to indicate an unknown NPI); if the CDA id has only a @nullFlavor, the extension may be placed on the Identifier element itself.

FHIR Identifier → CDA id with Example Mapping

In some cases, a CDA template requires an id, and the source FHIR resource may not have an identifier. In these cases, use of nullFlavor or UUID generation approach may be reasonable options.

FHIR ids

FHIR ids (i.e. resource ids and element ids) are strings: they have no system. We propose not preserving them. They could be used in II.extension but we have no way to identify a root. If someone can ascertain a reliable, repeatable way to do that, we might be able to keep the id.

CDA ↔ FHIR Time/Dates

CDA timestamp values are based on a pattern of YYYYMMDDHHmmss+zzzz and FHIR dateTime values are based on a YYYY-MM-DDThh:mm:ss+zz:zz. Partial expressions (e.g. 202305 for CDA or 2023-05 for FHIR) are allowed in both standards.

To convert between the standards, systems should deploy programming logic that converts formats and preserves the level of precision. For example, "20230531" from CDA would become "2023-05-31" in FHIR (not 2023-05-31T00:00:00+00:00). Additional examples below:

Note that in C-CDA, timezone offset is a SHOULD, while in FHIR, time zone offset is required when more specific than the day. There may be instances where a CDA date-time value omits a time zone offset and other data from the document may be necessary to populate FHIR dateTime requirements.

The following are possible approaches to map CDA timestamps without offset to a FHIR dateTime or instant datatype. Selecting an approach depends on various factors including the criticality of the data, the age of the document, and the level of information the transformation process has about the location where the particular element was recorded.

• Omit the time portion of the date entirely, optionally sending the time as an extension or use the Uncertain period extension
  • Note - this only works for FHIR fields with a dateTime datatype; the instant datatype must be precise to the second
• Use the same offset as a different timestamp within the same entry or section (or ClinicalDocument/effectiveTime)
• Use contextual knowledge of the source document's location (e.g. if the document came from a health system serving only New England and the date was in December, the offset is likely "-05:00")
• Default the offset to 00:00

Beware that any approach which manufactures an offset could have clinical implications, but this is likely less critical the older (and thus, more likely to be missing offsets) the document is.

Structured types

Some CDA temporal fields can be either a single point-in-time or an interval range. When mapped to a FHIR dateTime or instant datatype, the value should be taken from either @value or low/@value. If mapped to a FHIR period, effectiveTime/low maps to period.start and effectiveTime/high maps to period.end.

CDA Coding ↔ FHIR CodeableConcept

The structure for coding in CDA and FHIR are fundamentally different. CDA employs a mechanism (xsi:type CD or CE) where the code is included in the element and then originalText and translations elements may be provided as child elements. In FHIR, CodeableConcept places all codes in a coding list with a separate element for the text representation.

Both C-CDA and FHIR stipulate that display/@displayName represents one of the display strings defined for that code by the code system. If a source contains other text, the transforming party may choose to send the system value in display, put that original value in text/<originalText> and put the system value in display, or simply send the source value.

CDA Coding → FHIR CodeableConcept

FHIR CodeableConcept → CDA Coding

In addition to the context of the previous section, CDA often requires elements to be present but the usage of a null value (@nullFlavor) is allowed. Generally when a CDA element is required (i.e. SHALL [1..1]), implementers will need to do one of the following when converting data into CDA:

• If the data fulfills the target valueset, use the code and translate system
• If the data can be mapped into the target valueset, use a mapping and the translated system
• When the above is not possible:
  • If you have coded data and CDA nullFlavor is allowed, use "OTH" and put the source data in translation and provide originalText if possible. Note that CD and CE CDA elements generally allow translation and originalText.
  • If you have missing data with data-absent-reason, use a mapped nullFlavor if allowed. If not allowed, find the best match in the permitted valueset.
  • If you have missing data without data-absent-reason, select a nullFlavor if allowed. If not allowed, find the best match in the permitted valueset.

Note that C-CDA sometimes requires a code from a specific system in the root of a CD and permits others in the translation

FHIR Code → CDA Coding

Both CDA and FHIR employ a hierarchy of simpler types and more complex types that re-use the simpler ones. In some cases, a simpler type on one side will map to a more complex one on the other. Where the complexity supports metadata, these maps are essentially the same as the complex-to-complex maps (Coding & CodeableConcept, above). In a few cases, a complex type supports representing a simple source where a simple target would have failed.

Mapping OID ↔ URI

FHIR requires that certain terminologies use a specific uniform resource identifier (URI) while CDA always uses object identifiers (OIDs) for codeSystems. This means:

• For CDA → FHIR mapping
  • Translation to URIs is required where possible. One source of translations is available in FHIR terminologies which also includes information about other sources of translation.
  • For OIDs that have no URI equivalent is known, add the urn:oid: prefix to OID
• For FHIR → CDA mapping
  • Translation of URIs to OIDs is always required for FHIR → CDA mapping
  • Remove urn:oid: prefix for OIDs

Two example are shown in the table below. Since LOINC is a terminology with a defined URI in FHIR, it is not allowed to add urn:oid: when mapping from CDA (urn:oid:2.16.840.1.113883.6.1). This is allowed, however, for other terminologies where no URI is known.

Additional guidance on FHIR terminologies available here.

OriginalText

The <originalText> element in CDA can contain mixed XML content or a reference to a portion of the narrative. When converting to a FHIR data type that contains a text field, like CodeableConcept, this is a direct map. For other cases, the originalText extension may be used to convey this information. In either instance, the CDA narrative must be de-referenced, any markup removed, and stored as plain text into CodeableConcept.text or the originalText's .valueString.

FHIR also includes a narrativeLink extension which functions similarly to the <reference value="#..."> attribute underneath originalText. If the section or resource narrative has been converted to FHIR (see Narrative Text), this extension can be added to indicate the portion of narrative corresponding to the extended FHIR field.

CDA ↔ FHIR Quantity

CDA and FHIR have similar quantity data types. Both contain a numeric value, but CDA contains a single unit attribute which must be a UCUM (Unified Code for Units of Measure) code, while FHIR contains a free-text unit field and a pair of fields, code and system, which together can store a UCUM value.

When mapping from CDA to FHIR, the unit is already UCUM, so it can be represented in both the code and value fields:

When mapping from FHIR to CDA, if the system is http://unitsofmeasure.org, the code can map directly to CDA's @value. But if there is no code or system, or the system is something besides UCUM, the unit can only be placed in CDA's @unit after ensuring it is a valid UCUM unit. If the unit cannot be converted to UCUM, then the <translation> element available on CDA's PQ data type can be used, as demonstrated in the C-CDA Example Task Force's Results Unit Non-UCUM example. The FHIR unit value can be placed in translation/originalText, and the code and system can be placed in the translation's @code and @codeSystem attributes (if the URI can be mapped to an OID).

"quantity": {
  "value": 30,
  "unit": "each",
  "code": "EA",
  "system": "http://terminology.hl7.org/CodeSystem/standardBillingUnit"
}

<!-- This could also be used in other places like substanceAdministration/doseQuantity -->
<value xsi:type="PQ" nullFlavor="OTH">
  <translation value="30" code="EA" codeSystem="2.16.840.1.113883.2.13">
    <originalText>each</originalText>
  </translation>
</value>

"quantity": {
  "value": 25,
  "unit": "customUnits"
}

<value xsi:type="PQ" nullFlavor="OTH">
  <translation value="25" nullFlavor="OTH">
    <originalText>customUnits</originalText>
  </translation>
</value>

UCUM also provides the ability to include arbitrary units within a set of curly brackets (e.g. {INR}). No specific guidance on the use of curly brackets in unit translation is provided in this publication, however additional guidance on UCUM arbitrary units is available here.

Ranges of Physical Quantities

CDA conveys ranges of values using the IVL_PQ data type. The <low> and <high> elements are normal Physical Quantity (PQ) elements with an additional @inclusive attribute. When this is present and set to "false", the value of the boundary is not included in the range. The default value of this attribute is "true", so regardless of whether it is absent or set to "true", the value of the boundary IS included in the range.

In FHIR, ranges with both a low and high are represented in the Range data type, while ranges with only a low or a high are represented in the Quantity data type using a comparator.

Since a physical quantity is something that can be measured, a missing <low> value or a low value of 0 can be represented as < or <= the high value (based on the @inclusive property on <high>). If the <high> value is missing, it generally means the value was too large to measure, and the FHIR representation is > or >=.

Note that in FHIR, Observation.referenceRange only contains .low and .high values, so this guidance is targeted to the actual values of observations.

<value xsi:type="IVL_PQ">
  <high value="200" unit="mg/dL"/>
</value>

<value xsi:type="IVL_PQ">
  <low value="0" unit="mg/dL"/>
  <high value="200" unit="mg/dL"/>
</value>

<value xsi:type="IVL_PQ">
  <low nullFlavor="NINF"/>
  <high value="200" unit="mg/dL"/>
</value>

"quantity": {
  "value": 200,
  "comparator": "<=",
  "unit": "mg/dL",
  "code": "mg/dL",
  "system": "http://unitsofmeasure.org"
}

<value xsi:type="IVL_PQ">
  <high value="200" unit="mg/dL" inclusive="false"/>
</value>

"quantity": {
  "value": 200,
  "comparator": "<",
  "unit": "mg/dL",
  "code": "mg/dL",
  "system": "http://unitsofmeasure.org"
}

<value xsi:type="IVL_PQ">
  <low value="500" unit="mg/dL" inclusive="true"/>
  <high nullFlavor="PINF">
</value>

<value xsi:type="IVL_PQ">
  <low value="500" unit="mg/dL"/>
</value>

"quantity": {
  "value": 500,
  "comparator": ">=",
  "unit": "mg/dL",
  "code": "mg/dL",
  "system": "http://unitsofmeasure.org"
}

<value xsi:type="IVL_PQ">
  <low value="500" unit="mg/dL" inclusive="false"/>
  <high nullFlavor="PINF"/>
</value>

<value xsi:type="IVL_PQ">
  <low value="500" unit="mg/dL" inclusive="false"/>
</value>

"quantity": {
  "value": 500,
  "comparator": ">",
  "unit": "mg/dL",
  "code": "mg/dL",
  "system": "http://unitsofmeasure.org"
}

<value xsi:type="IVL_PQ">
  <low value="200" unit="mg/dL"/>
  <high value="1000" unit="mg/dL"/>
</value>

"range": {
  "low": {
    "value": 200,
    "unit": "mg/dL",
    "code": "mg/dL",
    "system": "http://unitsofmeasure.org"
  },
  "high": {
    "value": 1000,
    "unit": "mg/dL",
    "code": "mg/dL",
    "system": "http://unitsofmeasure.org"
  }
}

<value xsi:type="IVL_PQ">
  <low value="200" unit="mg/dL"/>
  <high value="1" unit="g/dL"/>
</value>

"range": {
  "low": {
    "value": 200,
    "unit": "mg/dL",
    "code": "mg/dL",
    "system": "http://unitsofmeasure.org"
  },
  "high": {
    "value": 1,
    "unit": "g/dL",
    "code": "g/dL",
    "system": "http://unitsofmeasure.org"
  }
}

CDA ↔ FHIR Provenance

CDA provides a repeated set of elements within each activity which may be used in populating data to/from FHIR Provenance.Agent

• author: Represents the humans and/or machines that authored the [document/section/entry/act].
• performer: A person who actually and principally carries out an action.
• informant: An informant (or source of information) is a person that provides relevant information, such as the parent of a comatose patient who describes the patient's behavior prior to the onset of coma.
• participant Used to represent other participants not explicitly mentioned by other classes, that were somehow involved in the documented activities

FHIR, however, provides different elements within resources (e.g. Condition.recorder) that convey some information on provenance and a dedicated Provenance resource which references a target resource. In addition, FHIR documents do not provide context conduction, so all FHIR resources in a FHIR document should have explicit Provenance. See Context conduction under v3 Similarities and Differences for more information.

At a minimum, it is recommended that when Provenance resources are present in a FHIR document, that they should be mapped to provenance as defined in the C-CDA Companion Guide and Basic Provenance in US Core.

Preliminary guidelines for documents may include:

1. Assembler generated documents
   • entity.what reference either a DocumentReference or DiagnosticReport
   • agent.type.coding.code = assembler
   • agent.onBehalfOf reference the Organization that the document was assembled under the auspices of
2. Device generated document templates
   • entity.what reference either a DocumentReference or DiagnosticReport
   • agent.type.coding.code = assembler
   • agent.onBehalfOf reference the Organization that the document was assembled under the auspices of
   • A role of Informant is not permitted in Device Generated Document template.
3. Patient Generated Document
   • entity.what reference either a DocumentReference or DiagnosticReport
   • agent.type of author
   • agent.who reference to the Patient. Optionally, it may include a participating device composer when created from a patient portal, and/or a participating assembeler; or a participating informant.
   • onBehalfOf valued to the authorizing provider's organization
4. Provider Generated Document
   • entity.what reference either a DocumentReference or DiagnosticReport
   • agent.type of author
   • agent.who reference the Practitioner or PractitionerRole (when organization is included along with roles form the source C-CDA)
   • onBehalfOf reference to an Organization that the provider is authorized by

Name, Address, Telecom

The mappings of name, address and telecom information are useful in many part of C-CDA ↔ FHIR mapping. These are a combination of string, code and date mappings as shown below and may be re-used across many templates/resources. For examples of these transformations, please see the CDA → FHIR Patient mapping and FHIR → CDA Patient mapping pages.

CDA name → FHIR name

CDA addr → FHIR address

CDA telecom → FHIR telecom

FHIR name → CDA name

FHIR address → CDA addr

FHIR telecom → CDA telecom

Missing Data in C-CDA vs. FHIR

CDA and FHIR address missing data and null usage in different ways:

• The use of nullFlavor in CDA is explained in depth in Volume 1 of the C-CDA Implementation Guide and in the C-CDA Companion Guide.
• The use of the data absent reason extension is explained in depth in the US Core Implementation Guide and also in the base extension.

In this publication, we include a mapping between missing data concepts. Importantly, it should be noted that several mappings include non-equivalence (wider or narrower or unsupported) and that each standard may allow data elements to be omitted while the other requires. Feedback to improve implementer guidance is welcome on the handling of missing data between C-CDA and FHIR:

• NullFlavor (CDA) → Data Absent Reason code (FHIR)
• Data Absent Reason code (FHIR) → NullFlavor (CDA)

Comment → Annotation

The CDA Comment Activity template is used for text notes accompanied by their author. The FHIR Annotation datatype can capture text and an author as well.

Narrative Text

The CDA section narrative text is an authoritative portion of the document and must be preserved when transforming to FHIR. When creating a FHIR Composition resource (or converting a FHIR Composition back into CDA), this is a straightforward mapping between CDA's section/text and the FHIR Composition section.text field. There is a slight difference in allowed elements - CDA defines a limited set of elements in its NarrativeBlock schema, and FHIR limits narratives to a subset of XHTML - but these two fields can generally be mapped 1:1. These differences are described below.

C-CDA Entry/Text → FHIR Resource.text

When mapping C-CDA entires to individual FHIR resources, the entry text should also be converted to a FHIR narrative. Every CDA ClinicalStatement (e.g. <act>, <observation>, <encounter>, etc) contains a <text> field, and C-CDA Volume 1 contains the following constraint which is applied to all of these ClinicalStatements:

SHOULD contain zero or one [0..1] text
   a. The text, if present, SHOULD contain zero or one [0..1] reference/@value
     i. This reference/@value SHALL begin with a '#' and SHALL point to its corresponding narrative (using the approach defined in CDA R2.0, section 4.3.5.1)

When this element is present on a C-CDA entry, the FHIR resource SHOULD be created with a narrative (.text) corresponding to the portion of the section narrative referenced by the reference/@value attribute. This attribute will match an @ID attribute on an element in the section narrative. That element and all of its children should be used as the basis for the FHIR resource's narrative. Additionally, the <text> node may contain mixed content alongside the <reference> element. In this case, the FHIR resource should also include the mixed content in its narrative.

NOTE: Sometimes the @ID element will appear on a portion of a table, such as a <tr> or a <td>, or some other narrative element like <item> which may not stand well on its own when converted to XHTML. When a situation like this occurs, include appropriate context from other elements outside the primary element containing @ID. For example, if the @ID appears on a <tr>, create a table for the FHIR resource narrative and repeat the header row(s) before including the <tr>.

Example mappings - assume CDA narrative contains an element with ID="id1" that contains "tagged text".

<act>
  <text>
    <reference value="#id1">
  </text>
</act>

<div xmlns="http://www.w3.org/1999/xhtml">
  tagged text
</div>

<act>
  <text>Mixed content</text>
</act>

<div xmlns="http://www.w3.org/1999/xhtml">
  Mixed content
</div>

<act>
  <text>Mixed with reference!
    <reference value="#id1">
  </text>
</act>

<!-- Surrounding either part with an extra <div> is
     one possible suggestion to improve readability -->
<div xmlns="http://www.w3.org/1999/xhtml">
  Mixed with reference!
  <div>tagged text</div>
</div>

FHIR Resource.text → C-CDA Section Narratives

If a FHIR Composition is being converted to CDA, its section.text can be converted to CDA section/text directly. If FHIR resources are being assembled into a new document, the narrative from each resource included in a section should be included as that section's text, as well as referenced from the specific C-CDA entry created from the conversion.

Difference between CDA Narrative and FHIR Narrative

The following is general guidance for mapping CDA Narrative elements and attributes to XHTML used by FHIR. For a specific example, see the informative CDA R2 Stylesheet. Table elements (<table>, <thead>, <tbody>, <tfoot>, <colgroup>, <col>, <tr>, <td>, <th>) are not included in the table because they are generally the same between CDA Narrative and XHTML.

The reverse conversion (from FHIR HTML to CDA Narrative) is also possible, but only the elements allowed by the CDA Narrative may be used.

Though included in NarrativeBlock.xsd, the Title, TitleContent, and TitleFootnote elements are not actually used in CDA Narrative text.

Terminology Mapping

Access terminology mappings between C-CDA and FHIR