openEHR Template vs. Composition

Hello fellows!
I’m working my way through the concepts of openEHR and struggle to understand the following explanation from the specifications:

An openEHR Template is a specification that defines a tree of of one or more archetypes, each constraining instances of various reference model types, such as Composition, Section, Entry subtypes and so on

My understanding so far, however, was that a Composition is nothing else than a template filled with data and that within a Composition we can have sections and entries. I don’t think that this matches with the quite :confused:

Furthermore, when querying an example template in JSON format, the first entry says

"_type": "COMPOSITION"

Again, how can a template be of the type composition?

Hi @mc1995,

I will try to describe in a bit informal way by providing an example of the serialized data: the template provides the metadata which describe how an openEHR data instance (= composition) is allowed to look like.

Here is an excerpt from a template (in WebTemplate format):

                               {
                                    "id": "diástole",
                                    "name": "Diástole",
                                    "localizedName": "Diástole",
                                    "rmType": "DV_QUANTITY",
                                    "nodeId": "at0005",
                                    "min": 0,
                                    "max": 1,
                                    "localizedNames": {
                                        "es-ar": "Diástole",
                                        "pt-br": "Diastólica"
                                    },
                                    "localizedDescriptions": {
                                        "es-ar": "Presión arterial sistémica mínima - medido durante la diástole o fase de relajación del ciclo cardíaco.",
                                        "pt-br": "Pressão arterial sistêmica mínima - medida na fase diastólica ou de dilatação do ciclo cardíaco."
                                    },
                                    "aqlPath": "/content[openEHR-EHR-OBSERVATION.blood_pressure.v2]/data[at0001]/events[at1042]/data[at0003]/items[at0005]/value",
                                    "inputs": [
                                        {
                                            "suffix": "magnitude",
                                            "type": "DECIMAL",
                                            "validation": {
                                                "precision": {
                                                    "min": 0,
                                                    "minOp": ">=",
                                                    "max": 0,
                                                    "maxOp": "<="
                                                },
                                                "range": {
                                                    "min": 0.0,
                                                    "minOp": ">=",
                                                    "max": 1000.0,
                                                    "maxOp": "<"
                                                }
                                            }
                                        },
                                        {
                                            "suffix": "unit",
                                            "type": "CODED_TEXT",
                                            "list": [
                                                {
                                                    "value": "mm[Hg]",
                                                    "label": "mm[Hg]",
                                                    "localizedLabels": {
                                                        "es-ar": "mmHg",
                                                        "pt-br": "mmHg"
                                                    },
                                                    "validation": {
                                                        "precision": {
                                                            "min": 0,
                                                            "minOp": ">=",
                                                            "max": 0,
                                                            "maxOp": "<="
                                                        },
                                                        "range": {
                                                            "min": 0.0,
                                                            "minOp": ">=",
                                                            "max": 1000.0,
                                                            "maxOp": "<"
                                                        }
                                                    }
                                                }
                                            ]
                                        }
                                    ]
                                }

It describes that there can be an an instance of the openEHR Reference Model class (DV_QUANTITY) at a specific path (/content[openEHR-EHR-OBSERVATION.blood_pressure.v2]/data[at0001]/events[at1042]/data[at0003]/items[at0005]) within a composition and which is allowed to be in a specific range (0 … 1000) and can occur 0 or 1 times within the entry and has unit mm[HG]

The excerpt of the composition/data instance (in this example represented in the so called flat format) that can be derived from the Template might look like the following:

"virtal_signs/presión_arterial/any_event_en:0/diástole|magnitude": 90.0, 
"virtal_signs/presión_arterial/any_event_en:0/diástole|unit": "mm[Hg]",

the same dats represented as canonical JSON format:

{
                                               "name": {
                                                    "value": "Diástole",
                                                    "_type": "DV_TEXT"
                                                },
                                                "value": {
                                                    "_type": "DV_QUANTITY",
                                                    "units": "mm[Hg]",
                                                    "magnitude": 90.0
                                                },
                                                "_type": "ELEMENT",
                                                "archetype_node_id": "at0005"
                                            },

The validation inside the openEHR server will check if the composition does not violate the constraints provided within the template.

Put a bit differently: while a Template necessarily resembles an openEHR composition by using classes that allow describing constraints on the classes from the openEHR Reference Model (which compositions consist of), they have different attributes and functions.

Hope this helps. Someone might elaborate a bit on the differences on the class definitions, but I personally like to take a look at examples first.

1 Like

Well in some way they are, but your missing some vital points here.
Template are not masks that you populate.
They are more structure definition and constrains of the composition.
So in the end compositions are an instance that comply to the rules and structure defined by the template (which refers RM classes and constrains them and son on and so on ).
As an example, templates constrain fields to contain specific codings etc…
You could see it a little bit like XML schemas (even thou they do much more), but for simplicity :wink:

If you know FHIR they are the Profiles of openEHR (surely they differ in the approach obviously etc. ).

Hi @mc1995 from where did you got that definition? (BTW has a typo)

A COMPOSITION is a structure to store data, but is a very generic structure.

A Template is a set of constraints over a COMPOSITION structure, it adds definition to the generic structure to make it more specific, in other words, the template is your final data structure based on a base generic COMPOSITION.

COMPOSITION = generic structure
Template = constraints over generic structure
COMPOSITION + Template = final data structure for a specific use

A COMPOSITION is NOT a template filled with data.

COMPOSITION and Template are two different models in the openEHR specifications, as said, one is a generic structure, the other one is a set of constraints over a generic structure.

That is the simplest definition I can come up with, then we can talk about model vs. instances and what defines what and what constraints what, but it’s a little complicated, let’s try to clarify your question first.

Please let me know if that answer helps you.

got it from here: 10 Archetypes and Templates (openehr.org) - fourth block of 10.1 Overview :wink:

Ok I understand your point that a composition is a structure and the constraints of that structure are encoded within the template. However, I am then confused where does the composition get its structure from? So far I have proceeded like this. I have downloaded templates or archetypes in CKM and deleted fields in the archetype designer that I do not need. Then I saved this as OPT and this is then the template which I have posted on our server.

Then I created an example composition via rest/ecis/v1/template//example and filled it with data. I.e. the structure of the composition comes then also from the template? Is this kind of approach not the intended one?

Your worflow is correct! Maybe there is confusion that the flat format uses the names from the template to represent paths instead of the more abstract Reference Model classes?

If this is the case, I would recommend to create examples using the different formats (canonical XML, canonical JSON, Flat, Structured) to study differences. The flat and structured format are more concrete representations to facilitate frontend/web development whereas the canonical formats are straight forwars serialisations of the generic Reference Model.

I hope this is not too confusing :grimacing:

Just a quick FYI: the link looks super old, please refer to the current docs instead Architecture Overview :slight_smile:

1 Like

The COMPOSITION structure is defined here EHR Information Model

It’s an object model described in UML, with a corresponding tabular description of each field and associated classes.

True, that spec is pre 2006, since then we have updated the specs quite a lot. Latest specs are here https://specifications.openehr.org/