openEHR is an open specification for storing clinical data in a way that outlives any single application. For developers, it changes the usual order of work: instead of designing database tables for each form, you build on a fixed reference model and let clinical models, called archetypes and templates, define the content.
This guide explains openEHR from the developer's seat: the classes you will touch, how a template becomes something an app can write, how compositions are stored and versioned, how AQL queries them, and where newcomers tend to trip up.
What is openEHR, from a developer's point of view?
Need engineers who work across openEHR and FHIR?
Agnotic provides FHIR developers and healthcare data engineers who build on clinical data repositories and expose them through standard APIs.
For a developer, openEHR is a fixed, generic information model plus a library of clinical models that constrain it. Applications write and read compositions through a clinical data repository's REST API, validated against templates, and query them with AQL. The database schema never changes when clinicians add a new form.
That separation is the point. Clinical modelers maintain the archetypes and templates. Developers maintain the software. A new blood pressure field or a new assessment form is a model change, uploaded to the repository, rather than a schema migration.
What does the two-level model separate?
The two-level model separates the generic structure of health records from the clinical content inside them. The first level is the reference model, which every openEHR system implements in code. The second level is the archetypes and templates, which define clinical concepts and forms as constraints on that reference model.
- Reference model: Classes such as EHR, COMPOSITION, OBSERVATION and DV_QUANTITY, implemented once by the repository and client libraries.
- Archetypes: Reusable models of single clinical concepts, such as blood pressure or a problem diagnosis, written in the Archetype Definition Language.
- Templates: Combinations of archetypes for a specific use, such as a diabetes review form, that narrow and remove elements for that context.
- Operational templates: The compiled form of a template that a repository loads and validates data against.
The archetype layer is formally specified in the openEHR Archetype Model, whose current release, AM 2.3.0, was published in March 2024, and the Archetype Model was adopted by ISO as ISO 13606-2:2019. ADL 1.4 and ADL 2 are both in use, so check which version a repository and its modeling tools expect before building templates.
Which reference model classes do developers touch most?
Developers mostly touch the classes that hold a patient's record, a document within it, the clinical entries in that document and the data values inside them. Knowing these is enough to read most openEHR data.
- EHR: The top-level record for one patient, identified by an ehr_id, with an EHR_STATUS that links it to external patient identifiers.
- COMPOSITION: The unit of commit, similar to a document or a form submission, with a category, context such as time and setting, and content.
- OBSERVATION: Measured or observed data over time, such as vital signs, held as a history of events.
- EVALUATION: Clinical opinions and summaries, such as a diagnosis or a risk assessment.
- INSTRUCTION and ACTION: Orders and the steps taken to carry them out, such as a medication order and each administration.
- ADMIN_ENTRY: Administrative content, such as an admission event.
- Data values: Types such as DV_QUANTITY for a value with units, DV_CODED_TEXT for a coded term and DV_DATE_TIME for timestamps.
Every element in an archetype has a path, built from node identifiers, such as the path to the systolic value inside a blood pressure observation. Paths are how forms, mappings and queries point at data, so they become part of the application's vocabulary.
How do you build on openEHR step by step?
Building on openEHR follows the two-level model from the bottom up. The reference model sits underneath, implemented by the repository. Archetypes constrain it for single concepts. Templates combine archetypes into a use case. The operational template is what the application writes against.
1. Find archetypes: Search a Clinical Knowledge Manager for published archetypes that match the concepts the form needs, before modeling anything new.
2. Design the template: Combine those archetypes into a template for the use case, removing unused elements, setting cardinalities and binding terminology.
3. Export the operational template: Compile the template to an operational template file that the repository can load.
4. Upload to the repository: Register the operational template with the clinical data repository through its definition API.
5. Generate examples: Ask the repository or tooling for an example composition or a simplified web template, which shows the paths and data types the app must fill.
6. Map the app: Connect form fields or incoming data to template paths, including units and coded values.
7. Commit compositions: Create the patient's EHR if it does not exist, then post compositions through the REST API, where the repository validates them against the template.
8. Query and expose: Read data back with AQL, and where other systems need it, expose it through a FHIR layer with documented mappings.
Most repositories accept compositions in canonical JSON or XML, and many also accept simplified flat or structured formats generated from the web template, which are easier for application code to produce. Pick one format per application and validate every write against the template in test before go-live, including writes with optional elements left empty.
How does AQL query clinical data?
AQL, the Archetype Query Language, queries clinical data by archetype paths rather than by tables. A query names the classes and archetypes it wants with a CONTAINS clause, selects values by path and filters with WHERE, so the same query works on any repository that stores data from those archetypes.
A typical query reads: select the systolic and diastolic values from every EHR that contains a composition that contains a blood pressure observation, where the systolic value is above a threshold. Because it is written against the archetype, it finds the data whichever template captured it.
- Population queries: Run across all EHRs for cohorts, registries and quality measures.
- Patient queries: Restrict to one ehr_id for an application screen.
- Stored queries: Register common queries in the repository and call them by name from apps.
- Performance: Test queries on realistic volumes early, since performance depends on the repository's indexing of paths.
Versioning and audit in the repository
openEHR repositories version every composition. Updating a composition creates a new version rather than overwriting the old one, and each change is recorded in a contribution with an audit entry stating who committed it, when and why.
This gives applications a medico-legal history for free, but it changes how updates are written. A client updating a composition must send the version it is replacing, so concurrent edits are detected, and deletions mark a version as deleted rather than removing it.
Persistent compositions, such as a problem list or medication list, are updated in place as new versions over time. Event compositions, such as a single encounter note, are usually created once. Choosing the right category up front avoids confusing histories. Decide it per template and document it, because changing a category after go-live means migrating data that has already been committed.
Who governs the clinical models?
Clinical models need governance as much as code does. A small group of clinical modelers and clinicians should own which archetypes the organization uses, approve new templates and decide when a template version changes. Without that group, templates multiply and the same concept gets captured several ways.
Treat templates like code. Keep them in version control, review changes, give each release a version number and record which applications write against which template version. When a template changes, the repository keeps older data valid against the version it was committed under, and queries written against archetype paths keep working.
Reuse beats local invention. Archetypes published through a Clinical Knowledge Manager have been reviewed by clinicians from many organizations, and using them keeps data queryable alongside other openEHR systems. When a local need is real, propose a change or a specialization rather than a parallel model.
Developers have a part in this process. They report where a template is hard to fill from real data, where units or terminology bindings are missing, and where a form needs an element the template removed. Those reports feed the next template release.
Where developers trip up with openEHR
Developers new to openEHR usually trip up on modeling and tooling rather than code. These failure points are worth checking on any first project.
- Modeling from scratch: Creating local archetypes when published ones exist, which breaks query portability.
- Template sprawl: A new template for every small form change, with no governance or versioning.
- Path guessing: Hand-building paths instead of generating them from the operational template.
- Mixed ADL versions: Tools, archetypes and repository expecting different ADL versions.
- Ignoring units and terminology: Free-text values where the archetype expects quantities with units or coded terms.
- No identity link: EHRs created without a reliable link to the patient identifier used by other systems.
- FHIR as an afterthought: Exposing data through FHIR without documented mappings, so each consumer interprets it differently.
How Agnotic can help
openEHR projects need engineers who understand clinical models as well as APIs. Agnotic Technologies provides FHIR developers and healthcare data engineers who build applications on clinical data repositories: template mapping, composition pipelines, AQL queries, versioning-aware clients and FHIR layers that expose openEHR data to other systems.
The client's clinical modelers own the archetypes and templates. Agnotic's engineers build the software around them and document every mapping between paths and FHIR elements.
Add engineers who know clinical data models
Read about hiring FHIR developers through Agnotic, or continue with more EHR integration articles.
Related reading on Agnotic
Continue with FHIR versus openEHR, choosing an openEHR repository, EHR integrations and EHR data analytics.
