Registry / serialization / fhir-resources

fhir-resources

library8.3.0pypypi✓ verified 28d ago

Python library for FHIR (Fast Healthcare Interoperability Resources) providing Pydantic-based models for all FHIR resource types. Supports FHIR R4, R4B, R5, STU3, and DSTU2. Built on Pydantic v2 for validation, serialization, and deserialization of FHIR JSON. Current version targets FHIR R5 by default with backwards-compatible imports for older FHIR versions.

serialization data

pip install fhir.resources

github ↗package ↗

INSTALL

IMPORT

SIG · FHIR-RESOURCES

fhir-resources

serializationpythonv8.3.0

Install

4.8s avg

Import

564ms

Disk

51MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.473s · 52.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 4.8s · import 0.429s · 52MB

51MB installed

● package 51MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Patient

✓ from fhir.resources.patient import Patient

✗ from fhir_resources import Patient

The package uses a namespace package 'fhir.resources'. Each resource type is in its own module with a lowercase name.

Patient (R4)

✓ from fhir.resources.R4B.patient import Patient

✗ from fhir.resources.patient import Patient # this gives R5

To use FHIR R4B resources, import from fhir.resources.R4B subpackage. Default top-level imports are R5.

Patient (STU3)

✓ from fhir.resources.STU3.patient import Patient

STU3 resources live under the fhir.resources.STU3 subpackage.

Bundle

✓ from fhir.resources.bundle import Bundle

Each FHIR resource is its own module. Import the class with the CamelCase name from the lowercase module.

Create, validate, and serialize a FHIR Patient resource using Pydantic v2 methods.

from fhir.resources.patient import Patient # Create from dict patient_data = { "resourceType": "Patient", "id": "example", "active": True, "name": [ { "use": "official", "family": "Doe", "given": ["John"] } ], "gender": "male", "birthDate": "1990-01-01" } patient = Patient.model_validate(patient_data) print(patient.name[0].family) # 'Doe' # Serialize back to FHIR JSON print(patient.model_dump_json(indent=2)) # Parse from JSON string json_str = patient.model_dump_json() patient2 = Patient.model_validate_json(json_str) print(patient2.id) # 'example'

Debug

Known issues

breakingfhir.resources 7.x+ requires Pydantic v2. Projects still on Pydantic v1 must use fhir.resources 6.x.

fix

Either upgrade to Pydantic v2 (pip install 'pydantic>=2.0') or pin fhir.resources<7.0.0 for Pydantic v1 compatibility.

affects: >= 7.0.0

breakingDefault FHIR version changed from R4B to R5 in fhir.resources 7.x+. Top-level imports now return R5 models.

fix

For R4B resources, import from fhir.resources.R4B.* subpackage instead of top-level fhir.resources.*.

affects: >= 7.0.0

breakingPydantic v2 migration changed validation and serialization methods. .parse_obj() and .json() are replaced.

fix

Use Patient.model_validate(data) instead of Patient.parse_obj(data), and patient.model_dump_json() instead of patient.json().

affects: >= 7.0.0

gotchaThe package installs as a namespace package (fhir.resources). Do not create your own 'fhir' package in your project or it will shadow the library.

fix

Avoid naming your own modules or packages 'fhir' to prevent import conflicts.

affects: all

gotchaFHIR resource validation is strict by default. Missing required fields or invalid value sets will raise ValidationError.

fix

Catch pydantic.ValidationError and inspect e.errors() for details on which fields failed validation.

affects: all

gotcharesourceType field must match the class name exactly. Passing resourceType='patient' (lowercase) will raise a validation error.

fix

Always use the exact CamelCase resourceType, e.g. 'Patient', 'Observation', 'Bundle'.

affects: all

breakingfhir.resources 7.x+ relies on Pydantic v2, which may utilize type annotations incompatible with Python 3.9 or earlier (e.g., the `|` union operator syntax introduced in Python 3.10). This can lead to a `TypeError` during model import or evaluation.

fix

Upgrade your Python environment to 3.10 or newer to ensure compatibility with Pydantic v2's type hint evaluation. If unable to upgrade Python, consider pinning `fhir.resources<7.0.0` for Pydantic v1 compatibility (as per warning #0).

affects: >= 7.0.0

Errors

Common errors & fixes

pydantic.ValidationError: X validation error for Y

Input data provided to a FHIR resource constructor does not conform to the FHIR specification's data model, such as incorrect data types, missing required fields, or invalid formats, which Pydantic then flags.

fix

Review the FHIR specification for the specific resource and its fields, ensuring that all required fields are present and data types/formats (e.g., dates, codes, quantities) match the expected schema for the FHIR version being used.

AttributeError: 'NoneType' object has no attribute 'serialize'

A preceding operation, such as a search or retrieval, failed to find a FHIR resource and returned 'None', on which a subsequent method (like '.serialize()' or any other attribute access) was then attempted.

fix

Add a check to verify that the returned object is not 'None' before attempting to access its attributes or methods. For example, `resource = Patient.get('some_id')` should be followed by `if resource: resource.serialize()`.

ModuleNotFoundError: No module named 'fhir.resources.R4.patient'

Attempting to import a FHIR resource from an incorrect or non-existent version-specific submodule. While `fhir-resources` version 8.2.0 defaults to FHIR R5, older versions (like R4, R4B, STU3) are available in specific submodules, and incorrect paths will lead to this error.

fix

For FHIR R5 resources, import directly from `fhir.resources`, e.g., `from fhir.resources.patient import Patient`. For older FHIR versions, ensure you are importing from the correct versioned submodule, e.g., `from fhir.resources.R4.patient import Patient` for R4, or `from fhir.resources.STU3.patient import Patient` for STU3.

Upgrade

Version history

8.3.0latest on PyPI · released Jul 3, 2026

Audit

Dependencies

pydanticrequiredCore dependency. fhir.resources 8.x requires Pydantic v2. Pydantic v1 is not supported.

orjsonoptionalOptional faster JSON serializer. Used automatically if installed.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/nazrulworld/fhir.resources ↗

packagehttps://pypi.org/project/fhir-resources/ ↗