openEHR logo

Operational Template 2 (OPT2)

Issuer: openEHR Specification Program

Release: AM Release-2.3.0

Status: DEVELOPMENT

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: EHR, ADL, AOM, health records, archetypes, constraint language, ISO 13606, openehr
openEHR components
© 2015 - 2024 The openEHR Foundation

The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.

Licence

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser, Implementer Completed

AM Release 2.3.0

AM Release 2.2.0

AM Release 2.1.0

AM Release 2.0.6

0.5.1

Added 'Purpose' section.

T Beale

08 Jun 2016

0.5.0

Initial Writing

T Beale

28 Oct 2015

Acknowledgements

Primary Author

  • Thomas Beale, Ars Semantica, UK; openEHR International Board.

Trademarks

  • 'openEHR' is a registered trademark of The openEHR Foundation

  • 'SNOMED CT' is a registered trademark of IHTSDO

1. Preface

1.1. Purpose

This document provides the formal specification of the Operational Template (OPT) for ADL2 artefacts. The OPT is a first generation 'compiled' artefact based on source archetypes and templates, that serves as the starting point for further downstream format generation (e.g. schemas, APIs) as well as the computational format for operational EHR systems using archetypes.

This specification is primarily intended for software developers.

1.2. Related Documents

Prerequisite documents for reading this document include:

Related documents include:

1.3. Nomenclature

In this document, the term 'attribute' denotes any stored property of a type defined in an object model, including primitive attributes and any kind of relationship such as an association or aggregation. XML 'attributes' are always referred to explicitly as 'XML attributes'.

We also use the word 'archetype' in a broad sense to designate what are commonly understood to be 'archetypes' (specifications of clinical data groups / data constraints) and 'templates' (data sets based on archetypes, since at a technical level, an ADL/AOM 2 template is in fact just an archetype. Accordingly, statements about 'archetypes' in this specification can be always understood to also apply to templates, unless otherwise indicated.

1.4. Status

This specification is in the DEVELOPMENT state. The development version of this document can be found at https://specifications.openehr.org/releases/AM/latest/OPT2.html.

Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:

TBD: (example To Be Determined paragraph)

1.5. Feedback

Feedback may be provided on the openEHR ADL forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the AM component Change Request tracker.

1.6. Conformance

Conformance of a data or software artifact to an openEHR specification is determined by a formal test of that artifact against the relevant openEHR Implementation Technology Specification(s) (ITSs), such as an IDL interface or an XML-schema. Since ITSs are formal derivations from underlying models, ITS conformance indicates model conformance.

1.7. Tools

Various tools exist for creating and processing archetypes. The ADL Workbench is a reference compiler, visualiser and editor. The openEHR tools can be downloaded from the website .

Source projects can be found at the openEHR Github project.

1.8. Relationship to OPT '1.4'

This specification describes an Operational Template based on ADL2/AOM2, rather than the original OPT, which is an XML-schema format based on ADL 1.4 archetypes.

2. Overview

The Operational Template (OPT) is a family of technical artefacts that is generated from source templates and archetypes expressed in ADL2, as described in the Archetype Technology Overview document.

2.1. Purpose of the OPT

The Operational Template as an artefact is a compiled form of source archteypes and templates and is useful for a number of reasons, as follows.

  1. A production EHR or other archetype-driven system can safely run only using guaranteed validated templates and archetypes. No direct use of source artefacts should ever be made for reasons of safety. (Clearly, experimental / research systems may operate somewhat differently).

  2. The specialisation relationship between archetypes has to be evaluated in order to produce usable artefacts, because the usable form of such artefacts is the 'inheritance-flattened' form. This is exactly analagous to the situation with class inheritance in object-oriented programming: the executable form of any class is the inheritance-flattened form. Accordingly, a deployable form of archetypes and templates must be compiled in some fashion from the sources.

  3. In general, there is always a possible need for further adjustments to the source artefacts to obtain a deployable artefact. For example, the original archetypes may be in numerous languages, and with bindings to say three terminologies, while the final artefact usually only requires one or two languages (e.g. the national language and English), and only a subset of the terminology bindings is typically required. The OPT provides a target artefact in which these choices can be made.

  4. The concrete format of the final artefact (the OPT) is intended to be the convenient for implementation rather than human use or modelling tools; normally this implies the use of machine formats such as XML, JSON, or even binary formats. In the ADL2 tools, OPTs can be generated in ADL, ODIN, JSON, XML and YAML, and other formats may be added in the future.

  5. The OPT is intended for use not only in production systems, but also as the basis for other types of transformations that generate new kinds of artefacts. E.g. Template Data Schema (TDS, a kind of XSD), Template Data Object (TDO, a partial class), APIs and so on. The OPT provides a single standard input artefact for these kinds of transformations.

2.2. Types of OPT

There are two types of OPT: 'raw' and 'profiled'. The raw form can informally be understood as being the single large archetype structure corresponding to many source archetypes and templates, flattened and expanded into a single artefact. A raw OPT contains all possible content in terms of languages and terminology bindings. The following diagram shows the progressive generation of these artefacts from original archetypes and templates.

opt tool chain
Figure 1. OPT Tool Chain

A profiled OPT is one that has had some languages and some or all terminology bindings removed, potentially external terminology substitutions made, and potentially removal of the annotations section. This form of OPT is therefore the same formally as a raw OPT, just with less content. Consequently, only a single specification is needed to describe both forms.

In order to prevent confusion, raw and profiled OPTs are saved using distinct filenames.

Because an OPT operates as a single standalone archetype, it does not require all of the syntax or semantic features of source archetypes or templates. It can thus be understood as being like a top-level (i.e. non-specialised) archetype, with the following differences:

  • all archetype references have been resolved to specific archetype identifiers, including full version;

  • no specialisation statement - an OPT is considered a 'top-level' standalone artefact;

  • no sibling order (i.e. before or after) markers remain among object nodes under container attributes;

  • no use_node nodes, i.e. all internal references have been expanded out as copies of their targets;

  • all slot-fillers and direct external references (use_archetype nodes) have been resolved and substituted;

  • all closed slots are removed;

  • all attribute (C_ATTRIBUTE) nodes that have existence matches {0} (i.e. are logically removed) are removed;

  • all template overlays have been applied (flattening);

  • the flattened form of all terminology sections of all referenced archetypes are included in the component_terminologies section.

Note that the identifiers of all of the deepest specialisations of archetypes and templates used in the OPT are visible at the root nodes of the corresponding structures, starting with the top node. This enables the totality of implicated archetypes and templates to be retrieved by a combination of inspection of the OPT, and inspection of the directly referenced artefacts, to obtain the specialisation parents, where applicable.

An OPT can be serialised in more than one form, including ADL, XML and JSON. To facilitate tooling and reduce confusion, distinct filename extensions are used, of the form .opt (ADL), .optx (XML), .optj and so on.

3. The Raw Operational Template

A 'raw' OPT is the first stage of OPT processing from a master source template, and all the other templates and archetypes that it references. All references to archetype nodes and other archetypes are resolved, and the structure is fully flattened, with all deleted nodes removed.

3.1. Artefact Structure

Since an OPT is considered a 'top-level' standalone artefact, there is no specialisation statement. There are no other differences to the 'outer' structure of the artefact, so its structure is the same as any top-level archetype, i.e. in ADL terms, it obeys the following Antlr4 rule:

adl_operational_template: 'operational_template' '(' qualifiers? ')'
        ARCHETYPE_HRID
    'language'
        odin_text
    'description'
        odin_text
    'definition'
        cadl_text
    ('rules'
        rules_text)?
    'terminology'
        odin_text
    ('annotations'
        odin_text)?
    'component_terminologies'
        odin_text
    ;

3.2. Archetype References

All references to other archetypes (typically not including full version information) found in the source archetypes and templates are resolved to full archetype identifiers, and replaced by these identifiers in the OPT output (guaranteed to include full 3-part versions).

3.3. Flattening

The flattening process for an OPT is somewhat more extensive than the standard flattening process that produces a flattened archetype, described in the AOM specification.

OPT Flattening involves the following additional steps:

  • since sibling sets of object nodes under a container attribute node are expressed in full (i.e. taking into account additions and removals from specialised child archetypes), there are no sibling order markers (i.e. 'before' and 'after' markers) in a raw OPT;

  • use_node internal references are replaced by an inline copy of the target structure of the reference;

  • for slots:

    • all closed slots are removed;

    • all slot-filler archetype references are replaced by an inline copy of the archetype to which the reference resolves;

  • all deleted nodes are removed from the output, i.e. attribute (C_ATTRIBUTE) nodes that have existence matches {0} and object (C_OBJECT) nodes with occurrences matches {0};

3.4. Terminology

During the OPT flattening process, the flat form of the terminology section of each flattened constituent archetype or template (other than the root template) is gathered under the component_terminologies section.

4. The Profiled Operational Template

A 'profiled' OPT is a technical artefact intended for direct use in some context. It is a processed form of the raw OPT in which various removals of unwanted elements are made, and terminology references are converted to the desired form for final use. Multiple profiled OPTs can be derived from a raw OPT.

It is assumed that tools provide ways of specifying the various alterations, and they are not described here. the following describes only the resulting output.

4.1. Annotations Removal

Annotations can be removed from a raw OPT, which results in the complete removal of the annotations section in the output.

4.2. Language Filtering

Since archetypes and templates in general may contain numerous language translations, and the target deployment environment is normally targetted to only one or two languages, one of the filtering possibilities is to remove any of the languages (including the original authoring language) up to the limit where only one remains.

The resulting OPT will be of the same form as before, but with reduced language translations. In the language section of the archetype, the original_language property will either contain the original authoring language of the root source template (which could easily be different from that of the majority of referenced archetypes).

4.3. Terminology Binding Filtering

Terminology bindings can also be globally filtered out in the profiled OPT, up to removal of all bindings. The resulting OPT will contain only those bindings not specified for removal in the terminology section.

4.4. Terminology Substitution

A more complex aspect of terminology-related processing has to do with what final codes will be used in archetype data. In the source artefacts, two types of value coding occur. The first case is fields constrained with archetype local value sets, i.e. where the ac-code maps to a group of at-codes, or a single at-code is specified. The second case is where ac-codes are bound only to external value sets (often large ones, such as 'type of infection'), and the value recorded in the data for that field must be an external code of some kind.

The first case poses a possible choice - either archetype-local at-codes or external codes could be used. The choice of what terminology should be used for each ac-code that is bound to both an internal and an external terminology could be made in several places, depending on the level of fine-grained control needed.

  • If we only need to choose which terminologies are allowed at whole-of-library level, the choice is effect by choosing terminology bindings to be removed, as described above.

  • If we need to decide on a per-OPT basis, i.e. the allowed/required terminologies may differ from one OPT to the next, it can still be an input to the OPT profiling step, but now it will be an argument specific to each OPT.

  • If node-level control is needed, the choices would need to be made in the raw OPT. Note that while it is normal that some nodes be coded by one terminology, e.g. an HL7 vocabulary, and others by e.g. SNOMED CT, node-by-node selection is not needed to achieve this, because the bindings for those nodes will already state the allowed possibilities. Node-by-node choosing is only needed if there is a need to further reduce possibilities to a more limited set, e.g. if within a single template, one node has a binding to both ICD10 and SNOMED CT but in a specific use, should only be coded in ICD10, but another node exists for which only SNOMED CT should be allowed, from the same two original possibilities.

TBD: Currently there is no way to do this in ADL2. It would be easy to implement, using a set of paths of coded nodes each with the list of terminologies allowed at that point.

The result of the choices, however made, is expressed in the profiled OPT by using a modified form of the normal term constraint syntax. This is described in detail in the ADL specification, in the Terminology Constraints and Terminology Integration sections.

5. File Formats

5.1. File-naming

5.2. Concrete Formats

5.2.1. ADL

5.2.2. Object-dump Formats - JSON, YAML

5.2.3. XML

References