Python Typings For FHIR

The FHIR Types package exports types declared using the typing library. This provides type checking support when creating dictionaries of FHIR objects in Python.

Installation

Installing from Pypi (recommended)

We recommend you first use a virtual environment and activate it in your shell.

pip install fhir-types

Installing from source

1. Clone this repository
2. Change to the package root directory
3. Run the pipenv install --dev --deploy command to create and install in a virtual environment

% pipenv install --dev --deploy
Creating a virtualenv for this project...
Pipfile: /fhir-types/Pipfile
Using /usr/local/bin/python3 (3.9.7) to create virtualenv...
. . .

If you want to install globally run pip install ., outside of a virtual environment.

Verify the installation

Verify the installation with pipenv run almake test.

% pipenv run almake test
python -m black --check .
All done! ✨ 🍰 ✨
702 files would be left unchanged.
python -m isort --check --df .
. . .

Or, if you have make installed:

% pipenv run make test

Usage

This project was developed using mypy for type checking.

Example

Consider these two FHIR JSON dictionaries.

# myfile.py

from fhir_types import FHIR_Patient

# This is a valid patient dictionary
patient: FHIR_Patient = {
    "resourceType": "Patient",
    "gender": "female",
    "name": [
        {
            "use": "official",
            "family": "Johnson",
            "given": ["Jennifer"],
            "prefix": ["Mrs."],
        }
    ]
}

# This is an invalid patient dictionary
invalid_patient: FHIR_Patient = {
    "resourceType": "PPPPatient", # error 1
    "gender": "female123",  # error 2
    "name": [
        {
            "123use": "official", # error 3
            "family": "Johnson",
            "given": ["Jennifer"],
            "prefix": ["Mrs."],
        }
    ]
}

After installing mypy with pip, running mypy myfile.py will display the errors in the second (invalid) structure.

It is good practice to set up your IDE (such as VS Code) to use mypy for linting as you work.

Issues

The Types located in the fhir_types directory are generated from the official fhir.schema.json provided by FHIR.

This data stucture is quite large with and contains cyclical relationships. Unfortunately, mypy does not handle cyclical relationships and has an open issue here. We added a workaround that reduces the type checking capabilities for certain properties in some classes.

All properties that point to any of the following classes are given an Any type because these lead to circular references. These were found by repeatedly running the mypy command.

CIRCULAR_REFERENCES = {
    "Extension",
    "Identifier",
    "ResourceList",
    "QuestionnaireResponse_Answer",
    "GraphDefinition_Link",
    "ExampleScenario_Process",
    "ExampleScenario_Alternative",
}

The other case is when a property points back to a parent class.

from fhir_types import FHIR_Questionnaire_Item

FHIR_Questionnaire_Item = TypedDict("FHIR_Questionnaire_Item", {
    "id": "123",
    item: List[Any] # This used to be FHIR_Questionnaire_Item but was changed to Any
})

Here, full type checking can be accomplished by creating two separate dictionaries and then combining them. For example:

from fhir_types import FHIR_Extension, FHIR_Patient

extension: FHIR_Extension = {
    "valueAddress": {
        "city": "Springfield",
        "state": "Massachusetts",
        "country": "US"
    }
}

patient: FHIR_Patient = {
    "gender": "male",
    "extension": [extension]
}