CdaLib 1.21.0

CdaLib

Proprietary Software. This software is proprietary. Unauthorized copying, distribution, modification, or use is prohibited. All rights reserved. This notice applies to the CdaLib and CdaLib.Rendering codebases and to all documentation in this repository.

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
• ✅ Section Filtering - Selectively include/exclude sections during parsing and compilation ⭐ NEW
• ✅ FHIR Bundle Support - Convert FHIR R4 bundles to C-CDA documents and vice versa ⭐ 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
• ✅ JSON Validation API - Validate C-CDA documents and get detailed results in JSON format ⭐ NEW
• ✅ 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.21.0

HTML Rendering (Optional):

dotnet add package CdaLib.Rendering --version 1.21.0

Or via Package Manager:

Install-Package CdaLib -Version 1.21.0
Install-Package CdaLib.Rendering -Version 1.21.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: Validate C-CDA XML and get JSON results with line numbers
var validationJson = service.Validate("input.xml");
// Or validate from XML string
var validationJson2 = service.Validate(xmlString);

// NEW: Import with FileInfo overload
var fileInfo = new FileInfo("input.xml");
var (errors, ccd) = service.Import(fileInfo);

// 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.ExportFromFhir(fhirBundle);

// NEW: Convert CCD to FHIR Bundle
using CdaLib.Mapping;
var fhirBundleFromCcd = CcdToFhirMapper.MapToFhirBundle(parsedCcd);

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

📚 Documentation

All documentation in this repository is proprietary and subject to the same terms as the software.

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 and CCD to FHIR

🏥 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 Conversion (Bidirectional)

Convert between FHIR R4 bundles and C-CDA documents in both directions:

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.ExportFromFhir(bundle);

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

FHIR to C-CDA (FhirToCcdMapper):

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

C-CDA to FHIR (CcdToFhirMapper) ⭐ NEW:

• ✅ Patient → FHIR Patient
• ✅ Allergies → FHIR AllergyIntolerance
• ✅ Problems → FHIR Condition
• ✅ Medications → FHIR MedicationStatement
• ✅ Procedures → FHIR Procedure
• ✅ Immunizations → FHIR Immunization
• ✅ Encounters → FHIR Encounter
• ✅ Results → FHIR Observation (laboratory)
• ✅ Vital Signs → FHIR Observation (vital-signs)
• ✅ Social History → FHIR Observation (social-history)
• ✅ Goals → FHIR Goal
• ✅ Care Team → FHIR CareTeam
• ✅ Author → FHIR Practitioner
• ✅ ProviderOrganization → FHIR 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);

Section Filtering ⭐ NEW

Control which sections are displayed when rendering CCDA documents to HTML. This feature allows you to selectively show only the sections you need in the HTML output, customizing the display according to user preferences.

By default, all sections are rendered (backward compatible behavior). Section filtering is optional and only applies when a SectionFilter is explicitly configured on the HTML renderer.

Exclusion Mode (Blacklist)

Exclude specific sections from HTML rendering while including all others:

using CdaLib.Rendering;

// Exclude specific sections from HTML rendering
var filter = new SectionFilter();
filter.Exclude(CdaSection.VitalSigns);
filter.Exclude(CdaSection.Results);

var renderer = new CdaHtmlRenderer(documentType);
renderer.SectionFilter = filter;
var html = renderer.RenderToHtml(ccd);
// HTML will not include VitalSigns and Results sections

Inclusion Mode (Whitelist)

Include only specific sections in HTML rendering, excluding all others:

using CdaLib.Rendering;

// Only include Problems, Medications, and Allergies in HTML
var whitelistFilter = new SectionFilter(new[] { 
    CdaSection.Problems, 
    CdaSection.Medications,
    CdaSection.Allergies 
});

var renderer = new CdaHtmlRenderer(documentType);
renderer.SectionFilter = whitelistFilter;
var html = renderer.RenderToHtml(ccd);
// HTML will only include Problems, Medications, and Allergies sections

Available Sections

The CdaSection enum provides type-safe section identifiers:

• CdaSection.Problems - Problems and conditions
• CdaSection.Medications - Medications
• CdaSection.Allergies - Allergies and intolerances
• CdaSection.VitalSigns - Vital signs
• CdaSection.Results - Laboratory results
• CdaSection.Procedures - Procedures
• CdaSection.Immunizations - Immunizations
• CdaSection.Encounters - Encounters
• CdaSection.PlanOfCare - Plan of care
• CdaSection.SocialHistory - Social history
• CdaSection.FunctionalStatus - Functional status
• CdaSection.Goals - Goals
• CdaSection.HealthConcerns - Health concerns
• CdaSection.Notes - Clinical notes
• And more... (see CdaSection enum for complete list)

Advanced Usage

using CdaLib.Rendering;

// Create filter with exclusion mode constructor
var exclusionFilter = new SectionFilter(
    new[] { CdaSection.VitalSigns, CdaSection.Results }, 
    isExclusionMode: true
);

// Dynamically modify filter
var filter = new SectionFilter();
filter.Exclude(CdaSection.VitalSigns);
filter.Include(CdaSection.Problems);  // Switches to whitelist mode
filter.RemoveFromExclude(CdaSection.VitalSigns);  // Remove from exclusion
filter.Clear();  // Reset to include all sections

// Check filter state
bool isWhitelist = filter.IsWhitelistMode;
var included = filter.IncludedSections;
var excluded = filter.ExcludedSections;

// Apply to renderer
var renderer = new CdaHtmlRenderer(documentType);
renderer.SectionFilter = filter;
var html = renderer.RenderToHtml(ccd);

Note: Section filtering is available in the CdaLib.Rendering package and uses semantic section names (CdaSection enum) rather than template IDs, providing a cleaner API that hides internal implementation details. Both CdaHtmlRenderer and OncStyleHtmlRenderer support section filtering.

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
);

JSON Validation API ⭐ NEW

Validate C-CDA documents and get detailed results in JSON format with line numbers:

using CdaLib;
using System.IO;

var service = new CdaService(CcdaDocumentTypes.ContinuityOfCareDocument);

// Validate from file path
var jsonResult = service.Validate("document.xml");
// Returns JSON with errors, warnings, line numbers, and XPath

// Validate from FileInfo
var fileInfo = new FileInfo("document.xml");
var jsonResult2 = service.Validate(fileInfo);

// Validate from XML string
var xmlContent = File.ReadAllText("document.xml");
var jsonResult3 = service.Validate(xmlContent);

// Example JSON response:
// {
//   "status": "error",
//   "message": "Validation found 2 error(s) and 3 warning(s)",
//   "fileName": "document.xml",
//   "errors": [
//     {
//       "lineNumber": 45,
//       "fieldName": "patient.name",
//       "importance": "Required",
//       "message": "Patient name is required",
//       "xPath": "/ClinicalDocument/recordTarget/patientRole/patient/name"
//     }
//   ],
//   "warnings": [
//     {
//       "lineNumber": 120,
//       "fieldName": "medication.dose",
//       "importance": "Recommended",
//       "message": "Medication dose is recommended",
//       "xPath": "/ClinicalDocument/component/structuredBody/component/section/entry/substanceAdministration/doseQuantity"
//     }
//   ]
// }

🏗️ 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"

Code coverage

Code coverage is collected for CdaLib and CdaLib.Rendering using Coverlet. Coverage is restricted to these two assemblies (test projects are excluded).

Run tests with coverage locally:

dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults --settings coverlet.runsettings

Coverage files (Cobertura XML) are written under TestResults per test project. To generate a merged HTML report locally, install ReportGenerator and run:

dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator -reports:"**/TestResults/**/coverage.cobertura.xml" -targetdir:./coveragereport -reporttypes:Html;TextSummary

Open coveragereport/index.html to view the report. In CI, coverage is collected the same way and the HTML report is uploaded as an artifact.

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.21.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.21.0) - Core library
• CdaLib.Rendering (1.21.0) - HTML rendering (depends on CdaLib 1.21.0)

FHIR (CdaLib): CdaLib depends on Hl7.Fhir.R4 5.12.2 (FHIR R4). This version is compatible with .NET 8 and .NET 9 and is aligned with common EHR integrations (e.g. ThyraEHR). The 5.12.x line is backward compatible; upgrading from 5.0.x is supported.