CdaLib 1.2.0

CdaLib

A .NET library for parsing and generating C-CDA (Consolidated Clinical Document Architecture) documents with full ONC 170.315(b)(1) Transitions of Care compliance.

🚀 Features

• ✅ Parse C-CDA XML documents into domain models
• ✅ Generate C-CDA XML documents from domain models
• ✅ FHIR Bundle Support - Convert FHIR R4 bundles to C-CDA documents ⭐ NEW
• ✅ Render C-CDA documents as beautiful, responsive HTML reports
• ✅ XML to HTML - Direct conversion from C-CDA XML to HTML ⭐ NEW
• ✅ Validate documents against XSD schemas and ONC conformance requirements
• ✅ Multi-Document Type Support - CCD, Discharge Summary, Referral Note, and more
• ✅ ONC Certification Ready - Full sender/receiver conformance validation
• ✅ C-CDA 2.1 & USCDI V3 Compliant

📋 Quick Start

Installation

Core Library:

dotnet add package CdaLib --version 1.1.0

HTML Rendering (Optional):

dotnet add package CdaLib.Rendering --version 1.1.0

Or via Package Manager:

Install-Package CdaLib -Version 1.1.0
Install-Package CdaLib.Rendering -Version 1.1.0

Basic Usage

using CdaLib;
using CdaLib.Parsing;
using CdaLib.Domain;

// Create a service for Continuity of Care Document
var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);

// Create your clinical data
var ccd = new Ccd
{
    Patient = new Patient { FirstName = "John", LastName = "Doe", /* ... */ },
    Problems = new List<Problem> { /* ... */ },
    Medications = new List<Medication> { /* ... */ },
    Allergies = new List<Allergy> { /* ... */ }
};

// Generate C-CDA XML with sender conformance validation
var (errors, xmlDoc) = service.Export(ccd);
if (errors.Any())
{
    // Handle validation errors
    foreach (var error in errors)
    {
        Console.WriteLine($"{error.ProblemType}: {error.Reason}");
    }
}

// Save to file
service.ExportToFile(ccd, "output.xml");

// Parse an existing C-CDA document with receiver conformance validation
var (importErrors, parsedCcd) = service.Import("input.xml");

// NEW: Render as responsive HTML medical report
var renderer = new CdaLib.Rendering.CdaHtmlRenderer(CcdaDocumentTypes.ContinuityOfCareDocument);
renderer.RenderToFile(parsedCcd, "patient-report.html");

// NEW: Convert FHIR Bundle to C-CDA
var fhirBundle = GetFhirBundle(); // Your FHIR R4 Bundle
var (fhirErrors, fhirXml) = service.ExportFromFhirBundle(fhirBundle);

// NEW: Convert C-CDA XML directly to HTML
var htmlRenderer = new CdaLib.Rendering.CdaHtmlRenderer(CcdaDocumentTypes.ContinuityOfCareDocument);
var html = htmlRenderer.RenderXmlToHtml(xmlDoc.ToString());

📚 Documentation

Getting Started

• CdaService Usage Guide - Complete guide to using the CdaService API
• Project Structure - Complete solution architecture and organization
• Document Type Configuration Guide - How to configure and use different C-CDA document types

ONC Certification & Compliance

• ONC Validation Guide - Step-by-step guide for ONC 170.315(b)(1) validation
• ONC Direct Protocol Compliance Guide - Sender/Receiver requirements and testing
• C-CDA Conformance Summary - Technical details of C-CDA 2.1 conformance implementation

Document Type Implementations

• Referral Note Implementation - Referral Note-specific implementation details and testing

HTML Rendering

• HTML Rendering Guide - Complete guide to rendering C-CDA documents as HTML
• CdaLib.Rendering README - HTML rendering library API reference

FHIR Integration

• FHIR Bundle Mapping - Guide to converting FHIR R4 bundles to C-CDA

🏥 Supported Document Types

🔍 Validation System

Conformance Modes

CdaLib includes a sophisticated validation system with two conformance modes based on ONC Direct Protocol requirements:

Sender Conformance (§ 170.202(d)) - Strict

For generating documents to send to other systems:

• Validates all required fields
• Checks document-type-specific required sections (Problems, Medications, Allergies for CCD)
• Ensures proper template IDs and document structure
• Validates header elements (patient, author, custodian)
• Used automatically in service.Export()

Receiver Conformance (§ 170.202(a)(2)) - Lenient

For parsing documents received from other systems:

• More tolerant of missing optional fields
• Focuses on structural integrity
• Allows parsing even with minor issues
• Tracks validation issues without rejecting documents
• Used automatically in service.Import()

Example: Using Validation

using CdaLib;
using CdaLib.Validation;
using CdaLib.Parsing;

// Export with sender validation (strict)
var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);
var (exportErrors, xml) = service.Export(ccd);
if (exportErrors.Any())
{
    Console.WriteLine("Document does not meet sender requirements:");
    foreach (var error in exportErrors)
    {
        Console.WriteLine($"  - [{error.ProblemType}] {error.Reason}");
    }
}

// Import with receiver validation (lenient)
var (importErrors, parsedCcd) = service.Import("received-document.xml");
// Parser will extract data even if there are minor conformance issues
Console.WriteLine($"Parsed patient: {parsedCcd.Patient.FirstName} {parsedCcd.Patient.LastName}");

// Advanced: Use validator directly for custom validation
var conformanceErrors = CdaValidator.ValidateWithConformance(
    xml,
    ConformanceMode.Sender,
    CcdaDocumentTypes.ContinuityOfCareDocument);

🧪 Testing Against ONC Validator

Sender Testing (Generate Documents)

1. Generate a C-CDA document:

var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);
var (errors, xml) = service.Export(myCcdData);
xml.Save("my-document.xml");

2. Upload my-document.xml to https://site.healthit.gov/c-cda/uscdi-v3
3. Select Sender validation criteria
4. Choose 170.315_b1_ToC_Amb scenario
5. Verify all IG conformance and S&CC Reference validation passes

Receiver Testing (Parse Documents)

1. Download scenario XML files from the ONC validator
2. Parse them with CdaLib:

var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);
var (errors, ccd) = service.Import("scenario-file.xml");

3. Verify data extraction is successful
4. Upload scenario files to validator with Receiver criteria

📦 Domain Model

The library uses a rich domain model for representing clinical data:

Core Components

• Ccd - Main document container
• Patient - Patient demographics and information
• Author - Document author information
• Custodian - Document custodian (organization)

Clinical Data

• Problems - Conditions and diagnoses
• Medications - Medication activities and prescriptions
• Allergies - Allergies and intolerances
• VitalSigns - Vital sign measurements
• Procedures - Procedures and interventions ⭐ NEW
• Immunizations - Vaccination history ⭐ NEW
• Results - Laboratory results
• Encounters - Healthcare encounters ⭐ NEW
• Goals - Patient goals ⭐ NEW
• SocialHistory - Social history including smoking status

USCDI V3 Extensions

• Goals - Patient goals
• HealthConcerns - Health concerns
• SDOH - Social Determinants of Health
• Notes - Clinical notes
• UDIs - Unique Device Identifiers
• Occupation - Occupational data
• TribalAffiliation - Tribal affiliation
• PregnancyObservations - Pregnancy status
• DisabilityStatus - Disability observations
• FunctionalStatus - Functional status
• Payer - Insurance payer information
• And more...

🔧 Advanced Features

FHIR Bundle to C-CDA Conversion

Convert FHIR R4 bundles directly to C-CDA documents:

using CdaLib;
using Hl7.Fhir.Model; // Microsoft FHIR SDK

// Create a FHIR Bundle with patient data
var bundle = new Bundle
{
    Entry = new List<Bundle.EntryComponent>
    {
        new Bundle.EntryComponent { Resource = new Patient { /* ... */ } },
        new Bundle.EntryComponent { Resource = new AllergyIntolerance { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Condition { /* ... */ } },
        new Bundle.EntryComponent { Resource = new MedicationStatement { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Procedure { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Immunization { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Encounter { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Observation { /* ... */ } },
        new Bundle.EntryComponent { Resource = new DiagnosticReport { /* ... */ } },
        new Bundle.EntryComponent { Resource = new Goal { /* ... */ } }
    }
};

// Convert to C-CDA
var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);
var (errors, xmlDoc) = service.ExportFromFhirBundle(bundle);

if (!errors.Any())
{
    xmlDoc.Save("fhir-to-ccda.xml");
}

Supported FHIR Resources:

• ✅ Patient
• ✅ AllergyIntolerance
• ✅ Condition
• ✅ MedicationStatement / MedicationRequest
• ✅ Procedure ⭐ NEW
• ✅ Immunization ⭐ NEW
• ✅ Encounter ⭐ NEW
• ✅ Observation (Results & Vital Signs) ⭐ NEW
• ✅ DiagnosticReport ⭐ NEW
• ✅ Goal ⭐ NEW
• ✅ Practitioner
• ✅ Organization

XML to HTML Rendering

Convert C-CDA XML directly to HTML without parsing:

using CdaLib.Rendering;

// From XML string
var xmlString = File.ReadAllText("document.xml");
var renderer = new CdaHtmlRenderer(CcdaDocumentTypes.ContinuityOfCareDocument);
var html = renderer.RenderXmlToHtml(xmlString);
File.WriteAllText("output.html", html);

// From XDocument
var xdoc = XDocument.Load("document.xml");
var html2 = renderer.RenderXmlToHtml(xdoc);

// ONC Style renderer also supports XML input
var oncRenderer = new OncStyleHtmlRenderer(CcdaDocumentTypes.ContinuityOfCareDocument);
var oncHtml = oncRenderer.RenderXmlToHtml(xmlString);

Multiple Document Types

Generate different document types for different use cases:

// Discharge Summary
var dischargeService = new CdaService(CcdaDocumentTypes.DischargeSummary);
var (errors1, dischargeXml) = dischargeService.Export(ccd);

// Referral Note
var referralService = new CdaService(CcdaDocumentTypes.ReferralNote);
var (errors2, referralXml) = referralService.Export(ccd);

// Transfer Summary
var transferService = new CdaService(CcdaDocumentTypes.TransferSummary);
var (errors3, transferXml) = transferService.Export(ccd);

Backward Compatibility

Static helper methods are available for quick operations:

// Quick compile without service
var xml = CcdCompiler.CompileStatic(ccd, CcdaDocumentTypes.ContinuityOfCareDocument);

// Quick parse without service
var parsedCcd = CcdaParser.ParseStatic(xml, CcdaDocumentTypes.ContinuityOfCareDocument);

Custom Validation

Use the validator directly for more control:

using CdaLib.Validation;

// XSD validation only
var xsdErrors = CdaValidator.Validate(xmlPath, ValidationMode.Strict);

// Full conformance validation
var allErrors = CdaValidator.ValidateWithConformance(
    xmlDoc,
    ConformanceMode.Sender,
    CcdaDocumentTypes.ContinuityOfCareDocument
);

🏗️ Architecture

Key Components

• CdaService - Primary user-facing API
• CcdCompiler - Compiles domain models to C-CDA XML
• CcdaParser - Parses C-CDA XML to domain models
• CdaValidator - XSD and conformance validation
• ConformanceValidator - ONC sender/receiver conformance
• CcdaDocumentTypes - Document type definitions

Design Principles

1. Type Safety - Document types are strongly typed
2. Explicit Configuration - No hidden defaults, clear intent
3. Separation of Concerns - Parsing, compilation, and validation are distinct
4. Standards Compliance - Follows C-CDA 2.1 and ONC requirements
5. Flexibility - Support for both instance-based and static usage

🧪 Testing

The library includes comprehensive tests:

# Run all tests
dotnet test

# Run specific test categories
dotnet test --filter "FullyQualifiedName~OncTransitionOfCareTests"
dotnet test --filter "FullyQualifiedName~CcdCompilerTests"
dotnet test --filter "FullyQualifiedName~CdaServiceTests"

Test Categories

• OncTransitionOfCareTests - ONC 170.315(b)(1) scenario tests
• CcdCompilerTests - Compiler functionality and roundtrip tests
• CcdaParserTests - Parser functionality tests
• CdaServiceTests - Service workflow tests
• DocumentTypeTests - Document type configuration tests
• SenderConformanceTests - Sender conformance validation
• ReceiverConformanceTests - Receiver conformance validation

📖 Additional Resources

Standards References

• C-CDA 2.1 Implementation Guide
• USCDI V3 Specification
• ONC Health IT Certification

Online Tools

• ONC C-CDA Validator - Official validator
• C-CDA Scorecard - Document quality assessment

🤝 Contributing

When contributing, ensure:

1. All tests pass (dotnet test)
2. Code follows existing patterns
3. Document any new features
4. Validate against ONC online validator

📄 License

[Add your license information here]

🆘 Support

For issues or questions:

1. Check the documentation guides above
2. Review test examples in CdaLib.Tests/
3. Validate with the ONC online validator
4. Open an issue with specific error messages

Version: 1.1.0
Target Framework: .NET 8.0, .NET 9.0
C-CDA Version: 2.1
USCDI Version: V3
ONC Certification: 170.315(b)(1) Transitions of Care
NuGet Packages:

• CdaLib (1.1.0) - Core library
• CdaLib.Rendering (1.1.0) - HTML rendering (depends on CdaLib 1.1.0)