openEHR logo

Guideline Definition Language v2 (GDL2)

Issuer: openEHR Specification Program

Release: CDS latest

Status: TRIAL

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: decision support, GDL, GDL2, archetype

openEHR components
© 2018 - 2022 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 Completed

CDS Release 2.0.0

2.0.0

SPECCDS-2: Add GDL and GDL2 specifications to CDS release.

SEC

20 May 2019

Initial Writing.

R Chen,
T Beale

12 Apr 2019

Acknowledgements

Primary Author

  • Rong Chen MD, PhD, Cambio CDS, Sweden

Contributors

This specification has benefited from formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

  • Thomas Beale, Ars Semantica (UK); openEHR Foundation Management Board.

Support

The work to produce this specification was funded by the following organisations:

  • Cambio CDS, Sweden.

Trademarks

  • 'openEHR' is a trademark of the openEHR Foundation

  • 'Java' is a registered trademark of Oracle Corporation

  • 'Microsoft' and '.Net' are trademarks of the Microsoft Corporation

1. Preface

1.1. Purpose

This document contains the design specifications of the Guideline Definition Language version 2 (GDL2). GDL2 is a formal language for expressing decision support logic. It is designed to be agnostic to languages, reference terminologies and standard EHR models. GDL2 is a major evolution from GDL version 1 ('GDL').

Prerequisite documents for reading this document include:

1.3. Status

This specification is in the TRIAL state. The development version of this document can be found at https://specifications.openehr.org/releases/CDS/latest/GDL2.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.4. Feedback

Feedback may be provided on the technical mailing list.

Issues may be raised on the specifications Problem Report tracker.

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

1.5. A Note on Nomenclature

This specification uses the terms 'GDL2' and 'GDL' to refer to version 2 of GDL, i.e. the formalism described in this specification.

1.6. Resources

The GDL-lang site is a useful location for GDL-related research material. The GDL Github repository contains published GDLguidelines. The GDL wiki provides further material.

1.7. Changes since GDL version 1 ('GDL')

GDL2 introduces the following changes with respect to the original release of GDL:

  • Data binding agnostic to EHR data models (e.g. openEHR / ISO 13606 / HL7 FHIR);

  • Template definition for output objects with new use_template statement with template-level variables; this enables, for example CDS-Hooks Cards & Suggestions as result of rule executions;

  • Individual references and ability to reference to specific items in the rules;

  • More math functions support.

Migration of GDL1 to GDL2 guidelines is described on the gdl-lang site.

2. Overview

2.1. Background

Expressing and sharing computerized clinical decision support (CDS) content across languages and technical platforms has been an evasive goal for a long time. Lack of commonly shared clinical information models and flexible support for various terminology resources have been identified as two main challenges for sharing decision logic across sites. The openEHR information architecture, coupled with external terminology provides a well-defined, open platform on which to base a computable guideline facility.

2.2. Scope

The scope of GDL is to express clinical logic as production rules. Discrete GDL rules, each containing 'when-then' statements, can be combined together as building blocks to support single decision making and more complex, chained decision making processes. The GDL rules can be used to drive at-point-of-care decision support applications as well as retrospective populational analytics.

The use cases of GDL2 include, but are not limited to:

  • Prompts, alerts & reminders;

  • Interactive single-screen decision support applications;

  • Detailed order-sets and care process support;

  • Algorithm-based calculators;

  • Generate and update personalized care plans as part of more complex care process support;

  • Retrospective treatment compliance check, and outcome measures.

2.3. An Example

The following is a simple GDL example that allows us to calculate CHA2DS2-VASc Score, a clinical tool for stroke risk stratification in atrial fibrillation.

Note
GDL Guidelines are expressed in either the openEHR ODIN or JSON formats, such that a GDL source is a serialised instance of the GDL2 Object Model, described below in Section 5. The example here uses ODIN.
<
    gdl_version = <"2.0">
    id = <"CHA2DS2-VASc.v1">
    concept = <"gt0001">
    original_language = <[ISO_639-1::en]>
    description = <
        details = <
            ["en"] = <
                copyright = <"Cambio Healthcare Systems">
                keywords = <"Atrial Fibrillation", "Stroke", "CHA2DS2-VASc">
                misuse = <"Do not use in patients with no diagnosis of atrial fibrillation.">
                purpose = <"Calculates stroke risk for patients with atrial fibrillation, possibly better than the CHADS2 score.">
                use = <"Calculates stroke risk for patients with atrial fibrillation, possibly better than the CHADS2 score.">
            >
        >
        lifecycle_state = <"in_review">
        original_author = <
            ["date"] = <"2016-12-16">
            ["email"] = <"rong.chen@cambio.se">
            ["name"] = <"Rong Chen">
            ["organisation"] = <"Cambio Healthcare Systems">
        >
        other_contributors = <"Carlos Valladares">
    >
    definition = <
        pre_conditions = <...>
        data_bindings = <
             ["gt0006"] = <...>
             ["gt0007"] = <...>
             ...
        >
        rules = <
             ["gt0024"] = <...>
             ["gt0025"] = <...>
             ...
        >
    >
    terminology = <
        term_definitions = <
            ["en"] = <
                ["gt123"] = <
                    text = <"some text">
                    description = "some description">
                >
            >
        >
        term_bindings = <
            ["ICD10"] = <
                ["gt123"] = <http://who.int/icd10/id/xxxx>
            >
        >
    >
>

The meta-data in the GDL header is based on the openEHR Resource model. The following GDL source illustrates the current version of the guideline, the supported natural languages, to which it has been translated, authorship information, lifecycle state, keywords and the purpose, use and misuse of the guideline. The other top-level sections are respectively definition and terminology.

The following block illustrates the data_bindings sub-section within the definition section, which binds data elements from a source data-set, defined in terms of an archetype, optionally within a specific template, to variables used by GDL rules. Variables are identified using 'gt-codes', e.g. 'gt0123'.

definition = <
    data_bindings = <
        ["gt0006"] = <
            model_id = <"openEHR-EHR-EVALUATION.problem-diagnosis.v1">
            type = <"INPUT">
            elements = <
                ["gt0107"] = <
                    path = <"/data[at0001]/items[at0002.1]">
                >
            >
        >
    >
>

Within the definition section, it is possible to define a set of logical pre-conditions that have to be met before the rules inside the guideline can be executed. In GDL2, the pre-conditions are formed from the pre_conditions sub-section (guideline-wide), and predicates defined in each of the subordinate data_bindings items, as in the CHA2DS2-VASc score calculation shown below:

definition = <
    pre_conditions = <"$gt0107|index diagnosis| != null">
    data_bindings = <
        [1] = <
            model_id = <"openEHR-EHR-EVALUATION.problem-diagnosis.v1">
            type = <"INPUT">
            elements = <
                ["gt0107"] = <
                    path = <"/data[at0001]/items[at0002.1]">
                >
            >
            predicates = <"/data[at0001]/items[at0002.1] is_a local::gt0105|Atrial fibrillation|">
            template_id = <"diagnosis_chadvas_icd10">
        >
    >
>

In this case, the pre-conditions consist of the statements:

-- there is a diagnosis in the data set
$gt0107|index diagnosis| != null

-- the diagnosis is gt0105, Atrial Fibrillation.
/data[at0001]/items[at0002.1] is_a local::gt0105|Atrial fibrillation|

Accordingly, the guideline will not be executed unless the patient has been diagnosed with atrial fibrillation.

The rules section makes use of locally defined variables to express the clinical logic. Each rule has a name codified by a locally defined gt-code, with which its natural language-dependent name and description are indexed in the term_definitions section. A priority can be assigned to ensure execution order of the rules. Higher priorities are executed earlier. This example illustrates rules that inspect different diagnoses relevant to CHA2DS2-VASc score and set the values of the DV_ORDINALs inside a CHA2DS2-VASc score archetype. The rule gt0026 ("Calculate total score") sums the values and sets the total score in CHA2DS2-VASc score archetype.

definition = <
    rules = <
        ["gt0018"] = <
            when = <"$gt0108 != null">
            then = <"$gt0014 = 1|local::at0031|Present|">
            priority = (11)
        >
        ["gt0019"] = <
            when = <"$gt0109 != null">
            then = <"$gt0010 = 1|local::at0034|Present|">
            priority = (9)
        >
        ["gt0026"] = <
            then = <"$gt0016.magnitude = gt0009.value + $gt0010.value + $gt0011.value + $gt0015.value + $gt0012.value + $gt0013.value + $gt0014.value">
            priority = (1)
        >
    >
>

Finally we have the terminology section of the guideline, where all the terms are bound to user interface labels and description of the terms in supported natural languages.

terminology = <
    term_definitions = <
        ["en"] = <
            ["gt0003"] = <
                text = <"Diagnosis">
            >
            ["gt0014"] = <
                text = <"Hypertension">
            >
            ["gt0102"] = <
                text = <"Diabetes">
            >
            ["gt0105"] = <
                text = <"Atrial fibrillation">
            >
            ["gt0018"] = <
                text = <"Set hypertension">
            >
            ["gt0019"] = <
                text = <"Set diabetes">
            >
            ["gt0026"] = <
                text = <"Calculate total score">
            >
        >
    >
>

In addition, locally defined terms may be bound to concepts or refsets defined by external reference terminologies in term_bindings. In this sample, the diagnosis of atrial fibrillation is bound to a specific code in ICD10.

terminology = <
    term_bindings = <
        ["ICD10"] = <
            ["gt0105"] = <"ICD10::I48">
        >
    >
>

3. Requirements

This section describes detailed formal requirements of the GDL2 language.

3.1. Clinical information models

  • It shall be possible to express clinical decision logic using standards-based clinical models such as openEHR Archetypes or HL7 FHIR Resources both as input and output of the rule execution;

  • The design shall support common data types underpinning standard clinical models.

3.2. Natural language independence

  • It shall be possible to author meta-data of the rules in any natural language;

  • The rule expressions shall be independent of any natural language;

  • The name of individual rules shall be independent of any natural language;

  • It shall be possible to add multiple language translations without changing the logical definitions in the rules.

3.3. Reference terminology support

  • It shall be possible to bind a locally defined term in the guideline to a single concept defined in one or several external reference terminologies;

  • It shall be possible to bind a locally defined term in the guideline to multiple concepts defined by external reference terminologies;

  • It shall be possible to bind a locally defined term in the guideline to externally defined terminology ref-sets.

3.4. Identification and meta-data

  • Each rule shall be uniquely identified for a given name space;

  • Each rule shall have explicit version information as part of the guideline identifier;

  • There shall be sufficient meta-data about the guideline with regards to authorship, purpose of the rules, version information and relevant clinical references.

3.5. Rule Execution

  • It shall be possible to chain the execution of several guidelines in order to support complex decision making process;

  • It shall be possible to reuse the guidelines in different decision support applications in different clinical contexts.

3.6. Complex Output Objects

  • It shall be possible to support complex hierarchical objects as output of the rule execution;

  • It shall be possible to alter the structure of the output objects based on the rule executions;

  • It shall be possible to alter the details of the output objects based on the rule executions;

  • It shall support standard or non-standard based output format.

3.7. Local variables

  • It shall be possible to use locally defined variables to hold intermediate results of the rule execution;

  • It shall be possible to use such local variables without dependent on external clinical models.

4. GDL2 Semantics

4.1. Rule Structure

The following diagram illustrates the structure of a GDL2 guideline. The central rules defining the semantics of the guideline are defined in terms of the formal rule definitions (when/then structures) coupled with 'rule execution filters', consisting of pre-conditions and predicates, that decide which rules are executed. If a rule is executed, its when conditions will be evaluated, and if all satisfied, its then actions performed. The data-bindings and terminology parts of structure define respectively, the mappings of the gt-codes used in the rules to nodes in input or output data sets (archetypes and/or templates); and the definitions of the gt-codes as terms, for human use. Finally, the optional templates provide a way of reporting generated results to downstream consumers. These are described in more detail in the Section 4.4 section below.

gdl2 guideline structure
Figure 1. GDL2 guideline structure

4.2. Execution Model

The following diagram illustrates the execution model of a rule in a GDL2 guideline, showing more clearly the relationship between rule execution 'filters' and rule execution.

gdl2 execution model
Figure 2. GDL2 execution model

4.3. GDL2 Language Elements

4.3.1. Syntax

Because GDL2 guidelines are machine serialisations of the Section 5, the syntax is mostly a direct consequence of the structure. Currently, either openEHR ODIN or JSON syntax may be used. The exception is where expressions appear, which is within Assertion and Assignment statements, which as per the model, occur in /pre_conditions, data_bindings[id]/predicates, rules[id]/when statements, rules[id]/then actions, and Guideline default_actions.

The following subsections describe the expressions occurring in Assertion and Assignment statements. The former is a kind of statement that asserts the truth of a Boolean expression, while the latter is a programming-style assignment of an expression of any type to a variable of that type.

4.3.2. Pre-conditions

Pre-conditions (GUIDELINE.pre_conditions) are part of the execution filter for the rules in a guideline. Pre-conditions apply to the guideline as a whole, i.e. all constituent rules and usually specify conditions on the type of patient / subject to which the guideline applies. Input data sets not satisfying the pre-conditions will cause a Guideline to be considered by the execution engine as not applying, and execution will pass to other guidelines or terminate.

The following shows a pre-condition used in the CHA2DS2VASc_Score_calculation.v1.1.0 guideline. This says that the value of the gt0121 variable (meaning: Atrial fibrillation), which is mapped to the path /data[at0001]/items[at0035] in the archetype openEHR-EHR-EVALUATION.chadsvas_diagnosis_review.v1 is 1, i.e. it is present.

definition = <
	pre_conditions = <"$gt0121 == 1|local::at0051|Present|">

    data_bindings = <
        ["gt0122"] = <
            model_id = <"openEHR-EHR-EVALUATION.chadsvas_diagnosis_review.v1">
            type = <"INPUT">
            elements = <
                ["gt0121"] = <
                    path = <"/data[at0001]/items[at0035]">
                >
            >
        >

terminology = <
    term_definitions = <
        ["en"] = <
            ["gt0121"] = <
                text = <"Atrial fibrillation">
                description = <"*">
            >
            ...

The following pre-condition is from the Coeliac_disease_alert.v2 guideline, expressed in JSON. The gt0015 code is mapped in a similar way to a data point within a diagnosis review. In this case, it asserts that there is no Coeliac disease diagnosis, which is the logical pre-condition for applying a Coeliac risk analysis guideline (clearly the latter is not useful for subjects already diagnosed as Coeliac).

    "pre_conditions": [
      "$gt0015|Coeliac disease diagnosis| == null"
    ],

4.3.3. Rules

Rules consist of the pattern when Assertion(s) then Statement(s). The logic of multiple Assertions in the when part is and, i.e. all are needed for the rule to fire.

The following example is from the Coeliac_disease_alert.v2 guideline, and shows a rule whose when condition is a multi-way or expression of various conditions, and whose then statements consist of:

  • assignment to a variable from an output template that corresponds to a CDS hooks 'card' data item;

  • an internal use_template call that tells the execution engine which reporting template to use.

This kind of rule essentially reports on a Boolean condition that was found to be present in the input data.

  "gt0007": {
    "id": "gt0007",
    "priority": 1,
    "when": [
      "$gt0025|Type 1 diabetes| == true ||
       $gt0029|Irritable bowel syndrome| == true ||
       $gt0028|(Unexplained) B12, iron or folate deficiency (and relevant medicines)| == true ||
       $gt0026|Autoimmune thyroid disease (and relevant medicines)| == true"
    ],
    "then": [
      "$gt0009|card.summary| = 'tTG serological testing is recommended'",
      "use_template ($gt2022)"
    ]
  }

Rules may be used to perform calculations, such as the well-known Body Mass Index (BMI). The extract below is from the BMI_Calculation-FHIR.v1 guideline. The 3rd item in the then list is an assignment stating that the BMI variable gt0003 value should be set to weight (gt0007) / height(gt0005)^2.

    "rules": {
      "gt0012": {
        "id": "gt0012",
        "priority": 1,
        "then": [
          "$gt0003|BMI|.unit = 'kg/m2'",
          "$gt0003|BMI|.precision = 1",
          "$gt0003|BMI|.magnitude = $gt0007.magnitude/($gt0005.magnitude/100)^2"
        ]
      }
    }

Rule-set action lists may be of any size, as shown by the following extract, from the QRISK2-2015_risk_calculation.v2 guideline.

  "gt0025": {
    "id": "gt0025",
    "priority": 2,
    "when": [
      "$gt0026=='female'"
    ],
    "then": [
      "$gt1000|dage|.precision = 15",
      "$gt1001|age_1|.precision = 15",
      "$gt1002|age_2|.precision = 15",
      "$gt1003|bmi|.precision = 15",
      "$gt1004|bmi_2|.precision = 15",
      "$gt1005|bmi_1|.precision = 15",
      "$gt1006|rati|.precision = 15",
      "$gt1007|sbp|.precision = 15",
      "$gt1008|town|.precision = 15",

      "$gt1000|dage|.magnitude = $gt0022|age|.magnitude",
      "$gt1000|dage|.magnitude = $gt1000|dage|.magnitude / 10.0",
      "$gt1001|age_1|.magnitude = $gt1000|dage|.magnitude ^ 0.5",
      "$gt1002|age_2|.magnitude = $gt1000|dage|.magnitude",
      "$gt1003|dbmi|.magnitude = $gt0024.magnitude",
      "$gt1003|dbmi|.magnitude = $gt1003|dbmi|.magnitude / 10.0",
      "$gt1004|bmi_2|.magnitude = $gt1003|dbmi|.magnitude ^ (0-2) * log($gt1003|dbmi|.magnitude)",
      "$gt1005|bmi_1|.magnitude = $gt1003|dbmi|.magnitude ^ (0-2)",

      "$gt1001|age_1|.magnitude = $gt1001|age_1|.magnitude - 2.086397409439087",
      "$gt1002|age_2|.magnitude = $gt1002|age_2|.magnitude - 4.353054523468018",
      "$gt1005|bmi_1|.magnitude = $gt1005|bmi_1|.magnitude - 0.152244374155998",
      "$gt1004|bmi_2|.magnitude = $gt1004|bmi_2|.magnitude - 0.143282383680344",
      "$gt1006|rati|.magnitude = $gt8005|Cholesterol/HDL ratio|.magnitude - 3.506655454635620",
      "$gt1007|sbp|.magnitude = $gt0016|Systolic BP|.magnitude - 125.040039062500000",
      "$gt1008|town|.magnitude = (0-0.416743695735931)",

      "$gt0030|QRISK2 score|.precision = 15",
      "$gt0030|QRISK2 score|.magnitude = 0",

      "$gt0030.magnitude = $gt0030.magnitude + $gt0004|Smoking category 1|.value * 0.2119377108760385200000000",
      "$gt0030.magnitude = $gt0030.magnitude + $gt0005|Smoking category 2|.value * 0.6618634379685941500000000",
      "$gt0030.magnitude = $gt0030.magnitude + $gt0006|Smoking category 3|.value * 0.7570714587132305600000000",
      "$gt0030.magnitude = $gt0030.magnitude + $gt0007|Smoking category 4|.value * 0.9496298251457036000000000",

4.3.4. Expression Elements

Most expression terminal elements shown in the Section 5.3 below are generated during the process of parsing larger expressions and statements found within guidelines, as per the above examples. Consequently, some properties, such as types of constants and variables are inferred and generated on the fly, rather than being stated literally within a guideline.

4.3.5. Local Variables

Local variables identified by gt-codes may be defined by including their gt-code definitions in the terminology in the normal way, and then just using them within assertions and assignments. They are tracked in the list GUIDELINE_DEFINITION.internal_variables, which is constructed on the fly during guideline materialisation.

4.4. Reporting

The actions performed when a GDL2 rule is fired consist of assignments, which result in a value being set in a location of an output data set.

The following example shows a rule whose then action list includes the internal call use_template($gt2022). The code gt2022 refers to a reporting 'template', which appears below the rule that mentions it. Within this template, the object field contains a structure whose model is defined by the preceding model_id and template_id attributes. Within the object structure, any output variables from the Guideline may be mentioned using the syntax {}, which means that at execution time, if the rule is fired, the template will be evaluated such that all {} mentions are substituted with their variable values, before final processing of the template (which might for example send it to a specific receiver service or application).

    "rules": {
      "gt0007": {
        "id": "gt0007",
        "priority": 1,
        "when": [...],
        "then": [
          "$gt0009|card.summary|='tTG serological testing is recommended'",
          "use_template($gt2022)"
        ]
      }

    "templates": {
      "gt2022": {
        "id": "gt2022",
        "name": "coeliac-disease-alert",
        "model_id": "generic_model",
        "template_id": "generic_model",
        "object": {
          "cards": [
            {
              "summary": "{$gt0009}",
              "detail": "Found risk factor(s):{$gt0020}",
              "indicator": "warning",
              "source": {
                "label": "National Institute for Health and Care Excellence (NICE). Coeliac disease: recognition, assessment and management. 2015.",
                "url": "https://www.nice.org.uk/guidance/ng20"
              }
            }
          ]
        }
      }
    },

5. GDL2 Object Model

5.1. Package Structure

The Guideline Object Model, the object model of GDL2 consists of three packages, the guideline package, expression package and the terminology package, each described in detail through the following sections.

CDS cds packages
Figure 3. cds Package

5.2. Guideline Package

5.2.1. Overview

The following UML diagram shows the guideline and terminology packages.

CDS cds.guideline
Figure 4. cds.guideline Package

5.2.2. Class Definitions

5.2.2.1. GUIDELINE Class

Class

GUIDELINE

Description

Representation of a discrete guideline, which defines archetype bindings, rules and descriptive meta-data.

Inherit

AUTHORED_RESOURCE

Attributes

Signature

Meaning

1..1

id: String

Identification of this guideline. Syntax is a string of format:

  • concept_name '.v' [N[.M.P]]

For example: calculate_bmi.v1.

0..1

gdl_version: String

The version of the GDL the guide is written in, in a string of format:

  • N.M[.P]

i.e. a 2- or 3-number form of version, e.g. "1.0", "2.0", etc.

1..1

concept: String

The normative meaning of the guideline as whole. Expressed as a gt-code.

1..1

definition: GUIDELINE_DEFINITION

The main definition part of the guide. It consists of archetype bindings and rule definitions.

1..1

terminology: TERMINOLOGY

Terminology definitions of the guideline containing definitions and translations (if applicable) for every gt-code.

5.2.2.2. GUIDELINE_DEFINITION Class

Class

GUIDELINE_DEFINITION

Description

The definition of the guideline includes:

  • pre_conditions: conditions defining the applicability of this guideline to a subject;

  • data bindings: bindings to to archetypes and other sources;

  • rules: define the logic of the guideline;

  • template: defines the output reporting structure.

Attributes

Signature

Meaning

0..1

data_bindings: Hash<String,DATA_BINDING>

List of archetype/template bindings, which define specific elements to be used by rules in this guideline.

0..1

pre_conditions: List<ASSERTION>

Pre-conditions to be met before the guideline can be selected for execution. Pre-conditions constitute the definition of the guideline 'entry point', i.e. the match to a patient type to which the guideline may apply.

0..1

rules: Hash<String,RULE>

Map of rules indexed by local gt codes.

0..1

default_actions: List<ASSIGNMENT>

Actions that will always be performed, whenever the when conditions are evaluated, regardless of the result.

0..1

templates: Hash<String,OUTPUT_TEMPLATE>

One or more output termplates that define how to represent output reporting structure.

0..1

internal_variables: List<VARIABLE>

Variables used internally to a GDL guideline, i.e. not bound to external data entities. These are generated during parsing of expressions and used to track interim state.

5.2.2.3. RULE Class

Class

RULE

Description

A single rule defined in a guideline, of the logical form

when conditions then actions.

Conditions are assertions based on input and/or environment variables (e.g.time, date etc). Actions take the form of assignments to output variables.

Attributes

Signature

Meaning

1..1

id: String

The gt-code of this rule.

0..1

when: List<ASSERTION>

List of assertions that when evaluated to True cause the rule to be fired. The when assertions may only mention 'input' type variables.

0..1

then: List<ASSIGNMENT>

List of actions if the rule is fired. Each action is in the form of an assignment to an 'output' type variable.

1..1

priority: Integer

Indicates the evaluation order of Rules within a Guideline. Rules with a higher priority value are executed first.

5.2.2.4. DATA_BINDING Class

Class

DATA_BINDING

Description

A list of bindings of nodes for a data-set' - i.e. from the archetype (and optionally template) specified by archetype_id and template_id respectively, to guideline variables, each specified by an element binding.

Attributes

Signature

Meaning

1..1

model_id: String

The identifier of the data-set model (i.e. archetype or other) from which the list of elements is selected.

0..1

template_id: String

The ID of an optional template to be used for selecting elements.

0..1

bindings: Hash<String,ELEMENT>

Map of variable binding indexed by identifying gt-code of the variable.

0..1

predicates: List<ASSERTION>

Predicates (constraints) that need to be satisfied before rule execution can occur. Generally speaking, predicates are constraints on variable values, and can only mention gt-codes of variables.

1..1

type: String

Marker to indicate whether variable is an input or output variable in the data-set. The value can either be:

  • "INPUT": input data to the guideline, e.g. values retrieved from the EHR;

  • "OUTPUT": output value generated by Guideline Rule execution.

5.2.2.5. ELEMENT Class

Class

ELEMENT

Description

The binding between a specific node in an archetype and a variable in the guide.

Attributes

Signature

Meaning

1..1

id: String

The gt-code of this element.

1..1

path: String

The path within archetype to reach this element.

5.2.2.6. OUTPUT_TEMPLATE Class

Class

OUTPUT_TEMPLATE

Description

Definition of structure for reporting guideline execution results.

Attributes

Signature

Meaning

1..1

id: String

The gt-code of this output template.

1..1

name: String

Name of this template.

1..1

model_id: String

Identifier of a model that defines the structure of the object.

0..1

template_id: String

The identifier of a template based on the model identified by model_id defining the attached object.

1..1

object: String

Detailed output report structure as an object that may be defined by a published model.

5.3. Expressions Package

5.3.1. Overview

The expression package is illustrated below.

CDS cds.expression
Figure 5. cds.expression Package

5.3.2. Class Definitions

5.3.2.1. EXPRESSION_ITEM Class

Class

EXPRESSION_ITEM (abstract)

Description

Abstract parent of all valued elements that may be used as a term in an expression. Concrete descendant types are generated by a GDL2 parser when processing a GDL2 text.

The function type() returns a value for the type of any concrete element, which may have been inferred and stored during parsing (Constants and Variables), or may be looked up (library of function calls).

Functions

Signature

Meaning

1..1

type (): String

Type name of the item. Comparisons should be done case-insensitive.

5.3.2.2. OPERATOR Class

Class

OPERATOR (abstract)

Description

Abstract model of an operator-based expression.

Inherit

EXPRESSION_ITEM

Attributes

Signature

Meaning

1..1

operator: OPERATOR_KIND

The operator type of this expression.

5.3.2.3. UNARY_OPERATOR Class

Class

UNARY_OPERATOR

Description

Concrete model of a unary operator in the rule.

Inherit

OPERATOR

Attributes

Signature

Meaning

1..1

operand: EXPRESSION_ITEM

The operand.

5.3.2.4. BINARY_OPERATOR Class

Class

BINARY_OPERATOR

Description

Concrete model of a binary operator in the rule.

Inherit

OPERATOR

Attributes

Signature

Meaning

1..1

left: EXPRESSION_ITEM

Left operand.

1..1

right: EXPRESSION_ITEM

Right operand.

5.3.2.5. OPERATOR_KIND Enumeration

Enumeration

OPERATOR_KIND

Description

Enumeration of operator types.

Attributes

Signature

Meaning

ADDITION

Addition ('+') operation.

SUBTRACTION

Subtraction ('-') operation.

MULTIPLICATION

Multiplication ('*') operation.

DIVISION

Division ('/') operation.

EXPONENT

Exponent ('^') operation.

AND

Logical and ('&&') operation.

OR

Logical or ('||') operation.

NOT

Logical negation ('!') operation.

EQUALITY

Relational equality ('==') operation.

INEQUALITY

Relational inequality ('!=') operation.

LESS_THAN

Relational less-than ('<') operation.

GREATER_THAN

Relational greater-than ('>') operation.

LESS_THAN_OR_EQUAL

Relational less-than-or-equal ('<=') operation.

GREATER_THAN_OR_EQUAL

Relational greater-than-or-equal ('>=') operation.

IS_A

Subsumption operator ('is_a').

IS_NOT_A

Negated subsumption operator ('!is_a').

FOR_ALL

Universal quantifier operator ('∀').

5.3.2.6. FUNCTION_CALL Class

Class

FUNCTION_CALL

Description

Concrete expression in the form of a function.

Inherit

EXPRESSION_ITEM

Attributes

Signature

Meaning

0..1

items: List<EXPRESSION_ITEM>

Function arguments.

1..1

function: FUNCTION_KIND

The specific function.

5.3.2.7. FUNCTION_KIND Enumeration

Enumeration

FUNCTION_KIND

Description

Enumeration of function types.

Attributes

Signature

Meaning

abs

Returns the absolute value of a double value.

ceil

Returns the smallest double value that is greater than or equal to the argument and is equal to a mathematical integer.

exp

Returns Euler’s number e raised to the power of a double value.

floor

Returns the largest double value that is less than or equal to the argument and is equal to a mathematical integer.

log

Returns the natural logarithm (base e) of a double value.

log10

Returns the base 10 logarithm of a double value.

log1p

Returns the natural logarithm of the sum of the argument and 1.

round

Returns the closest long to the argument, with ties rounding to positive infinity.

sqrt

Returns the correctly rounded positive square root of a double value.

sin

Returns the trigonometric sine of an angle.

cos

Returns the trigonometric cosine of an angle.

max

Maximum value of N elements.

min

Minimum value of N elements.

count

Count of instances of an element.

sum

Total sum of N element values.

5.3.2.8. CONSTANT Class

Class

CONSTANT (abstract)

Description

Terminal expression element representing a constant; subtypes define constants of specific types.

Inherit

EXPRESSION_ITEM

Attributes

Signature

Meaning

1..1

name: String

Symbolic name of constant.

1..1

value: Any

Value of constant, redefined to specific types in descendants.

5.3.2.9. STRING_CONSTANT Class

Class

STRING_CONSTANT

Description

Constant of type String.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: String

Value of constant, redefined to specific types in descendants.

5.3.2.10. INTEGER_CONSTANT Class

Class

INTEGER_CONSTANT

Description

Constant of type Integer.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: Integer

Value of constant, redefined to specific types in descendants.

5.3.2.11. BOOLEAN_CONSTANT Class

Class

BOOLEAN_CONSTANT

Description

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: Boolean

Value of constant, redefined to specific types in descendants.

5.3.2.12. DATE_TIME_CONSTANT Class

Class

DATE_TIME_CONSTANT

Description

Constant of type Date/time.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: Iso8601_date_time

Value of constant, redefined to specific types in descendants.

5.3.2.13. CODE_PHRASE_CONSTANT Class

Class

CODE_PHRASE_CONSTANT

Description

Constant of type Code phrase.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: CODE_PHRASE

Value of constant, redefined to specific types in descendants.

5.3.2.14. CODED_TEXT_CONSTANT Class

Class

CODED_TEXT_CONSTANT

Description

Constant of type Coded text.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: DV_CODED_TEXT

Value of constant, redefined to specific types in descendants.

5.3.2.15. ORDINAL_CONSTANT Class

Class

ORDINAL_CONSTANT

Description

Constant of type Ordinal.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: DV_ORDINAL

Value of constant, redefined to specific types in descendants.

5.3.2.16. QUANTITY_CONSTANT Class

Class

QUANTITY_CONSTANT

Description

Constant of type Quantity.

Inherit

CONSTANT

Attributes

Signature

Meaning

1..1
(redefined)

value: DV_QUANTITY

Value of constant, redefined to specific types in descendants.

5.3.2.17. VARIABLE Class

Class

VARIABLE

Description

Terminal expression element representing a named variable with a definition provided by the code attribute, containing a gt-code.

Inherit

EXPRESSION_ITEM

Attributes

Signature

Meaning

1..1

name: String

Variable symbolic name.

1..1

code: String

Internal gt-code defining the meaning of this variable.

5.3.2.18. STATEMENT Class

Class

STATEMENT (abstract)

Description

Abstract concept of a statement, which is a self-standing procedural element.

5.3.2.19. ASSIGNMENT Class

Class

ASSIGNMENT

Description

A statement assigning an expression result to a variable.

Inherit

STATEMENT

Attributes

Signature

Meaning

1..1

variable: VARIABLE

Variable that is the target of the assignment.

1..1

expression: EXPRESSION_ITEM

Expression that is the source of the assignment.

5.3.2.20. ASSERTION Class

Class

ASSERTION

Description

A statement of the logical form assert(cond) that asserts the truth of a Boolean expression, which if not true, generates an exception at runtime.

Inherit

STATEMENT

Attributes

Signature

Meaning

1..1

expression: EXPRESSION_ITEM

Expression that is the subject of the assertion.

Invariants

Inv_expression_type: expression.type().is_case_insensitive_equal('Boolean')

5.4. Terminology Package

5.4.1. Overview

The terminology package is illustrated earlier. The TERMINOLOGY and TERM classes are slightly simplified versions of the ARCHETYPE_TERMINOLOGY and ARCHETYPE_TERM classes from the openEHR AOM2 specification.

5.4.2. Class Definitions

5.4.2.1. TERMINOLOGY Class

Class

TERMINOLOGY

Description

Local terminology of an archetype. This class defines the semantics of the terminology of an archetype.

Attributes

Signature

Meaning

1..1

is_differential: Boolean

Indicates whether this terminology is differential with respect to a specialisation parent, or complete.

1..1

original_language: String

Original language of the terminology, as set at creation or parsing time; must be a code in the ISO 639-1 2 character language code-set.

1..1

concept_code: String

Term code defining the meaning of the artefact as a whole, and always used as the at-code on the root node of the archetype. Must be defined in the term_definitions property.

1..1

term_definitions: Hash<String, Hash<String, TERM>>

Directory of term definitions as a two-level table. The outer hash keys are language codes, e.g. "en", "de", while the inner hash keys are term codes, e.g. "gt17".

0..1

term_bindings: Hash <String, TERM_BINDING>

Directory of bindings to external terminology codes and value sets, as a two-level table. The outer hash keys are terminology ids, e.g. "SNOMED_CT", and the inner hash keys are constraint codes, e.g. "at4", "ac13" or paths. The indexed DV_URI objects represent references to externally defined resources, either terms, ontology concepts, or terminology subsets / ref-sets.

Functions

Signature

Meaning

1..1

specialisation_depth (): Integer

Specialisation depth of this artefact. Unspecialised artefacts have depth 0, with each additional level of specialisation adding 1 to the specialisation_depth.

1..1

has_language (
a_lang: String[1]
): Boolean

True if language a_lang is present in archetype terminology.

1..1

has_terminology (
a_terminology_id: String[1]
): boolean

True if there are bindings to terminology a_terminology_id present. True if terminology `a_terminology' is present in archetype ontology.

1..1

has_term_code (
a_code: String[1]
): boolean

True if code a_code defined in this terminology.

1..1

term_definition (
a_lang: String[1],
a_code: String[1]
): TERM

Pre: has_term-definition (a_lang, a_code)

Term definition for a code, in a specified language.

1..1

term_binding (
a_terminology: String[1],
a_code: String[1]
): Uri

Pre: has_term_binding (a_terminology_id, a_code)

Binding of constraint corresponding to a_code in target external terminology a_terminology_id, as a string, which is usually a formal query expression.

1..1

terminologies_available (): List<String>

List of terminologies to which term or constraint bindings exist in this terminology, computed from bindings.

1..1

languages_available (): List<String>

List of languages in which terms in this terminology are available.

Invariants

Original_language_validity: code_set (Code_set_id_languages).has_concept_id (original_language)

concept_code_validity: id_codes.has (concept_code)

Term_bindings_validity: bindings /= void implies not bindings.is_empty

Parent_archetype_valid: parent_archetype.terminology = Current

5.4.2.2. TERM Class

Class

TERM

Description

Representation of any coded entity (term or constraint) in the artefact terminology.

Attributes

Signature

Meaning

1..1

code: String

Code of this term.

1..1

text: String

Short term text, typically for display.

1..1

description: String

Full description text.

0..1

other_items: Hash<String, String>

Hash of keys and corresponding values for other items in a term, e.g. provenance. Hash of keys ("text", "description" etc) and corresponding values.

5.4.2.3. TERM_BINDING Class

Class

TERM_BINDING

Description

One binding between a local gt-code and one or more external bindings

Attributes

Signature

Meaning

0..1

bindings: List<TERM>

List of external codes, typically parsed in either URI form or openEHR standard form namespace '::' code.

1..1

code: String

Local gt-code to which external terms are bound.

6. Syntax Specification

The grammar and lexical specification for the standard GDL is entirely based on openEHR ODIN syntax, with a JSON equivalent, and driven by the guideline object model defined in this specification.

6.1. Syntax Specification

The grammar and lexical specification for the expressions used by GDL is loosely based on the assertion syntax in the ADL specification. This grammar is implemented using javaCC specifications in the Java programming environment. The full source code of the java GDL parser is available here.