Mapping CDA Documents to FHIR: Common Pitfalls & Solutions

Why CDA to FHIR Conversion?

C-CDA (Consolidated Clinical Document Architecture) is still the dominant format for clinical document exchange in the US — discharge summaries, referral notes, and continuity of care documents all arrive as CDA XML. Converting them to FHIR resources allows you to store, query, and exchange that data through modern APIs.

The Core Mapping Challenge

CDA is a document-centric model. FHIR is resource-centric. A single CDA document maps to a Bundle containing a Composition (the document shell), a Patient, and multiple clinical resources extracted from each CDA section.

Pitfall 1: Code System Mismatches

CDA uses SNOMED CT, LOINC, RxNorm, and ICD codes — but often with local extensions or retired codes. Always validate extracted codes against current terminology servers before storing them in FHIR resources. A code that was valid in 2015 ICD-9 will not be a valid FHIR Coding today.

// Validate against a FHIR terminology server
GET /fhir/CodeSystem/$validate-code
  ?url=http://hl7.org/fhir/sid/icd-10-cm
  &code=J18.9
  &display=Pneumonia%2C+unspecified+organism

Pitfall 2: Nulls and Missing Required Fields

CDA sections often contain nullFlavor attributes instead of actual values. Map these to FHIR's _value data absent extensions — do not silently drop them. A missing birth date in FHIR is better represented with a data absent reason than omitted entirely.

Pitfall 3: Author and Performer Identity

CDA contains author and performer sections with NPI numbers and organisation details. Map these to FHIR Practitioner and Organization resources and use references, not inline repetition. Deduplication by NPI is essential — the same clinician appears in every document they authored.

Handling Narrative Text

CDA sections contain human-readable narrative in <text> elements. Preserve this in the FHIR Composition.section.text field. Do not attempt to parse narrative text into structured FHIR fields — this introduces hallucination errors that corrupt clinical data.

Testing Your Mappings

Run converted bundles through the HAPI FHIR validator against US Core profiles. Track mapping accuracy with a set of known reference documents where you can manually verify output. Aim for zero validation errors on the Patient, Condition, and MedicationRequest resources before deploying to production.

Have questions about implementing this in your healthcare platform? Get in touch with the Akhester team.