oehrpy

How openEHR Works: the Data Lifecycle

Where oehrpy fits in the openEHR data lifecycle — from clinical modelling to querying patient data. Phases highlighted in blue are handled by oehrpy.

Phase 1ModellingOutside oehrpy
Archetype Designer
Define archetypes & templates using clinical modelling tools (e.g. Better Archetype Designer)
Export .opt
Export an Operational Template (.opt) file from the modelling tool
Phase 2CDR UploadOutside oehrpy
Upload Template
Upload the .opt to your CDR (e.g. EHRBase) via its admin API
Web Template
CDR generates a Web Template with FLAT paths and constraints
oehrpy scope
Phase 3App Developmentoehrpy
Parse OPT
Parse .opt files with OPTParser to extract template metadata
Fetch Web Template
Get Web Template JSON from CDR with get_web_template() for FLAT paths (ADR-0005)
Generate Builder
Generate metadata-only builder skeletons with BuilderGenerator; FLAT paths from Web Template
Validate Template
Validate OPT files against RM spec using OPTValidator
Validate Composition
Catch FLAT path errors before submission with FlatValidator
Phase 4Write Compositionoehrpy
Template Builder
Construct compositions with type-safe builders (e.g. VitalSignsBuilder)
FLAT Format
Build FLAT compositions with FlatBuilder using slash-separated paths
Canonical JSON
Serialize RM objects to openEHR canonical JSON with _type fields
Submit to CDR
Send compositions via EHRBaseClient async REST client
Phase 5Read / Queryoehrpy
AQL Builder
Build type-safe AQL queries with AQLBuilder fluent API
Execute Query
Run AQL queries against the CDR via EHRBaseClient
Deserialize
Parse query results back into typed RM objects for processing
Format Reference
.optOperational Template — XML file exported from modelling tools
Web TemplateCDR-generated JSON with FLAT paths and constraints
FLATSlash-separated paths like bp:0/systolic|magnitude
Canonical JSONHierarchical JSON with _type discriminator fields
AQLArchetype Query Language for retrieving clinical data
RMReference Model — 134 Pydantic classes for openEHR 1.1.0
oehrpy scope (Phases 3–5)
External tools (Phases 1–2)

What is openEHR?

openEHR is an open, vendor-neutral standard for electronic health records. Its central idea is two-level modelling: software only has to understand a small, stable Reference Model, while the clinical meaning (what a blood pressure reading or an allergy record contains) is defined separately by clinicians in archetypes and templates. The same data can then be stored, exchanged and queried by any openEHR system, and new clinical content does not require new database schemas or code releases.

Key concepts

Reference Model (RM)
The generic building blocks every openEHR system implements: COMPOSITION, OBSERVATION, ELEMENT, and data types such as DV_QUANTITY and DV_CODED_TEXT. oehrpy provides all 134 RM 1.1.0 classes as type-safe Pydantic models.
Archetype
A reusable, clinician-authored definition of one clinical concept, such as blood pressure or body temperature, built from RM types. Archetypes are shared internationally, for example through the openEHR Clinical Knowledge Manager.
Template and OPT
A template combines and constrains archetypes for one use case, e.g. a vital signs form. Modelling tools export it as an Operational Template (.opt, XML), the file you upload to a CDR. oehrpy can parse and validate OPTs.
Web Template
A simplified JSON rendering of an OPT that the CDR generates. It lists every field with its FLAT path, type and constraints, which makes it the authoritative source for FLAT paths. Browse one with the template explorer.
EHR and composition
Each patient has one EHR. Clinical data is committed to it as compositions, one document per encounter or recording, each conforming to a template and versioned on every change.
Canonical JSON and FLAT
Two JSON serializations of a composition. Canonical JSON is the full RM tree with _type fields; FLAT is a map of path|attribute keys that is much easier to produce from an application. See the serialization guide or try the converter.
CDR
A Clinical Data Repository stores EHRs and compositions and exposes the openEHR REST API. EHRBase is the leading open-source CDR; oehrpy ships an async EHRBase client.
AQL
The Archetype Query Language queries data across all EHRs by archetype paths rather than table columns, so the same query works on any openEHR CDR. oehrpy has a fluent AQL builder.

The five phases

1. Modelling

Clinical modellers pick or author archetypes and assemble them into a template in a tool such as Archetype Designer, then export the operational template (.opt).

2. Uploading to the CDR

The OPT is uploaded to the CDR, which from then on accepts compositions for that template and can serve its Web Template.

3. Application development

Developers fetch the Web Template, check the OPT with OPTValidator, and generate or write template builders so the application produces correctly shaped data. This is where oehrpy starts to help.

4. Writing compositions

The application fills a builder (or builds FLAT or canonical JSON directly), validates it with FlatValidator, and commits it to the patient's EHR through the CDR's REST API.

5. Reading and querying

Data is read back per composition or queried across the population with AQL. Results can be deserialized into typed RM objects for further processing.

Next steps

Install oehrpy with pip install oehrpy and follow the getting started guide, or paste your own templates into the validator, converter and explorer to see these concepts in action.