oehrpy
Docs: Reference Model

openEHR Reference Model Classes in Python

oehrpy ships all 134 classes of the openEHR Reference Model (RM) 1.1.0, including the BASE types, as Pydantic v2 models generated from the official specifications. They validate on construction and type-check with mypy, so invalid clinical data fails in your editor rather than at the CDR.

RM Classes

The Reference Model (RM) classes form the foundation of oehrpy. These are type-safe Pydantic models that represent openEHR data structures.

New in RM 1.1.0: Support for DV_SCALE (decimal scale values), preferred_term field in CODE_PHRASE, and enhanced Folder support. All 134 types include both RM and BASE components.

Data Types

oehrpy includes all major openEHR data types:

Text and Coded Values

from oehrpy.rm import DV_TEXT, DV_CODED_TEXT, CODE_PHRASE, TERMINOLOGY_ID

# Simple text
text = DV_TEXT(value="Blood pressure measurement")

# Coded text with terminology
status = DV_CODED_TEXT(
    value="Normal",
    defining_code=CODE_PHRASE(
        terminology_id=TERMINOLOGY_ID(value="local"),
        code_string="at0001"
    )
)

Quantities and Measurements

from oehrpy.rm import DV_QUANTITY, DV_COUNT

# Blood pressure (quantity with units)
systolic = DV_QUANTITY(
    magnitude=120.0,
    units="mm[Hg]",
    property=CODE_PHRASE(
        terminology_id=TERMINOLOGY_ID(value="openehr"),
        code_string="382"  # Pressure
    )
)

# Heart rate (count)
heart_rate = DV_COUNT(magnitude=72)

Date and Time

from oehrpy.rm import DV_DATE_TIME, DV_DATE, DV_TIME, DV_DURATION

# Date and time
timestamp = DV_DATE_TIME(value="2024-01-15T14:30:00Z")
date = DV_DATE(value="2024-01-15")
time = DV_TIME(value="14:30:00")

# Duration
duration = DV_DURATION(value="PT2H30M")  # 2 hours 30 minutes

Structures

Build complex clinical structures using openEHR structural types:

from oehrpy.rm import ELEMENT, CLUSTER, ITEM_TREE

# Create an element
bp_element = ELEMENT(
    name=DV_TEXT(value="Systolic"),
    value=systolic
)

# Group elements in a cluster
bp_cluster = CLUSTER(
    name=DV_TEXT(value="Blood Pressure"),
    items=[bp_element, ...]
)

Data Types Reference

Complete list of available RM data types:

Basic Types

Quantitative Types

Using DV_SCALE (RM 1.1.0)

from oehrpy.rm import DV_SCALE, DV_CODED_TEXT, CODE_PHRASE, TERMINOLOGY_ID

# Pain scale with decimal value
pain_scale = DV_SCALE(
    value=7.5,  # Decimal scale value
    symbol=DV_CODED_TEXT(
        value="Severe pain",
        defining_code=CODE_PHRASE(
            terminology_id=TERMINOLOGY_ID(value="local"),
            code_string="at0075",
            preferred_term="Severe"  # New in RM 1.1.0
        )
    )
)

Temporal Types

Complex Types

RM Validation

oehrpy uses Pydantic v2 for comprehensive validation.

Automatic Validation

from pydantic import ValidationError
from oehrpy.rm import DV_QUANTITY

try:
    # This will raise a validation error
    invalid = DV_QUANTITY(
        magnitude="not a number",  # Should be float
        units="mm[Hg]"
    )
except ValidationError as e:
    print(e)

Custom Validation

All RM classes support Pydantic's validation features:

from pydantic import ValidationError

# Validate required fields
try:
    text = DV_TEXT()  # Missing required 'value' field
except ValidationError as e:
    print(e.errors())

Type Safety

Full type hints enable IDE autocomplete and static type checking.

Using mypy

# Type checking with mypy
from oehrpy.rm import DV_TEXT, DV_QUANTITY

text: DV_TEXT = DV_TEXT(value="example")  # OK
quantity: DV_QUANTITY = DV_TEXT(value="wrong")  # mypy error

IDE Support

Modern IDEs like VS Code, PyCharm, and others provide full autocomplete: