C-CDA 2.1 Sections Reference¶

Last Updated: 2025-10-22 Reference Source: references/C-CDA_2.1/ Total Sections: 82 Upstream Repository: https://github.com/jddamore/ccda-search

Note: The C-CDA 2.1 reference documentation in references/C-CDA_2.1/ is sourced from the official HL7 C-CDA Online Search Tool repository maintained by John D'Amore. This repository contains the HTML pages and PDFs from the C-CDA navigation tool project released by HL7 in January 2021.

⚠️ IMPORTANT: Implementation Guidelines¶

ALL future implementations MUST reference the official C-CDA 2.1 specification located in:

references/C-CDA_2.1/

⚠️ IMPORTANT: The reference materials are NOT included in this repository. You must download them separately. See references/README.md for download instructions.

Quick Setup¶

# From the ccdakit root directory
cd references/
git clone https://github.com/jddamore/ccda-search.git C-CDA_2.1
cd ..

How to Use This Reference¶

Template HTML Files: Each template has detailed HTML documentation in references/C-CDA_2.1/templates/{template_id}.html
Template PDFs: PDF versions available in references/C-CDA_2.1/pdfs/
Template Data: Structured data in references/C-CDA_2.1/data.json

See references/README.md for detailed download and setup instructions.

Implementation Requirements¶

When implementing any section, you MUST: - ✅ Reference the official template HTML file for structure - ✅ Follow ALL conformance rules (CONF numbers) - ✅ Handle corner cases (missing data, optional fields, null flavors) - ✅ Support both R2.1 and R2.0 where applicable - ✅ Include comprehensive tests (90%+ coverage) - ✅ Generate proper narrative HTML tables - ✅ Validate against XSD schemas

📊 Implementation Status¶

Status	Count	Description
✅ COMPLETE	39	Fully implemented with tests
🔄 IN PROGRESS	0	Currently being worked on
📋 PLANNED	0	High priority, planned next
⏳ FUTURE	43	To be implemented

Total Progress: 39/82 sections (47.6%)

✅ Implemented Sections (39)¶

Core Clinical Sections (8/8 ONC Requirements - 100% Complete!)¶

Section Name	Template ID	Status	Coverage	Tests	File
Allergies and Intolerances Section (entries required)	2.16.840.1.113883.10.20.22.2.6.1	✅ Complete	100%	38	`ccdakit/builders/sections/allergies.py`
Encounters Section (entries required)	2.16.840.1.113883.10.20.22.2.22.1	✅ Complete	100%	24	`ccdakit/builders/sections/encounters.py`
Immunizations Section (entries required)	2.16.840.1.113883.10.20.22.2.2.1	✅ Complete	100%	35	`ccdakit/builders/sections/immunizations.py`
Medications Section (entries required)	2.16.840.1.113883.10.20.22.2.1.1	✅ Complete	100%	42	`ccdakit/builders/sections/medications.py`
Problem Section (entries required)	2.16.840.1.113883.10.20.22.2.5.1	✅ Complete	98%	45	`ccdakit/builders/sections/problems.py`
Procedures Section (entries required)	2.16.840.1.113883.10.20.22.2.7.1	✅ Complete	100%	15	`ccdakit/builders/sections/procedures.py`
Results Section (entries required)	2.16.840.1.113883.10.20.22.2.3.1	✅ Complete	100%	23	`ccdakit/builders/sections/results.py`
Social History Section	2.16.840.1.113883.10.20.22.2.17	✅ Complete	100%	18	`ccdakit/builders/sections/social_history.py`
Vital Signs Section (entries required)	2.16.840.1.113883.10.20.22.2.4.1	✅ Complete	100%	38	`ccdakit/builders/sections/vital_signs.py`

Extended Clinical Sections¶

Section Name	Template ID	Status	Coverage	Tests	File
Assessment and Plan Section	2.16.840.1.113883.10.20.22.2.9	✅ Complete	100%	64	`ccdakit/builders/sections/assessment_and_plan.py`
Family History Section	2.16.840.1.113883.10.20.22.2.15	✅ Complete	99%	38	`ccdakit/builders/sections/family_history.py`
Functional Status Section	2.16.840.1.113883.10.20.22.2.14	✅ Complete	100%	42	`ccdakit/builders/sections/functional_status.py`
Goals Section	2.16.840.1.113883.10.20.22.2.60	✅ Complete	100%	44	`ccdakit/builders/sections/goals.py`
Health Concerns Section	2.16.840.1.113883.10.20.22.2.58	✅ Complete	100%	45	`ccdakit/builders/sections/health_concerns.py`
Health Status Evaluations and Outcomes Section	2.16.840.1.113883.10.20.22.2.61	✅ Complete	99%	51	`ccdakit/builders/sections/health_status_evaluations.py`
Mental Status Section	2.16.840.1.113883.10.20.22.2.56	✅ Complete	100%	49	`ccdakit/builders/sections/mental_status.py`
Past Medical History	2.16.840.1.113883.10.20.22.2.20	✅ Complete	100%	36	`ccdakit/builders/sections/past_medical_history.py`
Physical Exam Section	2.16.840.1.113883.10.20.2.10	✅ Complete	98%	35	`ccdakit/builders/sections/physical_exam.py`

Specialized/Administrative Sections¶

Section Name	Template ID	Status	Coverage	Tests	File
Admission Medications Section (entries optional)	2.16.840.1.113883.10.20.22.2.44	✅ Complete	100%	30	`ccdakit/builders/sections/admission_medications.py`
Advance Directives Section (entries required)	2.16.840.1.113883.10.20.22.2.21.1	✅ Complete	100%	42	`ccdakit/builders/sections/advance_directives.py`
Chief Complaint and Reason for Visit Section	2.16.840.1.113883.10.20.22.2.13	✅ Complete	100%	28	`ccdakit/builders/sections/chief_complaint_reason_for_visit.py`
Discharge Medications Section (entries required)	2.16.840.1.113883.10.20.22.2.11.1	✅ Complete	100%	48	`ccdakit/builders/sections/discharge_medications.py`
Hospital Discharge Instructions Section	2.16.840.1.113883.10.20.22.2.41	✅ Complete	100%	29	`ccdakit/builders/sections/hospital_discharge_instructions.py`
Interventions Section	2.16.840.1.113883.10.20.21.2.3	✅ Complete	99%	47	`ccdakit/builders/sections/interventions.py`
Medical Equipment Section	2.16.840.1.113883.10.20.22.2.23	✅ Complete	100%	61	`ccdakit/builders/sections/medical_equipment.py`
Nutrition Section	2.16.840.1.113883.10.20.22.2.57	✅ Complete	91%	33	`ccdakit/builders/sections/nutrition.py`
Payers Section	2.16.840.1.113883.10.20.22.2.18	✅ Complete	92%	44	`ccdakit/builders/sections/payers.py`
Plan of Treatment Section	2.16.840.1.113883.10.20.22.2.10	✅ Complete	91%	32	`ccdakit/builders/sections/plan_of_treatment.py`
Reason for Visit Section	2.16.840.1.113883.10.20.22.2.12	✅ Complete	100%	32	`ccdakit/builders/sections/reason_for_visit.py`

Hospital and Surgical Sections¶

Section Name	Template ID	Status	Coverage	Tests	File
Admission Diagnosis Section	2.16.840.1.113883.10.20.22.2.43	✅ Complete	100%	35	`ccdakit/builders/sections/admission_diagnosis.py`
Anesthesia Section	2.16.840.1.113883.10.20.22.2.25	✅ Complete	100%	29	`ccdakit/builders/sections/anesthesia.py`
Complications Section	2.16.840.1.113883.10.20.22.2.37	✅ Complete	100%	31	`ccdakit/builders/sections/complications.py`
Discharge Diagnosis Section	2.16.840.1.113883.10.20.22.2.24	✅ Complete	100%	35	`ccdakit/builders/sections/discharge_diagnosis.py`
Hospital Course Section	1.3.6.1.4.1.19376.1.5.3.1.3.5	✅ Complete	100%	34	`ccdakit/builders/sections/hospital_course.py`
Hospital Discharge Studies Summary Section	2.16.840.1.113883.10.20.22.2.16	✅ Complete	100%	32	`ccdakit/builders/sections/discharge_studies.py`
Instructions Section	2.16.840.1.113883.10.20.22.2.45	✅ Complete	100%	33	`ccdakit/builders/sections/instructions.py`
Medications Administered Section	2.16.840.1.113883.10.20.22.2.38	✅ Complete	100%	35	`ccdakit/builders/sections/medications_administered.py`
Postoperative Diagnosis Section	2.16.840.1.113883.10.20.22.2.35	✅ Complete	100%	28	`ccdakit/builders/sections/postoperative_diagnosis.py`
Preoperative Diagnosis Section	2.16.840.1.113883.10.20.22.2.34	✅ Complete	100%	27	`ccdakit/builders/sections/preoperative_diagnosis.py`

Total Tests: 1,428 comprehensive tests across all sections Average Coverage: 99.1%

🎉 High Priority Sections (ALL COMPLETE!)¶

All commonly required C-CDA sections have been implemented:

Section Name	Template ID	Status	Notes
Procedures Section (entries required)	2.16.840.1.113883.10.20.22.2.7.1	✅ Complete	Surgical/medical procedures
Results Section (entries required)	2.16.840.1.113883.10.20.22.2.3.1	✅ Complete	Lab/diagnostic test results
Social History Section	2.16.840.1.113883.10.20.22.2.17	✅ Complete	Smoking, alcohol use, etc.
Encounters Section (entries required)	2.16.840.1.113883.10.20.22.2.22.1	✅ Complete	Healthcare visits/encounters

⏳ All C-CDA 2.1 Sections (Complete List)¶

A¶

✅ Admission Diagnosis Section - 2.16.840.1.113883.10.20.22.2.43 ✅
✅ Admission Medications Section (entries optional) - 2.16.840.1.113883.10.20.22.2.44 ✅
⏳ Advance Directives Section (entries optional) - 2.16.840.1.113883.10.20.22.2.21
✅ Advance Directives Section (entries required) - 2.16.840.1.113883.10.20.22.2.21.1 ✅
⏳ Allergies and Intolerances Section (entries optional) - 2.16.840.1.113883.10.20.22.2.6
✅ Allergies and Intolerances Section (entries required) - 2.16.840.1.113883.10.20.22.2.6.1 ✅
✅ Anesthesia Section - 2.16.840.1.113883.10.20.22.2.25 ✅
⏳ Assessment Section - 2.16.840.1.113883.10.20.22.2.8
✅ Assessment and Plan Section - 2.16.840.1.113883.10.20.22.2.9 ✅

C¶

⏳ Care Teams Section (Companion Guide) - 2.16.840.1.113883.10.20.22.2.500
⏳ Chief Complaint Section - 1.3.6.1.4.1.19376.1.5.3.1.1.13.2.1
✅ Chief Complaint and Reason for Visit Section - 2.16.840.1.113883.10.20.22.2.13 ✅
✅ Complications Section - 2.16.840.1.113883.10.20.22.2.37 ✅
⏳ Course of Care Section - 2.16.840.1.113883.10.20.22.2.64

D¶

⏳ DICOM Object Catalog Section - DCM 121181 - 2.16.840.1.113883.10.20.6.1.1
✅ Discharge Diagnosis Section - 2.16.840.1.113883.10.20.22.2.24 ✅
⏳ Discharge Diet Section (DEPRECATED) - 1.3.6.1.4.1.19376.1.5.3.1.3.33
⏳ Discharge Medications Section (entries optional) - 2.16.840.1.113883.10.20.22.2.11
✅ Discharge Medications Section (entries required) - 2.16.840.1.113883.10.20.22.2.11.1 ✅

E¶

⏳ Encounters Section (entries optional) - 2.16.840.1.113883.10.20.22.2.22
✅ Encounters Section (entries required) - 2.16.840.1.113883.10.20.22.2.22.1 ✅

F¶

✅ Family History Section - 2.16.840.1.113883.10.20.22.2.15 ✅
⏳ Fetus Subject Context - 2.16.840.1.113883.10.20.6.2.3
⏳ Findings Section (DIR) - 2.16.840.1.113883.10.20.6.1.2
✅ Functional Status Section - 2.16.840.1.113883.10.20.22.2.14 ✅

G¶

⏳ General Status Section - 2.16.840.1.113883.10.20.2.5
✅ Goals Section - 2.16.840.1.113883.10.20.22.2.60 ✅

H¶

✅ Health Concerns Section - 2.16.840.1.113883.10.20.22.2.58 ✅
✅ Health Status Evaluations and Outcomes Section - 2.16.840.1.113883.10.20.22.2.61 ✅
⏳ History of Present Illness Section - 1.3.6.1.4.1.19376.1.5.3.1.3.4
⏳ Hospital Consultations Section - 2.16.840.1.113883.10.20.22.2.42
✅ Hospital Course Section - 1.3.6.1.4.1.19376.1.5.3.1.3.5 ✅
✅ Hospital Discharge Instructions Section - 2.16.840.1.113883.10.20.22.2.41 ✅
⏳ Hospital Discharge Physical Section - 1.3.6.1.4.1.19376.1.5.3.1.3.26
✅ Hospital Discharge Studies Summary Section - 2.16.840.1.113883.10.20.22.2.16 ✅

I¶

⏳ Immunizations Section (entries optional) - 2.16.840.1.113883.10.20.22.2.2
✅ Immunizations Section (entries required) - 2.16.840.1.113883.10.20.22.2.2.1 ✅
⏳ Implants Section (DEPRECATED) - 2.16.840.1.113883.10.20.22.2.33
✅ Instructions Section - 2.16.840.1.113883.10.20.22.2.45 ✅
✅ Interventions Section - 2.16.840.1.113883.10.20.21.2.3 ✅

M¶

⏳ Medical (General) History Section - 2.16.840.1.113883.10.20.22.2.39
✅ Medical Equipment Section - 2.16.840.1.113883.10.20.22.2.23 ✅
✅ Medications Administered Section - 2.16.840.1.113883.10.20.22.2.38 ✅
⏳ Medications Section (entries optional) - 2.16.840.1.113883.10.20.22.2.1
✅ Medications Section (entries required) - 2.16.840.1.113883.10.20.22.2.1.1 ✅
✅ Mental Status Section - 2.16.840.1.113883.10.20.22.2.56 ✅

N¶

⏳ Notes Section (Companion Guide) - 2.16.840.1.113883.10.20.22.2.65
✅ Nutrition Section - 2.16.840.1.113883.10.20.22.2.57 ✅

O¶

⏳ Objective Section - 2.16.840.1.113883.10.20.21.2.1
⏳ Observer Context - 2.16.840.1.113883.10.20.6.2.4
⏳ Operative Note Fluids Section - 2.16.840.1.113883.10.20.7.12
⏳ Operative Note Surgical Procedure Section - 2.16.840.1.113883.10.20.7.14

P¶

✅ Past Medical History - 2.16.840.1.113883.10.20.22.2.20 ✅
✅ Payers Section - 2.16.840.1.113883.10.20.22.2.18 ✅
✅ Physical Exam Section - 2.16.840.1.113883.10.20.2.10 ✅
✅ Plan of Treatment Section - 2.16.840.1.113883.10.20.22.2.10 ✅
⏳ Planned Procedure Section - 2.16.840.1.113883.10.20.22.2.30
✅ Postoperative Diagnosis Section - 2.16.840.1.113883.10.20.22.2.35 ✅
⏳ Postprocedure Diagnosis Section - 2.16.840.1.113883.10.20.22.2.36
✅ Preoperative Diagnosis Section - 2.16.840.1.113883.10.20.22.2.34 ✅
⏳ Problem Section (entries optional) - 2.16.840.1.113883.10.20.22.2.5
✅ Problem Section (entries required) - 2.16.840.1.113883.10.20.22.2.5.1 ✅
⏳ Procedure Description Section - 2.16.840.1.113883.10.20.22.2.27
⏳ Procedure Disposition Section - 2.16.840.1.113883.10.20.18.2.12
⏳ Procedure Estimated Blood Loss Section - 2.16.840.1.113883.10.20.18.2.9
⏳ Procedure Findings Section - 2.16.840.1.113883.10.20.22.2.28
⏳ Procedure Implants Section - 2.16.840.1.113883.10.20.22.2.40
⏳ Procedure Indications Section - 2.16.840.1.113883.10.20.22.2.29
⏳ Procedure Specimens Taken Section - 2.16.840.1.113883.10.20.22.2.31
⏳ Procedures Section (entries optional) - 2.16.840.1.113883.10.20.22.2.7
✅ Procedures Section (entries required) - 2.16.840.1.113883.10.20.22.2.7.1 ✅

R¶

⏳ Reason for Referral Section - 1.3.6.1.4.1.19376.1.5.3.1.3.1
✅ Reason for Visit Section - 2.16.840.1.113883.10.20.22.2.12 ✅
⏳ Results Section (entries optional) - 2.16.840.1.113883.10.20.22.2.3
✅ Results Section (entries required) - 2.16.840.1.113883.10.20.22.2.3.1 ✅
⏳ Review of Systems Section - 1.3.6.1.4.1.19376.1.5.3.1.3.18

S¶

✅ Social History Section - 2.16.840.1.113883.10.20.22.2.17 ✅
⏳ Subjective Section - 2.16.840.1.113883.10.20.21.2.2
⏳ Surgery Description Section (DEPRECATED) - 2.16.840.1.113883.10.20.22.2.26
⏳ Surgical Drains Section - 2.16.840.1.113883.10.20.7.13

V¶

⏳ Vital Signs Section (entries optional) - 2.16.840.1.113883.10.20.22.2.4
✅ Vital Signs Section (entries required) - 2.16.840.1.113883.10.20.22.2.4.1 ✅

📚 How to Implement a New Section¶

Step 1: Research the Template¶

# Open the template HTML file
open references/C-CDA_2.1/templates/{template_id}.html

# Example:
open references/C-CDA_2.1/templates/2.16.840.1.113883.10.20.22.2.7.1.html

Step 2: Review the Specification¶

Look for: - Template ID and version extension - SHALL/SHOULD/MAY conformance rules - Entry requirements (required/optional entries) - Code bindings (value sets and code systems) - Cardinality (0..1, 1..1, 0.., 1..) - Narrative generation requirements

Step 3: Create Protocol (if needed)¶

Define the data contract in ccdakit/protocols/:

from typing import Protocol, Optional
from datetime import datetime

class YourDataProtocol(Protocol):
    """Data contract for your section."""

    @property
    def field_name(self) -> str:
        """Required field."""
        ...

    @property
    def optional_field(self) -> Optional[str]:
        """Optional field."""
        ...

Step 4: Create Entry Builder (if needed)¶

Implement entry-level builders in ccdakit/builders/entries/:

from ccdakit.core import CDAElement, CDAVersion

class YourEntry(CDAElement):
    """Builder for your entry observation/activity."""

    def __init__(
        self,
        data: YourDataProtocol,
        version: CDAVersion = CDAVersion.R2_1
    ):
        # Implementation
        pass

Step 5: Create Section Builder¶

Implement section builder in ccdakit/builders/sections/:

from ccdakit.core import CDAElement, CDAVersion

class YourSection(CDAElement):
    """Builder for Your Section."""

    def __init__(
        self,
        items: list[YourDataProtocol],
        version: CDAVersion = CDAVersion.R2_1
    ):
        # Implementation with narrative generation
        pass

Step 6: Write Comprehensive Tests¶

Create tests in tests/test_builders/:

def test_your_section_structure():
    """Test basic section structure."""
    pass

def test_your_section_with_data():
    """Test section with actual data."""
    pass

def test_your_section_empty():
    """Test section with no data."""
    pass

def test_your_section_narrative():
    """Test narrative HTML generation."""
    pass

# Target: 90%+ coverage

Step 7: Validate¶

# Run tests
uv run pytest tests/test_builders/test_your_section.py -v

# Check coverage
uv run pytest --cov=ccdakit.builders.sections.your_section

# Validate generated XML
uv run python examples/validate_ccda.py

🎯 Implementation Priorities¶

Phase 12: Core Clinical Sections (Next)¶

Procedures Section - Essential for clinical workflows
Results/Labs Section - Critical for diagnostic information
Social History Section - Required for many document types
Encounters Section - Tracks healthcare visits

Phase 13: Extended Clinical Sections¶

Family History Section
Functional Status Section
Mental Status Section
Goals Section
Health Concerns Section

Phase 14: Specialized Sections¶

Advance Directives Section
Medical Equipment Section
Plan of Treatment Section
Assessment and Plan Section

Phase 15: Document-Specific Sections¶

Discharge-related sections
Operative/Procedure-specific sections
DICOM imaging sections
Administrative sections

📊 Section Usage Statistics¶

Most Common Sections (ONC Requirements)¶

According to ONC C-CDA certification requirements, the most commonly required sections are:

✅ Problems - Required in CCD, Progress Note, Discharge Summary
✅ Medications - Required in CCD, Progress Note, Discharge Summary
✅ Allergies - Required in CCD, Progress Note, Discharge Summary
✅ Vital Signs - Required in many document types
✅ Results - Required in CCD, Progress Note
✅ Procedures - Required in CCD, Operative Note
✅ Encounters - Required in CCD
✅ Social History - Required in CCD

Current Coverage: 8/8 most common sections (100% COMPLETE!)

🔍 Template ID Patterns¶

C-CDA template IDs follow these patterns:

Document Templates¶

2.16.840.1.113883.10.20.22.1.X - Document-level templates

Section Templates¶

2.16.840.1.113883.10.20.22.2.X - Section-level templates
1.3.6.1.4.1.19376.1.5.3.1.X.X - IHE-derived sections

Entry Templates¶

2.16.840.1.113883.10.20.22.4.X - Entry-level templates

Version Extensions¶

R2.1: 2015-08-01 (most common)
R2.0: 2014-06-09

📞 Resources¶

Official C-CDA References¶

C-CDA Online: http://www.hl7.org/ccdasearch/
Local Reference: references/C-CDA_2.1/ (sourced from https://github.com/jddamore/ccda-search)
C-CDA Search Repository: https://github.com/jddamore/ccda-search
HL7 Blog Post: https://blog.hl7.org/new-hl7-c-cda-navigation-tool-released

Standards & Validation¶

HL7 CDA Standard: https://www.hl7.org/implement/standards/product_brief.cfm?product_id=7
C-CDA R2.1 Product Brief: https://www.hl7.org/implement/standards/product_brief.cfm?product_id=492
ONC C-CDA Validator: https://site.healthit.gov/sandbox-ccda/ccda-validator

🎉 Progress Tracking¶

# Current Stats
Implemented: 39/82 (47.6%)
High Priority Remaining: 0 (ALL DONE!)
Total Remaining: 43

# Milestones Achieved:
✅ Phase 1: Core Clinical Sections (9/9 - 100%)
✅ Phase 2: Extended Clinical Sections (9/9 - 100%)
✅ Phase 3: Specialized Sections (11/11 - 100%)
✅ Phase 4: Hospital and Surgical Sections (10/10 - 100%)

# Next Milestone: 50 sections (61.0%)
Target: End of Phase 5

📈 Recent Implementation Waves¶

Wave 2 - Hospital & Surgical Sections - Date: 2025-10-22 - Sections Added: 10 hospital and surgical sections - Total Tests Added: 319 tests - Average Coverage: 100% - Focus: Discharge summaries, operative notes, anesthesia records

Wave 1 - Core Clinical Foundation - Date: 2025-10-18 - Sections Added: 29 sections implemented - Total Tests Added: 1,109 tests - Average Coverage: 98.6% - All ONC Requirements: ✅ COMPLETE

Last updated by: Claude Code Version: ccdakit v0.1.0-alpha Date: 2025-10-22