usdm4-fhir 0.14.0

A python package for importing and exporting the CDISC TransCelerate USDM, version 4, using FHIR

USDM4 FHIR

A Python package for converting between CDISC TransCelerate Unified Study Data Model (USDM), version 4, and HL7 FHIR M11 message bundles.

Supports export (USDM to FHIR) and import (FHIR to USDM) for multiple FHIR profile versions, including PRISM2 and PRISM3 message formats, as well as a Madrid export variant.

Features

• Export USDM4 study definitions to FHIR M11 Bundle JSON (PRISM2, PRISM3, Madrid)
• Import FHIR M11 Bundle JSON back to USDM4 study definitions (PRISM2, PRISM3)
• Schedule of Activities export to FHIR
• Round-trip fidelity testing between USDM and FHIR representations
• Built on fhir.resources (Pydantic-based FHIR R5 models)

Installation

pip install usdm4_fhir

Quick Start

Export: USDM to FHIR

from usdm4_fhir.m11.export.export_prism3 import ExportPRISM3

exporter = ExportPRISM3(study, extra)
fhir_bundle_json = exporter.to_message()

Import: FHIR to USDM

from usdm4_fhir.m11.import_.import_prism3 import ImportPRISM3

importer = ImportPRISM3()
wrapper = await importer.from_message("path/to/fhir_bundle.json")
study = wrapper.study

Dependencies

• usdm4 (>=0.18.0) -- USDM4 API model and assembler
• fhir.resources (==7.1.0) -- FHIR R5 resource models
• d4k_ms_base (>=0.3.0) -- shared microservice base

Development

Setup

git clone https://github.com/data4knowledge/usdm4_fhir.git
cd usdm4_fhir
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

Commands

ruff format          # Format code
ruff check           # Lint
pytest               # Run tests

Regenerating integration test fixtures

The M11, SoA, and package integration tests (tests/usdm4_fhir/m11/test_m11_integration.py, tests/usdm4_fhir/soa/test_soa_integration.py, tests/usdm4_fhir/test_package_integration.py) compare exporter / importer output against committed golden files under tests/usdm4_fhir/test_files/. When you deliberately change exporter output shape — adding a new extension, renaming a field, splitting a single date carrier into typed sub-extensions — those goldens need to be regenerated.

Set UPDATE_FIXTURES=1 to put the integration helpers into save mode for that run:

# Regenerate all integration goldens
UPDATE_FIXTURES=1 pytest tests/

# Or scope to one test file / one test
UPDATE_FIXTURES=1 pytest tests/usdm4_fhir/m11/test_m11_integration.py
UPDATE_FIXTURES=1 pytest tests/usdm4_fhir/m11/test_m11_integration.py::test_from_fhir_prism3_asp8062

The committed source always reads SAVE = os.environ.get("UPDATE_FIXTURES") == "1", so CI cannot rubber-stamp a drifted fixture: no SAVE = True literal can be accidentally committed.

After a regeneration run, inspect the regenerated files via git diff before committing — the diffs are the actual shape change you intended, and a reviewer can scan them to confirm exporter and importer moved together.

How the import tests stay aligned with the exporter

The import-side tests in test_m11_integration.py::run_from_test and test_package_integration.py::run_from_m11_test are live round-trip tests, not static-fixture tests. For each protocol they:

1. Read the canonical USDM input and _extra.yaml hints from the export side (tests/usdm4_fhir/test_files/m11/export/<version>/<name>_{usdm.json,extra.yaml}).
2. Run today's exporter against that input.
3. Stage the generated FHIR bundle in a tempfile.mkdtemp directory.
4. Run today's importer against that bundle.
5. Assert the resulting USDM matches the committed tests/usdm4_fhir/test_files/m11/import/<version>/<name>_usdm.json golden.

This makes import / export drift impossible by construction — the import test always sees the exporter's current output shape rather than a frozen FHIR fixture that lags behind the exporter. The two halves cannot disagree silently.

There are no static <name>_fhir.json files under tests/usdm4_fhir/test_files/m11/import/<version>/; if you find one in a future PR, something has regressed.

Build and Publish

python3 -m build --sdist --wheel
twine upload dist/*

Project Structure

src/usdm4_fhir/
  factory/        FHIR resource factories (ResearchStudy, PlanDefinition, etc.)
  m11/
    export/       USDM to FHIR export (PRISM2, PRISM3, Madrid)
    import_/      FHIR to USDM import (PRISM2, PRISM3)
    utility/      Shared utilities (address service, HTML parsing, tag references)
  soa/
    export/       Schedule of Activities FHIR export
  utility/        Data store
tests/            Integration test suite with round-trip verification

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.