C-CDA on FHIR
2.0.0-ballot - STU 2 Ballot
C-CDA on FHIR
2.0.0-ballot - STU 2 Ballot
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
This page provides a mapping from CDA to FHIR. For the FHIR to CDA mapping, please refer to Patient FHIR → CDA. For guidance on how to read the table below, see Reading the C-CDA ↔ FHIR Mapping Pages
| C-CDA¹ US Realm Header recordTarget |
FHIR Patient |
Transform Steps |
|---|---|---|
| /id | .identifier | CDA id ↔ FHIR identifier |
| /addr | .address | CDA addr ↔ FHIR address |
| /telecom | .telecom | CDA telecom ↔ FHIR telecom |
| /patient/name | .name | CDA name ↔ FHIR name |
| /patient/administrativeGenderCode | .gender | CDA coding ↔ FHIR CodeableConcept CDA administrativeGender → FHIR gender |
| /patient/birthTime | .birthDate | CDA ↔ FHIR Time/Dates Note: the FHIR birthDate element is less precise than the CDA birthtime element. Precision can be preserved by also using the extension patient-birthTime. |
| /patient/sdtc:deceasedInd | .deceasedBoolean | Note: Only one of deceasedBoolean or deceasedDateTime may exist. If both are present in CDA, use deceasedDateTime. |
| /patient/sdtc:deceasedTime | .deceasedDateTime | CDA ↔ FHIR Time/Dates |
| /patient/maritalStatusCode | .maritalStatus | CDA coding ↔ FHIR CodeableConcept |
| /patient/religiousAffiliationCode | .extension:patient-religion.valueCodeableConcept | CDA coding ↔ FHIR CodeableConcept |
| /patient/raceCode | .extension:us-core-race: ombCategory | CDA coding ↔ FHIR CodeableConcept This should be a category and map to the ombCategory sub-extension. But if it is a detailed race, then it should go in the detailed sub-extension. |
| /patient/sdtc:raceCode | .extension:us-core-race | CDA coding ↔ FHIR CodeableConcept If code is in OMB category, use us-core-race: ombCategory; else use us-core-race: detailed. If the detailed race is under a different OMB category that the non-sdtc:raceCode element, then an additional OMB category sub-extension should be included as well. |
| /patient/raceCode/originalText and /patient/sdtc:raceCode/originalText |
.extension:us-core-race: text | The race extension's text sub-extension is required but may only exist once. Recommendation is to comma-delimit all originalText / displayNames available, taking care to not duplicate values. |
| /patient/ethnicGroupCode | .extension:us-core-ethnicity | CDA coding ↔ FHIR CodeableConcept This should be a category and map to the ombCategory sub-extension. But if it is a detailed race, then it should go in the detailed sub-extension. |
| /patient/sdtc:ethnicGroupCode | .extension:us-core-ethnicity : detailed | CDA coding ↔ FHIR CodeableConcept Used for detailed ethnicity |
| /patient/guardian/code and /patient/guardian/guardianPerson/sdtc:asPatientRelationship/code |
.contact.relationship | First, add a fixed relationship code of GUARD from v3 RoleCode (http://terminology.hl7.org/CodeSystem/v3-RoleCode) to preserve the CDA guardian relationship. Then map the two fields to additional relationship entries using CDA coding ↔ FHIR CodeableConcept |
| /patient/guardian/addr | .contact.address | CDA addr ↔ FHIR address |
| /patient/guardian/telecom | .contact.telecom | CDA telecom ↔ FHIR telecom |
| /patient/guardian/guardianPerson/name | .contact.name | CDA name ↔ FHIR name |
| /patient/birthPlace/place/addr | .extension:patient-birthPlace.valueAddress | CDA addr ↔ FHIR address |
| /patient/languageCommunication/languageCode | .communication.language | |
| /patient/languageCommunication/preferenceInd | .communication.preferred | |
| /patient/languageCommunication/modeCode | .communication.extension:patient-proficiency:type | CDA coding ↔ FHIR CodeableConcept If both modeCode and proficiencyLevelCode are set for a language, only one patient-proficiency extension is needed. |
| /patient/languageCommunication/proficiencyLevelCode | .communication.extension:patient-proficiency:level | CDA coding ↔ FHIR CodeableConcept If both modeCode and proficiencyLevelCode are set for a language, only one patient-proficiency extension is needed. |
| /providerOrganization | .managingOrganization |
1. XPath abbrievated for C-CDA US Realm recordTarget as:
ClinicalDocument/recordTarget/patientRole
| CDA RecordTarget Example | FHIR Patient Resource |
|---|---|
|
<recordTarget>
<patientRole>
<id root="068F3166-5721-4D69-94ED-8278FF035B8A" />
<addr use="H">
<streetAddressLine>1357 Amber Drive</streetAddressLine>
<city>Beaverton</city>
<state>OR</state>
<postalCode>97006</postalCode>
</addr>
<telecom value="tel:+1(565)867-5309" use="MC"/>
<patient>
<name use="L">
<given>Myra</given>
<family>Jones</family>
</name>
<administrativeGenderCode
code="F"
codeSystem="2.16.840.1.113883.5.1" />
<birthTime value="19470501" />
<sdtc:deceasedInd value="false" />
<maritalStatusCode
code="M"
displayName="Married"
codeSystem="2.16.840.1.113883.5.2"
codeSystemName="MaritalStatus"/>
<religiousAffiliationCode
code="1013"
displayName="Christian (non-Catholic, non-specific)"
codeSystem="2.16.840.1.113883.5.1076"
codeSystemName="HL7 Religious Affiliation"/>
<raceCode
code="2106-3"
codeSystem="2.16.840.1.113883.6.238"
displayName="White" />
<sdtc:raceCode
code="2108-9"
displayName="European"
codeSystem="2.16.840.1.113883.6.238" />
<ethnicGroupCode
code="2135-2"
codeSystem="2.16.840.1.113883.6.238"
displayName="Hispanic or Latino" />
<sdtc:ethnicGroupCode
code="20146-9"
displayName="Spanish Basque"
codeSystem="2.16.840.1.113883.6.238" />
<guardian>
<code
code="FTH"
displayName="father"
codeSystem="2.16.840.1.113883.5.111"
codeSystemName="RoleCode" />
<addr use="H">
<streetAddressLine>123 main street</streetAddressLine>
<city>Beaverton</city>
<state>OR</state>
<postalCode>97867</postalCode>
</addr>
<telecom value="tel:+1(555)555-2008" use="MC" />
<guardianPerson>
<name>
<given>Boris</given>
<given qualifier="CL">Bo</given>
<family>Betterhalf</family>
</name>
</guardianPerson>
</guardian>
<birthplace>
<place>
<addr>
<streetAddressLine>4444 Birth Street</streetAddressLine>
<city>Beaverton</city>
<state>OR</state>
<postalCode>97867</postalCode>
</addr>
</place>
</birthplace>
<languageCommunication>
<languageCode code="en" />
<modeCode
code="ESP"
displayName="Expressed spoken"
codeSystem="2.16.840.1.113883.5.60"
codeSystemName="LanguageAbilityMode"/>
<proficiencyLevelCode
code="G"
displayName="Good"
codeSystem="2.16.840.1.113883.5.61"
codeSystemName="LanguageAbilityProficiency"/>
<preferenceInd value="true" />
</languageCommunication>
</patient>
<!-- Creates reference: Organization/PCPartnersTest -->
<providerOrganization>
<id extension="3" root="1.3.6.1.4.1.22812.3.2009316.3" />
<name>Primary Care's Partners Test</name>
<telecom use="WP" value="tel:+1-(676)857-6769" />
</providerOrganization>
</patientRole>
</recordTarget>
|
{
"resourceType": "Patient",
"id": "6581e92eb6ff5dadc088eae5",
"identifier": [{
"system": "urn:uuid:068f3166-5721-4d69-94ed-8278ff035b8a",
"value": "urn:ietf:rfc:3986"
}],
"language": "en-US",
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/patient-religion",
"valueCodeableConcept": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ReligiousAffiliation",
"code": "1013",
"display": "Christian (non-Catholic, non-specific)"
}]
}
}, {
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
"extension": [{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2135-2",
"display": "Hispanic or Latino"
}
}, {
"url": "text",
"valueString": "Hispanic or Latino, Spanish Basque"
}, {
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "20146-9",
"display": "Spanish Basque"
}
}]
}, {
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension": [{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
}, {
"url": "text",
"valueString": "White, European"
}, {
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2108-9",
"display": "European"
}
}]
},
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-birthPlace",
"valueAddress": {
"line": ["4444 Birth Street"],
"city": "Beaverton",
"state": "OR",
"postalCode": "97867"
}
}],
"name": [{
"text": "Myra Jones",
"use": "usual",
"family": "Jones",
"given": ["Myra"]
}],
"telecom": [{
"system": "phone",
"value": "+1(565)867-5309",
"use": "mobile"
}],
"gender": "female",
"birthDate": "1947-05-01",
"deceasedBoolean": false,
"address": [{
"use": "home",
"text": "1357 Amber Drive Beaverton OR 97006",
"line": ["1357 Amber Drive"],
"city": "Beaverton",
"state": "OR",
"postalCode": "97006"
}],
"maritalStatus": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
"code": "M",
"display": "Married"
}]
},
"contact": [{
"relationship": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
"code": "GUARD",
"display": "Guardian"
}]
}, {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
"code": "FTH",
"display": "father"
}]
}],
"name": {
"family": "Betterhalf",
"given": [
"Boris",
"Bo"
]
},
"telecom": [{
"system": "phone",
"value": "+1(555)555-2008",
"use": "mobile"
}],
"address": {
"use": "home",
"line": ["123 main street"],
"city": "Beaverton",
"state": "OR",
"postalCode": "97867"
}
}],
"communication": [{
"language": {
"coding": [{
"system": "urn:ietf:bcp:47",
"code": "en",
"display": "English"
}]
},
"preferred": true,
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/patient-proficiency",
"extension": [{
"url": "level",
"valueCoding": {
"system": "http://terminology.hl7.org/CodeSystem/v3-LanguageAbilityProficiency",
"code": "G",
"display": "Good"
}
}, {
"url": "type",
"valueCoding": {
"system": "http://terminology.hl7.org/CodeSystem/v3-LanguageAbilityMode",
"code": "ESP",
"display": "Expressed spoken"
}
}]
}]
}],
"managingOrganization": {
"reference": "Organization/PCPartnersTest"
}
}
|
The consensus mapping example developed through multiple vendors are available below:
IG © 2020+ HL7 International / Cross-Group Projects. Package hl7.fhir.us.ccda#2.0.0-ballot based on FHIR 4.0.1. Generated 2025-07-31
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change