FHIR Resources (Python)

8.2.0 · active · verified Tue Mar 17

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.

Warnings

breaking fhir.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.
breaking Default 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.*.
breaking Pydantic 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().
gotcha The 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.
gotcha FHIR 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.
gotcha resourceType 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'.

Install

pip install fhir.resources Python (latest, FHIR R5 default)
pip install 'fhir.resources[r4]' Python (with R4 extras)

Imports

Patient
```
from fhir.resources.patient 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
```
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.

Quickstart

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'

view raw JSON →