Skip to main content

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

  1. Bump version in pyproject.toml
  2. Open a PR, get it approved, and merge to main
  3. Create a GitHub Release
  4. The publish workflow automatically builds and uploads to PyPI

Documentation

See docs/mapping/ for detailed field-level mapping documentation covering each resource type, including:

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)

Source distribution for ccda-to-fhir 0.3
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)

Table of built distributions (wheels) for ccda-to-fhir 0.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page