C-CDA / FHIR Converter
This page describes C-CDA built-in module which provides API to convert C-CDA documents to FHIR documents and backward.
C-CDA (Consolidated Clinical Document Architecture) is a standard that has been widely adopted in the healthcare industry for exchanging clinical documents. Based on the HL7 Clinical Document Architecture (CDA) standard, it provides a structured approach to capturing and sharing patient information in a consistent manner. However, with the healthcare industry moving towards the more modern FHIR standard, there is now a growing need to convert data between C-CDA and FHIR. Furthermore, the § 170.315(g)(9) ONC criterion mandates that EHR systems must import and export patient data in C-CDA format.
To meet these data exchange requirements, Aidbox offers a module that performs C-CDA to FHIR and FHIR to C-CDA conversions. This module applies a set of rules consistently in both directions, ensuring a robust and reliable conversion process. In addition to data conversion, the module also provides endpoints for validating C-CDA documents and for persisting FHIR data extracted from C-CDA documents.
Below is the list of supported C-CDA sections, their corresponding OIDs and aliases. Section aliases are used to configure C-CDA endpoints to specify a list of sections to process.
Value | Section OID(s) | FHIR resource |
|---|---|---|
goals | 2.16.840.1.113883.10.20.22.2.60 | Goal |
problems | 2.16.840.1.113883.10.20.22.2.5.1 | Condition |
medications | 2.16.840.1.113883.10.20.22.2.1.1 | MedicationStatement |
immunizations | 2.16.840.1.113883.10.20.22.2.2 2.16.840.1.113883.10.20.22.2.2.1 2.16.840.1.113883.10.20.22.4.52 | Immunization |
payers | 2.16.840.1.113883.10.20.22.2.18 | Coverage |
vital-signs | 2.16.840.1.113883.10.20.22.2.4.1 | Observation |
social-history | 2.16.840.1.113883.10.20.22.2.17 | Observation |
procedures | 2.16.840.1.113883.10.20.22.2.7.1 | Procedure |
encounters | 2.16.840.1.113883.10.20.22.2.22.1 | Encounter |
plan-of-treatment | 2.16.840.1.113883.10.20.22.2.10 | Procedure, Observation, Encounter, Goal |
allergies | 2.16.840.1.113883.10.20.22.2.6.1 | AllergyIntolerance |
results | 2.16.840.1.113883.10.20.22.2.3.1 | Observation |
To perform C-CDA to FHIR conversion without storing FHIR resources in the Aidbox database, use the
/ccda/v2/to-fhir endpoint. Simply POST C-CDA XML document in request body as in the following example:POST /ccda/v2/to-fhir
Authorization: .....
Content-Type: application/cda+xml
<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:hl7-org:v3" ...>
....
</ClinicalDocument>
Please note the
Content-Type: application/cda+xml header. Any other MIME type will be rejected by this endpoint.If conversion was successful, you'll get a FHIR Document as a result. Accordingly to the FHIR Documents specification, the first resource in the resulting bundle is Composition resource containing document header information as well as the list of document sections.
// POST /ccda/to-fhir
// HTTP/1.1 200 OK
{
"resourceType" : "Bundle",
"type" : "document",
"entry" : [ {
"resource" : {
"resourceType": "Composition",
"date" : "2015-06-22",
"section" : [ {
"code" : {
"coding" : [ {
"code" : "48765-2",
"display" : "48765-2",
"system" : "http://loinc.org"
} ]
},
"title" : "ALLERGIES AND ADVERSE REACTIONS",
"author" : [ {
"uri" : "urn:uuid:f7a93b9c-f490-dee8-a1ce-e3bf5f0360cc"
} ],
"entry" : [ {
"uri" : "urn:uuid:468e2476-2095-240f-84b6-8f05b0d97637"
}, {
"uri" : "urn:uuid:5082dbe5-1c5a-326a-a72b-a0d73216a679"
} ],
"text" : {
"div" : "<table width='100%' border='1'>\n<thead>\n<tr>\n<th>\nSubstance\n</th>\n<th>\nReaction\n</th>\n<th>\nSeverity\n</th>\n<th>\nStatus\n</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>\n<content ID='product1'>\nPenicillin G\n</content>\n</td>\n<td>\n<content ID='reaction1'>\nHives\n</content>\n</td>\n<td>\n<content ID='severity1'>\nModerate\n</content>\n</td>\n<td>\nActive\n</td>\n</tr>\n<tr>\n<td>\n<content ID='product2'>\nAmpicillin\n</content>\n</td>\n<td>\n<content ID='reaction2'>\nHives\n</content>\n</td>\n<td>\n<content ID='severity2'>\nModerate\n</content>\n</td>\n<td>\nActive\n</td>\n</tr>\n</tbody>\n</table>",
"status" : "generated"
}
}, {
"code" : {
"coding" : [ {
"code" : "10160-0",
"display" : "HISTORY OF MEDICATION USE",
"system" : "http://loinc.org"
} ]
},
"title" : "MEDICATIONS",
"entry" : [ {
"uri" : "urn:uuid:4ddb05da-b1e6-685a-5c08-f28210d31d5d"
}, {
"uri" : "urn:uuid:6f87fc48-b173-97c0-a5fd-1b7e483d5c67"
}, {
"uri" : "urn:uuid:b8b29b52-ecb1-7e69-bee9-52af94d0c174"
} ]
....
In case of error, OperationOutcome resource will be returned:
// POST /ccda/v2/to-fhir
// HTTP/1.1 422 Unprocessable Entity
{
"resourceType": "OperationOutcome",
"id": "invalid",
"text": {
"status": "generated",
"div": "...."
},
"issue": [
{
"severity": "fatal",
"code": "invalid",
"diagnostics": "..."
}
]
}
Please note that this endpoint doesn't persist any populated FHIR data to Aidbox database. This endpoint is read-only and it performs a stateless conversion of the document from one format to another. To persist FHIR data extracted from a C-DDA document proceed to the Persisting a result of C-CDA to FHIR conversion section.
There are several options you may pass to the
/ccda/v2/to-fhir endpoint. Options are passed as query string parameters, i.e. /ccda/v2/to-fhir?option1=value1&option2=value2.Option | Values | Description |
|---|---|---|
format | aidbox | fhir
Default: fhir | |
sections | Comma-separated list of section aliases to process. By default all sections are processed. |
The
/ccda/v2/to-ccda endpoint is used to convert FHIR document to C-CDA document. It accepts a FHIR Document, which is a specialized FHIR Bundle with Composition resource as its first element. It is the user's responsibility to compose this bundle. The resulting C-CDA document will contain all sections from the provided Composition.Because of technical limitation you have to make sure that provided FHIR Document doesn't contain circular references between resources.
Circular references occur when two or more resources in the bundle reference each other in a loop, such as resource A references resource B, which in turn references resource C, which then references resource A again.
There's a mechanism to streamline FHIR Document generation to use with this endpoint, please check Producing C-CDA documents page.
To convert a FHIR document to C-CDA, make a POST request to the
/ccda/v2/to-ccda endpoint with the FHIR document in the request body. The endpoint will return the C-CDA document in XML format.POST /ccda/v2/to-ccda
Content-Type: application/fhir+json
Authorization: ...
{
"resourceType": "Bundle",
"type": "document",
"entry": [...]
}
// POST /ccda/v2/to-ccda
// HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:hl7-org:v3" ...>
....
</ClinicalDocument>
To store C-CDA to FHIR conversion results in the Aidbox database, you can use the
/ccda/v2/persist endpoint. This endpoint converts the C-CDA document to a FHIR document and creates or updates resources using a FHIR Transaction bundle. As this process is transactional, any failure in the bundle will cause the entire transaction to be rolled back, and nothing will be saved. Here is an example of how to use the /ccda/v2/persist endpoint:POST /ccda/v2/persist
Authorization: .....
Content-Type: application/cda+xml
<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:hl7-org:v3" ...>
....
</ClinicalDocument>
Persisting is heavily based on C-CDA's
<id root="..."> element. If some entity in C-CDA document contains this element (identifier), this identifier will be used (in hashed form) as an ID for resulting FHIR resource. This means that resubmitting the same document several times will not produce duplicate resources in the database for C-CDA entities which contains <id> elements.In addition to the FHIR resources that are converted from C-CDA data, the
/ccda/v2/persist endpoint also creates a Provenance resource that contains references to all of the resources that are created or updated during a single call. This list is useful for identifying all FHIR resources that are related to a specific C-CDA document, such as for deleting them from the database.If the
create-docref option is provided, this endpoint will also create a DocumentReference resource that contains a base64-encoded copy of the original C-CDA XML document in its content attribute. This feature is useful if you want to store the original document in the Aidbox database for rare use cases. By default, the create-docref option is set to false, so no DocumentReference resource is created.Options are passed as query-string parameters, i.e.
/ccda/v2/persist?create-docref=true&option2=value2. sections are passed separated by commas, i.e. /ccda/v2/persist?section=dicom,goals,findings.Option | Values | Description |
|---|---|---|
create-docref | true | false
Default: false | Specifies if a DocumentReference resource is needed to store original XML document. |
tenant-id | ID of Tenant resource
Default: none | |
sections | Comma-separated list of section aliases to process. By default all sections are processed. |
Aidbox provides an endpoint to check correctness of C-CDA document. Despite the fact that C-CDA to FHIR conversion can be performed even on invalid C-CDA document (with undefined result), there are some use cases when you want to validate C-CDA document first. For instance, you can use this endpoint to check user-submitted document and reject if it's not valid.
There are two stages of C-CDA validation:
- Structural validation (XSD) which checks that XML tree is properly formed
- Schematron validation that checks the presence of data elements required by C-CDA specification
By default both stages are performed.
On C-CDA Converter Demo page only XSD validation is performed. Uploaded XML file will be highlighted with green color if the document is valid, red otherwise.
The following example demonstrates how to use validation endpoint:
POST /ccda/validate
Authorization: .....
Content-Type: application/cda+xml
<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:hl7-org:v3" ...>
....
</ClinicalDocument>
If validation was successful, you will get the following response:
// POST /ccda/validate
// HTTP/1.1 200 OK
{
"result": true
}
In case of failed validation endpoint will return a list of errors and warnings:
// POST /ccda/validate
// HTTP/1.1 200 OK
{
"result": false,
"errors": [
{
"pattern": {
"id": "p-urn-hl7ii-2.16.840.1.113883.10.20.22.4.78-2014-06-09-errors"
},
"rule": {
"context": "//cda:observation[cda:templateId[@root='2.16.840.1.113883.10.20.22.4.78' and @extension='2014-06-09']]",
"id": "r-urn-hl7ii-2.16.840.1.113883.10.20.22.4.78-2014-06-09-errors"
},
"failed-assert": {
"location": "/ClinicalDocument/component/structuredBody/component[5]/section/entry[0]/observation",
"schematron": "count(cda:statusCode)=1",
"explanation": [
"SHALL contain exactly one [1..1] statusCode (CONF:1098-14809)."
],
"id": "a-1098-14809"
}
}
],
"warnings": [
{
"pattern": {
"id": "p-urn-oid-2.16.840.1.113883.10.20.22.4.64-warnings"
},
"rule": {
"context": "//cda:act[cda:templateId[@root='2.16.840.1.113883.10.20.22.4.64']]",
"id": "r-urn-oid-2.16.840.1.113883.10.20.22.4.64-warnings"
},
"failed-assert": {
"location": "/ClinicalDocument/component/structuredBody/component[1]/section/entry/substanceAdministration/entryRelationship[1]/act",
"schematron": "count(cda:author[cda:templateId[@root='2.16.840.1.113883.10.20.22.4.119']])=1",
"explanation": [
"SHOULD contain zero or one [0..1] Author Participation (identifier: urn:oid:2.16.840.1.113883.10.20.22.4.119) (CONF:81-9433)."
],
"id": "a-81-9433"
}
}
],
"no-of-fails": {
"errors": 1,
"warnings": 1
}
}
Options are passed as query-string parameters, i.e.
/ccda/validate?option1=value1&option2=value2.Option | Values | Description |
|---|---|---|
method | xsd | schematron | both
Default: both | Type of validation to perform. |
Last modified 28d ago