ccda-to-fhir
A Python library for converting C-CDA documents to FHIR R4B resources. Built for precision: the library implements the HL7 C-CDA on FHIR Implementation Guide and fails loudly on unexpected data rather than silently dropping information.
Installation
pip install ccda-to-fhir
Or with uv:
uv add ccda-to-fhir
Quick Start
from ccda_to_fhir import convert_document
with open("patient_record.xml") as f:
result = convert_document(f.read())
bundle = result["bundle"]
print(f"Converted {len(bundle['entry'])} resources")
Features
- Type Safety: Strict typing with Pydantic models and mypy validation
- Extensibility: Modular converter architecture for custom mappings
- Standards Compliance: FHIR R4B with US Core profile support, HL7 C-CDA on FHIR IG v2.0.0
Supported Conversions
| C-CDA Section | FHIR Resource |
|---|---|
| Patient (recordTarget) | Patient |
| Problems | Condition |
| Allergies | AllergyIntolerance |
| Medications | MedicationRequest, MedicationStatement, MedicationDispense |
| Immunizations | Immunization |
| Procedures | Procedure |
| Lab Results | DiagnosticReport, Observation |
| Vital Signs | Observation (vital-signs profile) |
| Social History | Observation |
| Encounters | Encounter |
| Care Plans | CarePlan, Goal |
| Care Teams | CareTeam |
| Payers | Coverage, Organization |
| Plan of Treatment | ServiceRequest |
| Notes (Note Activities, narrative-only sections, encounter diagnosis notes) | DocumentReference |
| Devices | Device |
| Authors/Performers | Practitioner, PractitionerRole, Device, Organization, Provenance |
Clinical Data Handling
- Complex structures: blood pressure components, pregnancy observations
- Provenance tracking with multi-author support (Practitioner, Device, Organization)
- Narrative-only section extraction (HPI, Physical Exam, ROS, Assessment, Reason for Visit)
- Encounter diagnosis notes from narrative tables
- Negation patterns: no-known-allergies, refuted conditions, not-done procedures
- Body site qualifiers with laterality
- Reference ranges for vital signs and lab results
- NullFlavor to data-absent-reason mapping
- US Core extensions (race, ethnicity, birth sex, tribal affiliation)
Tested EHR Integrations
The library has been validated against C-CDA documents from:
- Epic
- Cerner
- Athena
- Practice Fusion
- NIST reference documents
Error Handling
The library raises specific exceptions when it encounters data it cannot handle:
from ccda_to_fhir import convert_document
from ccda_to_fhir.exceptions import UnknownCodeSystemError, UnmappedValueError
try:
result = convert_document(xml_content)
except UnknownCodeSystemError as e:
print(f"Unknown code system OID: {e.oid}")
except UnmappedValueError as e:
print(f"Unmapped value '{e.value}' for {e.field}")
Conversion Metadata
Track what was processed during conversion:
result = convert_document(xml_content)
metadata = result["metadata"]
print(f"Processed: {len(metadata['processed_templates'])} templates")
print(f"Skipped: {len(metadata['skipped_templates'])} templates")
print(f"Errors: {len(metadata['errors'])}")
Development
git clone https://github.com/NurraHealth/ccda-to-fhir.git
cd ccda-to-fhir
uv sync --dev
uv run pytest
uv run ruff check .
uv run mypy ccda_to_fhir/
Releasing
- Bump
versioninpyproject.toml - Open a PR, get it approved, and merge to main
- Create a GitHub Release
- The publish workflow automatically builds and uploads to PyPI
Documentation
See docs/mapping/ for detailed field-level mapping documentation covering each resource type, including:
- Mapping Overview - Core data type mappings and conversion rules
- Terminology Maps - Value set translations between C-CDA and FHIR
License
MIT
Metadata
Release files for ccda-to-fhir 0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ccda_to_fhir-0.3.tar.gz | 1.3 MB | With provenance | Details for ccda_to_fhir-0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ccda_to_fhir-0.3-py3-none-any.whl | Python 3 | none | any | Details for ccda_to_fhir-0.3-py3-none-any.whl |
Total release size: 1.6 MB
Release files / ccda_to_fhir-0.3.tar.gz
| Download URL | ccda_to_fhir-0.3.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b10993286b65dc40bf3310787b126df63562a1854f559e0d23101f8c54ac2c44
|
|
BLAKE2b-256 checksum How to use checksums |
7f51c7c6e5109423f94162c4cfc1facff1d10ba88f5b4e943c18850fd926e091
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 24, 2026.
Transparency logRelease files / ccda_to_fhir-0.3-py3-none-any.whl
| Download URL | ccda_to_fhir-0.3-py3-none-any.whl |
|---|---|
| Size | 340.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
283da30342164cdc766ac355ae704a50dfb468022d9d9d76f4c76cdd854a360f
|
|
BLAKE2b-256 checksum How to use checksums |
b3dfce559d4f2fc1d75cddfb6145471aaebd91266fbcb86ca3313c424d174e28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 24, 2026.
Transparency logSecurity for ccda-to-fhir 0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ccda_to_fhir-0.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.