21 Sep
A provider partner agrees to share patient records for a pilot. What arrives isn’t a tidy FHIR bundle. It’s a folder of C-CDA documents: dense clinical XML files, each one a Continuity of Care Document or discharge summary, each one technically standards-compliant and each one missing pieces the engineering team doesn’t discover until the model starts producing strange answers.
This is a different failure mode than the HL7 v2 problem. A v2 message is inconsistent because implementers customize it. A C-CDA document can be perfectly valid by the standard’s own rules and still leave out the exact clinical detail a model needed, because the standard itself allows that gap.
What is a C-CDA and why does a provider partner send it?
C-CDA, the Consolidated Clinical Document Architecture, is the format most EHRs use to export a patient summary: a Continuity of Care Document, a discharge summary, a referral note. It’s not a niche format. ONC’s own certification testing materials confirm that C-CDA Release 2.1 is the standard certified health IT must support to export data mapped to the United States Core Data for Interoperability, which is exactly why a provider partner’s system defaults to handing over C-CDA files rather than FHIR resources. The mandate that matters to their compliance team is written around C-CDA, so that’s what their system produces first.
For an AI team, the instinct is to treat that file the way a FHIR bundle would be treated: parse it, pull out structured fields, feed the result to the model. C-CDA doesn’t cooperate with that instinct as cleanly as FHIR does.
Why can the narrative text and the structured data disagree?
Every C-CDA section carries two parallel representations of the same clinical information: a narrative block, meant for a human to read, and a set of structured entries, meant for a computer to parse. HL7’s own build guidance for the standard states directly that an originator of a CDA document is not required to fully encode all narrative into CDA entries within the document body. That’s not a bug in a particular vendor’s export. It’s the standard working as designed. A clinician can write a complete, clinically accurate narrative note, and the structured entries beneath it can be thin, partial, or absent, and the document is still fully compliant.
A model that only reads structured entries misses whatever lives in the narrative. A pipeline that only extracts narrative text loses the coding and machine-processable structure that made FHIR conversion worth doing in the first place. Neither approach alone gets the full clinical picture, and most conversion pipelines pick one by default without flagging what got left behind.
Why does that gap matter to a model, not just a human reader?
A clinician reading a C-CDA in a viewer sees both the narrative and the structured data rendered together, and their judgment fills in whatever gap exists between the two. A model consuming extracted, structured fields doesn’t get that context. If the allergy list’s structured entries are sparse but the narrative mentions a reaction in a sentence buried in the plan of care, a pipeline that only pulled structured entries hands the model an incomplete allergy picture and calls it done.
This produces a specific kind of failure. It isn’t a crash. It’s a model operating confidently on a clinical picture that looks complete because the extraction succeeded, when the extraction actually only captured half of what the document contained.
What sections tend to arrive incomplete or narrative-only?
Not every C-CDA section carries the same risk. Some are reliably structured because the certification criteria that produced the document require specific entry templates. Others lean on narrative far more often in practice, particularly free-text plan of care notes, care team communication, and any section where the source EHR’s user interface makes structured entry optional or awkward for the clinician.
| C-CDA section | Typical structure reliability | What to check before trusting it |
|---|---|---|
| Problems / conditions | Generally structured, coded entries expected | Confirm code system used and whether resolved problems are flagged |
| Medications | Generally structured | Check for dose, route, and status completeness |
| Allergies | Often incomplete, reaction detail may sit in narrative only | Compare narrative text against structured entry count |
| Plan of care | Frequently narrative-only | Assume the narrative carries information the entries don’t |
| Social history | Inconsistent across vendors | Verify presence before relying on it for any risk scoring |
What technical signal shows the narrative and structured data have diverged?
The C-CDA specification includes a mechanism for exactly this problem, and most conversion pipelines never use it. A structured entry can carry an originalText reference that points back to the specific span of narrative text it was drawn from, and separately, a translationCode element that maps a locally selected term to a standard code system. When that linkage is present and followed correctly, it’s possible to confirm that a given structured entry actually reflects what the narrative says, rather than assuming the two match.
In practice, many source systems either skip that linkage or use it inconsistently, which is part of why the standard’s own guidance is direct on this point: narrative text can carry more clinical nuance than the structured entries beside it, and a receiving system should not discard it on the assumption that the structured side is the complete record. A conversion pipeline that extracts only the coded entries and throws away the narrative is treating an optional, sometimes-thin data path as if it were guaranteed to be the whole story.
How do you check what you're actually getting before it reaches your model?
The only reliable way to know whether a specific provider partner’s C-CDA export is giving a model a complete clinical picture is to look at the converted output next to the source document, not to assume the conversion caught everything. That check has to happen before the pipeline goes live, using a synthetic or de-identified C-CDA sample, not a real patient’s discharge summary.
Hgear’s free C-CDA to FHIR Converter takes a C-CDA document and extracts it into FHIR R4 resources, including Patient, Condition, AllergyIntolerance, MedicationStatement, and related resources, so a team can see exactly what came through structured and compare it against the source narrative directly. Running a partner’s sample document through it before the integration goes live turns a guess about data completeness into an actual answer.
- Run a synthetic or de-identified sample C-CDA from the specific partner’s system, not a generic test file, since section completeness varies by EHR vendor.
- Compare the converted FHIR resources against the original narrative text section by section, not just at the document level.
- Flag any section where the narrative contains detail the structured entries don’t capture, and decide explicitly whether the model needs that narrative content too.
- Repeat the check for every new provider partner, since the same EHR product can produce different completeness depending on how a given clinical team uses it.
Want to see what a real C-CDA export actually converts to?
Hgear’s free C-CDA to FHIR Converter is built for exactly this kind of pre-integration check. Run a synthetic or de-identified C-CDA document through it and see the FHIR R4 resources it produces, side by side with what the source narrative actually said.
FAQs
A C-CDA, or Consolidated Clinical Document Architecture document, is an XML-based clinical summary such as a Continuity of Care Document or discharge summary. Unlike FHIR, which represents data as discrete, queryable resources, a C-CDA combines human-readable narrative text with optional structured entries in a single document, and ONC's certification requirements tie C-CDA R2.1 to USCDI data export for certified health IT.
HL7's own C-CDA build guidance states that an originator of a CDA document is not required to fully encode all narrative content into structured CDA entries. A document can be fully standards-compliant while carrying clinical detail only in narrative text, with no structured entry capturing the same information.
Plan of care sections and portions of social history are frequently narrative-heavy in practice, while problems and medications tend to be more reliably structured because the certification criteria behind them expect specific coded entry templates. Reliability still varies by EHR vendor and by how a given clinical team uses the system.
Yes. Hgear's free C-CDA to FHIR Converter is built to be evaluated with synthetic or de-identified C-CDA documents, so a team can see the converted FHIR output and compare it against the source narrative before any real patient data is involved in the pipeline.
Narrative text alone loses the coding and structure that make data usable across systems, such as standardized problem or medication codes. The goal isn't choosing narrative over structured data, it's checking whether the conversion captured everything the narrative actually said, since C-CDA allows the two to diverge.
Yes. Section completeness depends on the source EHR vendor and on how a specific clinical team uses that system, so a conversion pipeline validated against one partner's documents doesn't guarantee the same completeness for the next partner's exports.
ISO 27001:2022 Certified
Aigilx health specializes in developing Interoperability solutions to create a healthcare ecosystem and aids in the delivery of efficient, patient-centric and population-focused healthcare.
