Canonical JSON & FLAT Serialization

openEHR compositions travel as JSON in two main shapes. Canonical JSON is the standard serialization of the Reference Model, a nested tree where every object carries a _type. FLAT is the simplified format used by EHRBase and Better: a single map of path|attribute keys. oehrpy converts RM objects to and from canonical JSON and helps you build FLAT compositions. To try the conversion without writing code, use the Canonical JSON ⇄ FLAT converter.

Canonical JSON

Canonical JSON is the standard openEHR format with _type fields:

from oehrpy.serialization import to_canonical, from_canonical
from oehrpy.rm import DV_QUANTITY

# Serialize to canonical JSON
quantity = DV_QUANTITY(magnitude=120.0, units="mm[Hg]", ...)
canonical = to_canonical(quantity)
# {"_type": "DV_QUANTITY", "magnitude": 120.0, "units": "mm[Hg]", ...}

# Deserialize from canonical JSON
restored = from_canonical(canonical, expected_type=DV_QUANTITY)

FLAT Format

FLAT format is EHRBase's simplified format using paths:

from oehrpy.serialization import FlatBuilder

# For EHRBase 2.x, use the template's composition tree ID as the prefix
builder = FlatBuilder(composition_prefix="vital_signs_observations")
builder.context(language="en", territory="US", composer_name="Dr. Smith")
builder.set_quantity("vital_signs_observations/vital_signs/blood_pressure/systolic", 120.0, "mm[Hg]")
builder.set_text("vital_signs_observations/vital_signs/notes", "Patient stable")

flat_data = builder.build()