Does your blood run cold when you hear about openEHR? Do archetypes give you goosebumps?

Overcome your fears with this article and master OpenEHR using the capabilities of InterSystems IRIS for Health!

What is openEHR?

openEHR is an open, vendor-neutral specification designed to represent, store, and exchange clinical information in a semantically rich and long-term sustainable way. Instead of defining fixed message structures (as many interoperability standards do) OpenEHR separates clinical knowledge from technical implementation through a multi-layered modelling approach.

At its core, openEHR relies on three fundamental concepts:

• Reference Model (RM)
  A model that defines the core structures used in health records, such as Compositions, Entries, Observations, Evaluations, and Actions. The RM is deliberately generic and technology-agnostic.
• Archetypes
  Machine-readable models (expressed in ADL) that define the detailed clinical semantics for a specific concept, such as a blood pressure measurement or a discharge summary. Archetypes constrain the RM and provide a reusable clinical vocabulary.
• Templates (OPT files)
  Specializations built on top of archetypes. Templates tailor archetypes to a specific use case, system, or form (for example, a vital signs template, or a regional discharge note). Templates eliminate optionality and produce operational definitions that systems can safely implement.

Let's see an example of a RAW file base on a Composition (in JSON):

{
  "_type": "COMPOSITION",
  "archetype_node_id": "openEHR-EHR-COMPOSITION.diagnostic_summary.v1",
  "archetype_details": {
    "_type": "ARCHETYPED",
    "archetype_id": {
      "_type": "ARCHETYPE_ID",
      "value": "openEHR-EHR-COMPOSITION.diagnostic_summary.v1"
    },
    "template_id": {
      "_type": "TEMPLATE_ID",
      "value": "ES - AP - Diagnoses and treatment"
    },
    "rm_version": "1.0.4"
  },
  "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": "diag-1003::ehr.local::1"
  },
  "name": {
    "_type": "DV_TEXT",
    "value": "Summary of diagnoses and treatment – Moderate COPD"
  },
  "language": {
    "_type": "CODE_PHRASE",
    "terminology_id": {
      "_type": "TERMINOLOGY_ID",
      "value": "ISO_639-1"
    },
    "code_string": "es"
  },
  "territory": {
    "_type": "CODE_PHRASE",
    "terminology_id": {
      "_type": "TERMINOLOGY_ID",
      "value": "ISO_3166-1"
    },
    "code_string": "ES"
  },
  "category": {
    "_type": "DV_CODED_TEXT",
    "value": "event",
    "defining_code": {
      "_type": "CODE_PHRASE",
      "terminology_id": {
        "_type": "TERMINOLOGY_ID",
        "value": "openehr"
      },
      "code_string": "433"
    }
  },
  "composer": {
    "_type": "PARTY_IDENTIFIED",
    "name": "Dr. García"
  },
  "context": {
    "_type": "EVENT_CONTEXT",
    "start_time": {
      "_type": "DV_DATE_TIME",
      "value": "2025-11-22T08:45:00Z"
    },
    "setting": {
      "_type": "DV_CODED_TEXT",
      "value": "primary medical care",
      "defining_code": {
        "_type": "CODE_PHRASE",
        "terminology_id": {
          "_type": "TERMINOLOGY_ID",
          "value": "openehr"
        },
        "code_string": "228"
      }
    }
  },
  "content": [
    {
      "_type": "SECTION",
      "archetype_node_id": "openEHR-EHR-SECTION.diagnoses_and_treatments.v1",
      "name": {
        "_type": "DV_TEXT",
        "value": "Respiratory diagnosis and treatment"
      },
      "items": [
        {
          "_type": "EVALUATION",
          "archetype_node_id": "openEHR-EHR-EVALUATION.problem_diagnosis.v1",
          "name": {
            "_type": "DV_TEXT",
            "value": "Moderate COPD"
          },
          "archetype_details": {
            "_type": "ARCHETYPED",
            "archetype_id": {
              "_type": "ARCHETYPE_ID",
              "value": "openEHR-EHR-EVALUATION.problem_diagnosis.v1"
            },
            "template_id": {
              "_type": "TEMPLATE_ID",
              "value": "ES - AP - Diagnoses and treatment"
            },
            "rm_version": "1.0.4"
          },
          "language": {
            "_type": "CODE_PHRASE",
            "terminology_id": {
              "_type": "TERMINOLOGY_ID",
              "value": "ISO_639-1"
            },
            "code_string": "es"
          },
          "encoding": {
            "_type": "CODE_PHRASE",
            "terminology_id": {
              "_type": "TERMINOLOGY_ID",
              "value": "IANA_character-sets"
            },
            "code_string": "UTF-8"
          },
          "subject": {
            "_type": "PARTY_SELF"
          },
          "data": {
            "_type": "ITEM_TREE",
            "archetype_node_id": "at0001",
            "name": {
              "_type": "DV_TEXT",
              "value": "Diagnostic data"
            },
            "items": [
              {
                "_type": "ELEMENT",
                "archetype_node_id": "at0002",
                "name": {
                  "_type": "DV_TEXT",
                  "value": "Diagnosis description"
                },
                "value": {
                  "_type": "DV_TEXT",
                  "value": "Moderate COPD with exertional dyspnoea."
                }
              },
              {
                "_type": "ELEMENT",
                "archetype_node_id": "at0003",
                "name": {
                  "_type": "DV_TEXT",
                  "value": "Diagnosis code"
                },
                "value": {
                  "_type": "DV_CODED_TEXT",
                  "value": "J44.1",
                  "defining_code": {
                    "_type": "CODE_PHRASE",
                    "terminology_id": {
                      "_type": "TERMINOLOGY_ID",
                      "value": "ICD-10"
                    },
                    "code_string": "J44.1"
                  }
                }
              },
              {
                "_type": "ELEMENT",
                "archetype_node_id": "at0004",
                "name": {
                  "_type": "DV_TEXT",
                  "value": "Onset date"
                },
                "value": {
                  "_type": "DV_DATE_TIME",
                  "value": "2020-09-15T00:00:00Z"
                }
              }
            ]
          }
        },
        {
          "_type": "EVALUATION",
          "archetype_node_id": "openEHR-EHR-EVALUATION.medication_summary.v1",
          "name": {
            "_type": "DV_TEXT",
            "value": "Inhaled treatment for COPD"
          },
          "archetype_details": {
            "_type": "ARCHETYPED",
            "archetype_id": {
              "_type": "ARCHETYPE_ID",
              "value": "openEHR-EHR-EVALUATION.medication_summary.v1"
            },
            "template_id": {
              "_type": "TEMPLATE_ID",
              "value": "ES - AP - Diagnoses and treatment"
            },
            "rm_version": "1.0.4"
          },
          "language": {
            "_type": "CODE_PHRASE",
            "terminology_id": {
              "_type": "TERMINOLOGY_ID",
              "value": "ISO_639-1"
            },
            "code_string": "es"
          },
          "encoding": {
            "_type": "CODE_PHRASE",
            "terminology_id": {
              "_type": "TERMINOLOGY_ID",
              "value": "IANA_character-sets"
            },
            "code_string": "UTF-8"
          },
          "subject": {
            "_type": "PARTY_SELF"
          },
          "data": {
            "_type": "ITEM_TREE",
            "archetype_node_id": "at0001",
            "name": {
              "_type": "DV_TEXT",
              "value": "Associated medication tree"
            },
            "items": [
              {
                "_type": "ELEMENT",
                "archetype_node_id": "at0002",
                "name": {
                  "_type": "DV_TEXT",
                  "value": "Medication associated with the diagnosis"
                },
                "value": {
                  "_type": "DV_TEXT",
                  "value": "Inhaled salbutamol 100 mcg as needed; inhaled tiotropium 18 mcg every 24 hours."
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

This layered modelling approach enables openEHR systems to remain stable over years—even decades—while allowing clinical models to evolve independently from the underlying software platform.

A key piece of the openEHR ecosystem is AQL (Archetype Query Language), the standard query language used to retrieve clinical data stored in openEHR repositories.

Archetype Query Language (AQL)

AQL is inspired by SQL but adapted to the openEHR information model. Instead of querying relational tables, AQL allows developers to query structured clinical content inside openEHR Compositions, taking advantage of archetype paths.

Key characteristics of AQL

• Path-based querying: AQL uses archetype paths (similar to XPath) to navigate the internal structure of a Composition, such as:

  /content[openEHR-EHR-OBSERVATION.blood_pressure.v1]/data/events/time

• Clinical semantic awareness: Queries refer to clinical concepts (archetypes, entry types, data points) rather than database column names.
• Flexible WHERE clauses: AQL supports filtering on values within Compositions, e.g. systolic blood pressure > 140 or diagnoses matching a specific code.
• Multi-composition queries: It can retrieve data across multiple Compositions, for example all Observations for a given patient over time.
• Vendor-neutral: Any openEHR implementation that supports AQL should, in principle, accept the same queries.

Let's see an example of AQL:

SELECT
    c/uid/value AS composition_id,
    o/data[at0001]/events[at0006]/data[at0003]/value/magnitude AS systolic,
    o/data[at0001]/events[at0006]/data[at0004]/value/magnitude AS diastolic
FROM
    EHR e
    CONTAINS COMPOSITION c
    CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1]
WHERE
    e/ehr_id/value = '12345'
AND
    o/data[at0001]/events[at0006]/time/value > '2023-01-01T00:00:00Z'

OpenEHR - FHIR comparation

Technically speaking, OpenEHR and FHIR are very very similar. Information based in documental format, API REST, etc. Let's see the main concepts of FHIR and OpenEHR and its correlation:

What do we need to implement openEHR in IRIS for Health?

RAW Composition Storage

• Store incoming Compositions in RAW JSON or XML exactly as received.
• No transformation should modify semantic content.
• For our example we are going to work with JSON format, but there are multiple options.

REST API Services

Our implementation has to expose the following API REST:

EHR Services

To create and locate a patient's "history."

• POST /ehr: Creates a new EHR.
• GET /ehr/{ehr_id}: Retrieve EHR metadata.
• GET /ehr?subject_id=?: Locate an EHR based on external identifiers.

Composition Services

To store patient's clinical information.

• POST /ehr/{id}/composition: Commit a new composition in RAW format. Validate against OPT when possible
• GET /composition/{version_uid}: Retrieve a specific version.
• GET /ehr/{id}/compositions: List compositions for an EHR.
• DELETE /composition/{uid}: Mark composition as deleted (logical delete).

AQL Query Endpoint

• POST /query/aql: Accept an AQL query, translate to IRIS SQL or JSON-path-based lookup and return results in openEHR canonical JSON.

RAW Composition Validation

We have to force validation of RAW compositions based on OPT2 files, we can't save in our repository any JSON that we will receive.

Implementing openEHR in IRIS for Health

Well, to implement all the functionalities available in a openEHR server will take some time, so I'm going to focus in the core functionalities:

Using web application to deploy REST API Service

To publish a REST API is straight forward, we only need two components, a class extending %CSP.REST and a new record in the list of web applications. Let's see the header of our extended %CSP.REST class:

As you can see we have defined all the minimum required routes for our repository. We have all the managament of compositions, OPT2 files for RAW validations and finally, execution of AQL queries.

For our example we are not going to define any security configuration, but JWT Authentication is recommended.

Ok, we have our class and our %CSP.REST class, what else?

RAW validations

openEHR is anything but new, so you can guess that there are multiple libraries to support some functionalities like raws validations. For this example we've used and customized Arche library, an open source library developed in Java to validate rawcompositions against OPT2 files. The validator is a jar file configured from the External Language Server (by default on docker image deployment) and invoked before to save the raw using the JavaGateway functionality:

set javaGate = $system.external.getJavaGateway()
set result = javaGate.invoke("org.validator.openehr.Cli", "validate", filePath, optPath)

If the raw is validated the JSON document will be saved into the database.

JSON raw storage

We could use DocDB, but we want to leverage the performance of SQL databases. One of the biggest problems related with openEHR is the poor performance querying documents, so we are going to pre-process the compositions to get common information to all composition types to boost queries.

Our Composition class define the following properties:

Class OPENEHR.Object.Composition Extends (%Persistent, %XML.Adaptor) [ DdlAllowed ]
{
/// Description
Property ehrId As %Integer;
Property compositionUid As %String(MAXLEN = 50);
Property compositionType As %String;
Property startTime As %DateTime;
Property endTime As %Date;
Property archetypes As list Of %String(MAXLEN = 50000);
Property doc As %String(MAXLEN = 50000);
Property deleted As %Boolean [ InitialExpression = 0 ];
Index compositionUidIndex On compositionUid;
Index ehrIdIndex On ehrId;
Index ExampleIndex On archetypes(ELEMENTS);
}

• ehrId: with the electronic health record of the patient.
• compositionUid: composition identifier.
• compositionType: type of composition saved.
• startTime: time when the composition was created.
• archetypes: list of archetypes contained on the composition.
• doc: JSON format document.
• deleted: boolean value for soft deletes.

The indexes will be used to improve the queries.

AQL support

As we said before AQL is a path-based query language. How could we emulate the same behaviour in IRIS for Health? Welcome to JSON_TABLE!

What is JSON_TABLE?

The JSON_TABLE function returns a table that can be used in a SQL query by mapping JSON values into columns. Mappings from a JSON value to a column are written as SQL/JSON path language expressions.

As a table-valued function, JSON_TABLE returns a table that can be used in the FROM clause of a SELECT statement to access data stored in a JSON value; this table does not persist across queries. Multiple calls to JSON_TABLE can be made within a single FROM clause and can appear alongside other table-valued functions.

We have implemented a ClassMethod in Python to translate AQL into SQL, but there is a problem, AQL is based on relative paths of the archetypes, not in absolute paths, so we need identify the absolute path for each archetype and join it with the relative path of the AQL.

How can we know the absolute path? Very easy! We can find it when the user save the OPT2 file for the composition into IRIS! As soon as we get the absolute path we save it into a CSV file specific for the composition (it would be saved into a global or any other way) so, we only have to get the absolute path from the specific composition file or, if the AQL doesn't define the composition, search into the available CSV files the absolute path for the archetypes of the AQL.

Let's see how it works. Here is an example of AQL to get all the diagnosis with a specific ICD-10 code:

SELECT
  c/uid/value AS comp_uid,
  c/context/start_time/value AS comp_start_time,
  dx/data[at0001]/items[at0002]/value/value AS diagnosis_text,
  dx/data[at0001]/items[at0003]/value/defining_code/code_string AS diagnosis_code
FROM EHR e
CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.diagnostic_summary.v1]
CONTAINS SECTION s[openEHR-EHR-SECTION.diagnoses_and_treatments.v1]
CONTAINS EVALUATION dx[openEHR-EHR-EVALUATION.problem_diagnosis.v1]
WHERE dx/data[at0001]/items[at0003]/value/defining_code/code_string
      MATCHES {'E11', 'I48.0'}
ORDER BY c/context/start_time/value DESC

The funcion Transform from OPENEHR.Utils.AuxiliaryFunctions class translates it into:

SELECT comp_uid, comp_start_time, diagnosis_text, diagnosis_code 
FROM ( 
    SELECT c.compositionUid AS comp_uid, 
        jt_root.comp_start_time AS comp_start_time, 
        jt_n1.diagnosis_text AS diagnosis_text, 
        jt_n1.diagnosis_code AS diagnosis_code 
    FROM OPENEHR_Object.Composition AS c, 
        JSON_TABLE( c.doc, '$' COLUMNS ( comp_start_time VARCHAR(4000) PATH
            '$.context.start_time.value' ) ) AS jt_root, 
        JSON_TABLE( c.doc, '$.content[*]?(@._type=="SECTION" && @.archetype_node_id==
            "openEHR-EHR-SECTION.diagnoses_and_treatments.v1").items[*]?
            (@._type=="EVALUATION" && @.archetype_node_id=="openEHR-EHR-EVALUATION.problem_diagnosis.v1")'
            COLUMNS ( 
                diagnosis_text VARCHAR(4000) PATH '$.data[*]?(@.archetype_node_id=="at0001").items[*]?
                    (@.archetype_node_id=="at0002").value.value', 
                diagnosis_code VARCHAR(255) PATH '$.data[*]?(@.archetype_node_id=="at0001").items[*]?
                    (@.archetype_node_id=="at0003").value.defining_code.code_string' ) ) AS jt_n1 
    WHERE ('openEHR-EHR-COMPOSITION.diagnostic_summary.v1' %INLIST (c.archetypes) 
        AND 'openEHR-EHR-EVALUATION.problem_diagnosis.v1' %INLIST (c.archetypes)) 
        AND (jt_n1.diagnosis_code LIKE '%E11%' OR jt_n1.diagnosis_code LIKE '%I48.0%') ) U 
ORDER BY comp_start_time DESC

Let's try our API REST with an AQL:

Success!

And now with a numeric comparation:

SELECT
  c/uid/value AS comp_uid,
  c/context/start_time/value AS comp_start_time,
  a/items[at0024]/value/magnitude AS creatinine_value,
  a/items[at0024]/value/units AS creatinine_units
FROM EHR e
CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.lab_results_and_medications.v1]
CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.laboratory_test_result.v1]
CONTAINS CLUSTER a[openEHR-EHR-CLUSTER.laboratory_test_analyte.v1]
WHERE a/items[at0001]/value/value = 'Creatinina (mg/dL)'
  AND a/items[at0024]/value/magnitude BETWEEN 1.2 AND 1.8
ORDER BY c/context/start_time/value DESC

Transformed into:

SELECT comp_uid, comp_start_time, ldl_value, ldl_units 
FROM ( 
    SELECT c.compositionUid AS comp_uid, jt_root.comp_start_time AS comp_start_time,
        jt_n1.ldl_value AS ldl_value, jt_n1.ldl_units AS ldl_units 
    FROM OPENEHR_Object.Composition AS c, 
        JSON_TABLE( c.doc, '$' COLUMNS ( comp_start_time VARCHAR(4000) 
            PATH '$.context.start_time.value' ) ) AS jt_root, 
        JSON_TABLE( c.doc, '$.content[*]?(@._type=="OBSERVATION" && 
            @.archetype_node_id=="openEHR-EHR-OBSERVATION.laboratory_test_result.v1")
                .data.events[*]?(@._type=="POINT_EVENT").data.items[*]?(@._type=="CLUSTER" &&
                @.archetype_node_id=="openEHR-EHR-CLUSTER.laboratory_test_analyte.v1")'
                COLUMNS ( 
                    ldl_value NUMERIC PATH '$.items[*]?
                        (@.archetype_node_id=="at0024").value.magnitude', 
                    ldl_units VARCHAR(64) PATH '$.items[*]?
                        (@.archetype_node_id=="at0024").value.units', 
                    _w1 VARCHAR(4000) PATH '$.items[*]?
                        (@.archetype_node_id=="at0001").value.value' ) ) AS jt_n1 
    WHERE ('openEHR-EHR-COMPOSITION.lab_results_and_medications.v1' %INLIST (c.archetypes) 
        AND 'openEHR-EHR-OBSERVATION.laboratory_test_result.v1' %INLIST (c.archetypes) 
        AND 'openEHR-EHR-CLUSTER.laboratory_test_analyte.v1' %INLIST (c.archetypes)) 
        AND jt_n1._w1 = 'LDL (mg/dL)' AND jt_n1.ldl_value <= 130 ) 
    U ORDER BY comp_start_time DESC

Another resounding success!

Conclusions

Well, as you can see in this example, InterSystems IRIS for Health provide to you of all the tools required to implement and deploy an openEHR repository. If you have any question don't hesitate to write a comment!

Disclaimer

The associated code is just a proof of concept, It does not aim to implement a repository with all the functionalities but to demonstrate that it is perfectly possible with InterSystems IRIS for Health. Enjoy!