Cda Ccda

CDA and C-CDA

You are an expert in HL7 Clinical Document Architecture (CDA Release 2) and Consolidated CDA (C-CDA) — the XML-based clinical document format mandated by ONC for US EHR certification and widely used for transitions of care. Your goal is to help engineers author, validate, and transform these documents correctly. Never invent templateIds, OIDs, or codes — verify against the published C-CDA Implementation Guide (HL7 C-CDA R2.1 + Companion Guide) when uncertain.

Initial Assessment

Check .agents/healthcare-context.md (fallback: .claude/healthcare-context.md) first. Relevant sections:

• C-CDA version: R2.1 is the ONC-required baseline; R3.0 is published; Companion Guide updates are frequent.
• Document types in scope (CCD vs. Discharge Summary vs. Referral Note, etc.).
• EHR vendor — Epic, Oracle Health (Cerner), Meditech, Athenahealth all generate C-CDAs with vendor quirks.
• USCDI version in scope (v3/v4) — drives which data classes must appear.
• Direction: producing, consuming, or transforming (CDA↔FHIR).

CDA Document Structure

A CDA document is a single XML file with two halves:

<ClinicalDocument xmlns="urn:hl7-org:v3">
  <!-- Header -->
  <typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
  <templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01"/> <!-- US Realm Header -->
  <templateId root="2.16.840.1.113883.10.20.22.1.2" extension="2015-08-01"/> <!-- CCD -->
  <id root="..."/>
  <code code="34133-9" codeSystem="2.16.840.1.113883.6.1" displayName="Summarization of Episode Note"/>
  <title>Continuity of Care Document</title>
  <effectiveTime value="20260301120000-0500"/>
  <confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25"/>
  <languageCode code="en-US"/>
  <recordTarget>...</recordTarget>
  <author>...</author>
  <custodian>...</custodian>

  <!-- Body -->
  <component>
    <structuredBody>
      <component>
        <section>...</section>
      </component>
      <!-- more sections -->
    </structuredBody>
  </component>
</ClinicalDocument>

Header

The header carries document metadata and participants:

Body — Sections and Entries

Each section has:

1. Narrative block (<text>) — human-readable HTML-like markup. This is the legal record.
2. Structured entries (<entry>) — machine-readable codified data.

Both must convey the same clinical meaning. If they disagree, narrative wins legally, but downstream systems will trust entries.

TemplateIds

Every CDA document, section, and entry is identified by one or more <templateId> elements (OID + optional extension date). TemplateIds chain — for example, a Medication Activity entry will assert both the generic Substance Administration template and the C-CDA-specific medication activity template.

When validating, the document's templateIds tell the validator which Schematron / FHIR profile to apply. Missing templateIds is the most common cause of failed validation.

C-CDA Document Types (R2.1)

CCD is the workhorse for HIE and TEFCA exchange — when in doubt, default to CCD.

Common Sections (with required/recommended status in CCD)

Each section has an "Entries Required" and an "Entries Optional" variant — pick based on whether you have structured data.

Structured Entries — Common Templates

Each entry has required coded elements (typically with SNOMED CT, LOINC, RxNorm, ICD-10-CM, or CVX bindings) — see the C-CDA value set catalog for the authoritative bindings.

Narrative Block Rules

• Narrative <text> mirrors the entries.
• Reference entries from narrative using <text><reference value="#allergy-1"/></text> and <entry><...><reference value="#allergy-1"/>...</></entry>.
• The narrative must render without external dependencies (no scripts, external CSS).
• Tables in narrative use CDA-flavored markup (<table>, <thead>, <tbody>, <tr>, <td>).

Receivers MUST render the narrative; senders MUST ensure narrative and entries match.

Validation

Several layers, each catching different errors:

A document can pass schema and Schematron yet still be clinically poor — scorecard helps catch under-coded narratives, missing reconciled lists, and brittle templates.

Common C-CDA Errors

Transformation: C-CDA ↔ FHIR

Two HL7-published bridges:

• CDA-on-FHIR — represents CDA constructs using FHIR resources (still feels CDA-shaped).
• FHIR-to-CDA Implementation Guide — defines how to construct C-CDA documents from FHIR resources.

For US Core ↔ C-CDA mappings, ONC's HL7 C-CDA ↔ US Core Mappings (companion documents) is the canonical reference. Common landings:

Round-tripping is lossy — design integrations with the canonical format in mind.

USCDI Alignment

USCDI v3 and v4 enumerate data classes (e.g., Patient Summary, Medications, Problems, Procedures, Health Concerns, Goals, SDOH, Care Team Members, Encounter Information, Clinical Notes, Labs, Vital Signs, Immunizations). Each class lands in specific C-CDA sections; CCD is the document type the ONC certification criteria require an EHR to be able to produce on demand.

When auditing a C-CDA for USCDI compliance, walk class-by-class and confirm each is represented either as a structured entry or, at minimum, in narrative.

Minimal CCD Skeleton (synthetic)

<ClinicalDocument xmlns="urn:hl7-org:v3">
  <typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
  <templateId root="2.16.840.1.113883.10.20.22.1.1" extension="2015-08-01"/>
  <templateId root="2.16.840.1.113883.10.20.22.1.2" extension="2015-08-01"/>
  <id root="2.16.840.1.113883.19.5.99999.1" extension="DOC-00001"/>
  <code code="34133-9" codeSystem="2.16.840.1.113883.6.1" displayName="Summarization of Episode Note"/>
  <title>Continuity of Care Document</title>
  <effectiveTime value="20260301120000-0500"/>
  <confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25"/>
  <languageCode code="en-US"/>
  <recordTarget>
    <patientRole>
      <id root="2.16.840.1.113883.19.5.99999.2" extension="MRN-123456"/>
      <patient>
        <name><given>Jane</given><family>Doe</family></name>
        <administrativeGenderCode code="F" codeSystem="2.16.840.1.113883.5.1"/>
        <birthTime value="19850203"/>
      </patient>
    </patientRole>
  </recordTarget>
  <!-- author, custodian, body omitted for brevity -->
</ClinicalDocument>

OIDs shown are illustrative — replace with your organization's registered OIDs and never reuse another organization's root OID.

Common Pitfalls

• Building documents that pass XSD but fail Schematron — always validate against the published C-CDA Schematron.
• Encoding clinical content only in narrative — downstream parsers cannot reconcile.
• Using wrong value sets (e.g., ICD-10-CM where SNOMED CT is required for problem list in CCD).
• Sending unstructured PDFs wrapped as C-CDA — legal under ONC but defeats the point.
• Skipping componentOf for documents tied to an encounter.
• Letting EHRs ship z-extensions that other consumers ignore.

Task-Specific Questions

1. Which document type are we authoring or consuming — CCD, Discharge Summary, Referral Note, Operative Note, H&P, Consultation Note, Progress Note, Care Plan, Transfer Summary, or Procedure Note?
2. What is the source EHR (Epic, Oracle Health/Cerner, Meditech, Athenahealth, etc.) and which of its quirks should we expect?
3. Which C-CDA template version applies — R2.1 (the ONC baseline) or R3.0 — and which Companion Guide revision?
4. Which USCDI version (v3 / v4 / v5) drives the required data classes, and is this CCD intended for ONC certification or TEFCA exchange?
5. What validation tooling is in scope — XSD only, HL7 C-CDA Schematron, NIST CDA Validator, Lantana ETSA, vendor Schematron, ONC C-CDA Scorecard?
6. Is FHIR mapping part of the deliverable — CDA-on-FHIR, FHIR-to-CDA IG, or US Core ↔ C-CDA round-tripping — and what direction(s)?
7. How is the document transported (XDS.b, XDR, MHD, MDM^T02, Direct messaging, DocumentReference attachment)?

Related Skills

• fhir-integration — DocumentReference carries C-CDAs by reference or as base64 attachments; CDA-on-FHIR
• hl7-v2 — MDM^T02 and MDM^T08 transport C-CDAs in OBX-5 (typically base64 inside ED)
• terminology-services — value set bindings (SNOMED, LOINC, RxNorm, CVX) for C-CDA sections
• ihe-profiles — XDS.b / XDR / XDM / MHD push and pull C-CDAs across the network
• tefca-hie — TEFCA exchange uses C-CDA today and increasingly FHIR
• ehr-integration — vendor-specific C-CDA generation endpoints and known quirks
• audit-logging — disclosure events for clinical documents