Archetype Definition Language

1.1 Purpose

This document describes the design basis and syntax of the Archetype Definition Language (ADL). It is intended for software developers, technically-oriented domain specialists and subject matter experts (SMEs). Although ADL is primarily intended to be read and written by tools, it is quite readable by humans and ADL archetypes can be hand-edited using a normal text editor.

The intended audience includes:

• Standards bodies producing health informatics standards;
• Software development organisations using openEHR;
• Academic groups using openEHR;
• The open source healthcare community;
• Medical informaticians and clinicians interested in health information;
• Health data managers.

1.2 Related Documents

Prerequisite documents for reading this document include:

• The openEHR Architecture Overview Related documents include:

• The openEHR Archetype Object Model (AOM)
• The openEHR Archetype Profile (oAP)

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’.

1.4 Status

This document is under development, and is published as a proposal for input to standards processes and implementation works.

This document is available at http://svn.openehr.org/specification/TAGS/Release 1.0.1/publishing/architecture/am/adl2.pdf .

The latest version of this document can be found at http://svn.openehr.org/specifica tion/TRUNK/publishing/architecture/am/adl2.pdf .

Blue text indicates sections under active development.

Editors:{T Beale, S Heard} Page 9 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Introduction Archetype Definition Language ADL 2 Rev 2.1.0

1.5 Peer review

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

TBD_1: (example To Be Determined paragraph)

Areas where more analysis or explanation is required are indicated with “to be continued” paragraphs like the following:

To Be Continued: more work required

Reviewers are encouraged to comment on and/or advise on these paragraphs as well as the main content. Please send requests for information to info@openEHR.org. Feedback should preferably be provided on the mailing list openehr-technical@openehr.org, or by private email.

1.6 Conformance

Conformance of a data or software artifact to an openEHR Reference Model 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, automated derivations from the Reference Model, ITS conformance indicates RM conformance.

Date of Issue: 03 Mar 2007 Page 10 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 Overview Rev 2.1.0

2.1 What is ADL?

Archetype Definition Language (ADL) is a formal language for expressing archetypes, which are constraint-based models of domain content. The archetype concept is described by Beale [1], [2]. The openEHR Archetype Object Model [3] describes the definitive semantic model of archetypes, in the form of an object model. The ADL syntax is one possible serialisation of an archetype.

The openEHR archetype framework is described in terms of Archetype Definitions and Principles [6] and an Archetype System [7]. Other semantic formalisms which were considered in the course of archetype, and some which remain relevant are described in detailed in section 11 on page 43.

To describe constraints on data which are instances of some information model (e.g. expressed in UML), ADL archetypes use three syntaxes: dADL (a data expression syntax), cADL (a constraint expression syntax), and a version of first-order predicate logic (FOPL). It is most useful when very generic information models are used for describing the data in a system, for example, where the logical concepts PATIENT, DOCTOR and HOSPITAL might all be represented using a small number of classes such as PARTY and ADDRESS. In such cases, archetypes are used to constrain the valid structures of instances of these generic classes to represent the desired domain concepts. In this way future-proof information systems can be built - relatively simple information models and database schemas can be defined, and archetypes supply the semantic modelling, completely outside the software. ADL can thus be used to write archetypes for any domain where formal object model(s) exist which describe data instances.

When archetypes are used at runtime in particular contexts, they are composed into larger constraint structures, with local or specialist constraints added, via the use of templates. The formalism of templates is dADL. Archetypes can be specialised by creating an archetypes that reference existing archetypes as parents; such archetypes can only make certain changes while remaining compatible with the parent.

Another major function of archetypes is to connect information structures to formal terminologies. Archetypes are language-neutral, and can be authored in and translated into any language.

Finally, archetypes are completely path-addressable in a manner similar to XML data, using path expressions that are directly convertible to Xpath expressions.

2.2 Computational Context

An archetypes is a structured model of domain content, such as “blood pressure”. Archetypes sit between knowledge resources in a computing environment, such as terminologies and ontologies, and runtime data in production systems. Their primary purpose is to provide a reusable, interoperable way of managing data creation, validation and querying, by ensuring that data conform to particular structures and semantic constraints. Every ADL archetype is written with respect to a particular information model, often known as a “reference model”, if it is a shared, public specification.

Archetypes are applied to data via the use of templates, which are defined at a local level. Templates generally correspond closely to screen forms, and may be re-usable at a local or regional level. Templates do not introduce any new semantics to archetypes, they simply specify the use of particular archetypes in particular hierarchical compositions, as well as default data values.

A third artifact that governs the functioning of archetypes and templates at runtime is a local palette, which specifies which natural language(s) and terminologies are in use in the locale. The use of a palette removes irrelevant languages and terminology bindings from archetypes, retaining only those relevant to actual use. FIGURE 3 illustrates the overall environment in which archetypes, templates, and a locale palette exist.

2.3 XML form of Archetypes

With ADL parsing tools it is possible to convert ADL to any number of forms, including various XML formats. XML instance can be generated from the object form of an archetype in memory. An XML-schema corresponding to the ADL Object Model is published on openEHR.org.

Date of Issue: 03 Mar 2007 Page 14 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 Overview Rev 2.1.0

Archetypes

Library

FIGURE 3 Archetypes, Templates, and Palettes

2.4 Changes From Previous Versions

For existing users of ADL or archetype development tools, the following provides a guide to the changes in the syntax.

2.5 Tools

A validating ADL parser is freely available from http://my.openehr.org/wsvn/oe_distrib/. It has been wrapped for use in Java and Microsoft .Net, and standard C/C++ environments. See the website for the latest status.

Editors:{T Beale, S Heard} Page 17 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Overview Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 18 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 dADL - Data ADL Rev 2.1.0

dADL - Data ADL

The dADL specification is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 19 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 20 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 cADL - Constraint ADL Rev 2.1.0

cADL - Constraint ADL

The cADL specification is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 21 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 22 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 Assertions Rev 2.1.0

Assertions

The assertion specification is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 23 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Declarations Archetype Definition Language ADL 2 Rev 2.1.0

Declarations

This section for a future release of ADL

To Be Determined: main problem of variables is that they must havenames, which are language-dependent; imagine if there were a mixture ofvariables added by authors in different languages. The only solution is toname them with terms.

To Be Determined: Variables have to be treated as term coordinations,and should be coded e.g. using ccNNNN codes (“cc” = coordinated code). Then they can be given meanings in any language.

6.1 Predefined Variables

A number of predefined variables can be referenced in ADL assertion expressions, without prior definition, including:

• $current_date: Date; returns the date whenever the archetype is evaluated
• $current_time: Time; returns time whenever the archetype is evaluated
• $current_date_time: Date_Time; returns date/time whenever the archetype is evaluated

To Be Continued: these should be coded as well, using openEHR codes

6.2 Archetype-defined Variables

Variables can also be defined inside an archetype, as part of the assertion statements in an invariant. The syntax of variable definition is as follows:

let $var_name = reference

Here, a reference can be any of the operand types listed above. ‘Let’ statements can come anywhere in an invariant block, but for readability, should generally come first.

The following example illustrates the use of variables in an invariant block:

invariant

let $sys_bp =

/data[at9001]/events[at9002]/data[at1000]/items[at1100]

let $dia_bp =

/data[at9001]/events[at9002]/data[at1000]/items[at1200]

$sys_bp >= $dia_bpTo Be Continued:

Date of Issue: 03 Mar 2007 Page 24 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL Paths Rev 2.1.0

ADL Paths

The path specification is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 25 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL Paths Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 26 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL - Archetype Definition Language Rev 2.1.0

ADL - Archetype Definition Language

8.1 Introduction

This section describes ADL archetypes as a whole, adding a small amount of detail to the descriptions of dADL and cADL already given. The important topic of the relationship of the cADL-encoded definition section and the dADL-encoded ontology section is discussed in detail. In this section, only standard ADL (i.e. the cADL and dADL constructs and types described so far) is assumed. Archetypes for use in particular domains can also be built with more efficient syntax and domain-spe cific types, as described in Customising ADL on page 41, and the succeeding sections.

An ADL archetype is a dADL document with the structure shown below:

archetype_id = <“some.archetype.id”> adl_version = <“2.0”>

is_controlled = <True> parent_archetype_id = <“some.other.archetype.id”>

concept = <[concept_code]> original_language = <“lang”>

translations = < ... >

description = <

...

> definition = (cadl) <#

cADL plug-in section

#> invariant = (aadl) <#

assertions plug-in section

#> ontology = <

...

> revision_history = <

...

>

In the above, all top-level attribute names are an exact match in name and type for a corresponding attribute in the openEHR. Archetype Object Model (AOM). Optional parts are shown unbolded. In this document, top level attributes are usually described as ‘sections’ of the archetype.

8.2 Basics

8.2.1 Order of Sections

As of ADL 2.0, order is no longer significant in archetypes. However, it is strongly recommended that the order above be respected, since it is the logical reading order, and some parser implementations may rely on it.

8.2.2 Keywords

ADL has no keywords of its own (i.e, distinct from the keywords in cADL and the invariant language), although depending on how parsers are built, the top-level attribute names might be regarded as special in some implementations.

Editors:{T Beale, S Heard} Page 27 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

8.2.3 Node Identification

In the definition section of an ADL archetype, a particular scheme of codes is used for node identifiers as well as for denoting constraints on textual (i.e. language dependent) items. Codes are either local to the archetype, or from an external lexicon. This means that the archetype description is the same in all languages, and is available in any language that the codes have been translated to. All term codes are shown in brackets ([]). Codes used as node identifiers and defined within the same archetype are prefixed with “at” and by convention have 4 digits, e.g. [at0010]. Codes of any length are acceptable in ADL archetypes. Specialisations of locally coded concepts have the same root, followed by ‘dot’ extensions, e.g. [at0010.2]. From a terminology point of view, these codes have the implied semantics of subsumption; additionally - the ‘dot’ structuring is used as an optimisation on node identification.

8.2.4 Local Constraint Codes

A second kind of local code is used to stand for constraints on textual items in the body of the archetype. Although these could be included in the main archetype body, because they are language- and/or terminology-sensitive, they are defined in the ontology section, and referenced by codes prefixed by “ac”, e.g. [ac0009]. As for “at” codes, the convention used in this document is to use 4-digit “ac” codes, even though any number of digits is acceptable. The use of these codes is described in section

8.6.4

8.3 Header Sections

8.3.1 Archetype_id Section

This section introduces the archetype and must include an identifier. A typical archetype section is as follows:

archetype_id = <“mayo.openehr-ehr-entry.haematology.v1”>

The multi-axial identifier identifies archetypes in a global space. The syntax of the identifier is described under Archetype Identification on page 13 in The openEHR Archetype System.

8.3.2 Adl_version Section

This mandatory section indicates the version of ADL being used in the archetype. Its value is one of the revision values of this specification, such as “2.0”; it typically looks as follows:

adl_version = <“2.0”>

8.3.3 Is_controlled Section

This is an optional section indicating whether the archetype is change-controlled or not can be included after the version, as follows:

is_controlled = <False> The flag may have the values True and False only, and is an aid to software. Archetypes having is_controlled set to True must have the revision_history section included, while those with the value False, or no flag at all, may omit the revision_history section. This enables archetypes to be privately edited in an early development phase without generating large revision histories of little or no value.

Date of Issue: 03 Mar 2007 Page 28 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2		ADL - Archetype Definition Language
		Rev 2.1.0
8.3.4	Parent_archetype_id Section

This optional section indicates that the archetype is a specialisation of some other archetype, whose identity must be given. Only one specialisation parent is allowed, i.e. an archetype cannot ‘multiplyinherit’ from other archetypes. An example of declaring specialisation is as follows:

archetype_id = <“mayo.openehr-ehr-entry.haematology-cbc.v1”> parent_archetype_id = <“mayo.openehr-ehr-entry.haematology.v1”>

Here the identifier of the new archetype is derived from that of the parent by adding a new section to its domain concept section. See Archetype Identification on page 13 in The openEHR Archetype Sys tem.

8.3.5 Concept Section

All archetypes represent some real world concept, such as a “patient”, a “blood pressure”, or an “antenatal examination”. The concept section describes the overall concept using the code of a concept whose definition is given in the archetype ontology. Like any coded entity, it can be displayed in any language the archetype has been translated to. A typical concept section is as follows:

concept = <[at0010]> -- haematology resultIn this concept definition, the term definition of [at0010] contains a more complete description corresponding to the notion implied by the short identifier “haematology-cbc” in the example archteype_id section shown above.

8.3.6 Original_language and Translations Sections

The original_language and translations sections include meta-data describing the original language in which the archetype was authored (essential for evaluating natural language quality), and the total list of languages available in the archetype due to translation. There can be only one original_language. The translations section is optional, but must be present if any translations are present in the description or ontology sections; if present, it must be updated every time a translation of the archetype is undertaken. The following shows a typical example.

original_language = <[iso_639-1::en]> translations = <

[“de”] = <

language = <[iso_639-1::de]>

author = <"Frederick Smith">

accreditation = <"British Medical Translator id 00400595”> > [“ru”] = <

language = <[iso_639-1::ru]>

author = <"Vladimir Korotkov">

accreditation = <"Russion Translator id 892230A”>

other_details = <

[“email”] = <"vladimir.korotkov@acme.translators.ru"> > > >

Archetypes must always be translated completely or not at all to be valid. This means that when a new translation is made, every language dependent section of the description and ontology sections has to be translated into the new language, and an appropriate addition made to the translations list in the language section.

Editors:{T Beale, S Heard} Page 29 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

8.3.7 Description Section

The description section of an archetype contains descriptive information, or what some people think of as document “meta-data”, i.e. items that can be used in repository indexes and for searching. The dADL syntax is used for the description, as in the following example.

description = <

original_author = < [“name”] = <"Dr J Joyce"> [“organisation”] = <"NT Health Service"> [“date”] = <2003-08-03>

> lifecycle_state = <"initial"> resource_package_uri =

<"http://www.aihw.org.au/data_sets/diabetic_archetypes.html"> details = <

[“en”] = < purpose = <"archetype for diabetic patient review"> use = <"used for all hospital or clinic-based diabetic reviews,

including first time. Optional sections are removed according

to the particular review">misuse = <"not appropriate for pre-diagnosis use"> original_resource_uri =

<"http://www.healthdata.org.au/data_sets/

diabetic_review_data_set_1.html">

other_details = <...> > [“de”] = <

purpose = <"Archetyp für die Untersuchung von Patientenmit Diabetes">

use = <"wird benutzt für alle Diabetes-Untersuchungen imKrankenhaus, inklusive der ersten Vorstellung. OptionaleAbschnitte werden in Abhängigkeit von der speziellenVorstellung entfernt.">

misuse = <"nicht geeignet für Benutzung vor Diagnosestellung"> original_resource_uri = <"http://www.healthdata.org.au/data_sets/

diabetic_review_data_set_1.html"> other_details = <...> > > >

A number of details are worth noting here. Firstly, the free hierarchical structuring capability of dADL is exploited for expressing the ‘deep’ structure of the details section and its subsections. Secondly, the dADL qualified list form is used to allow multiple translations of the purpose and use to be shown. Lastly, empty items such as misuse (structured if there is data) are shown with just one level of empty brackets. The above example shows meta-data based on the openEHR Archetype Object Model (AOM).

The description section is technically optional according to the AOM, but in any realistic use of ADL for archetypes, it is likely to be required. A minimal description section satisfying to the AOM is as follows:

description = <

original_author = < [“name”] = <"Dr J Joyce"> [“organisation”] = <"NT Health Service"> [“date”] = <2003-08-03>

Date of Issue: 03 Mar 2007 Page 30 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL - Archetype Definition Language Rev 2.1.0

> lifecycle_state = <"initial"> details = <

[“en”] = < language = <[iso_639-1::en]> purpose = <"archetype for diabetic patient review">

> > >

8.4 Definition Section

The definition section contains the main formal definition of the archetype, and is written in the Constraint Definition Language (cADL). A typical definition section is as follows:

definition = (cadl) <# ENTRY[at0000] ∈ { -- blood pressure measurement name ∈ { -- any synonym of BP CODED_TEXT ∈ { code ∈ { CODE_PHRASE ∈ {[ac0001]} }

} } data ∈ {

HISTORY[at9001] ∈ { -- historyevents cardinality ∈ {1..*} ∈ {EVENT[at9002] occurrences ∈ {0..1} ∈ {-- baseline name ∈ {CODED_TEXT ∈ {code ∈ {CODE_PHRASE ∈ {[ac0002]}}

} } data ∈ {

ITEM_LIST[at1000] ∈ { -- systemic arterial BP items cardinality ∈ {2..*} ∈ {ELEMENT[at1100] ∈ { -- systolic BP name ∈ { -- any synonym of 'systolic' CODED_TEXT ∈ {code ∈ {CODE_PHRASE ∈ {[ac0002]}}

}}value ∈ {

QUANTITY ∈ {magnitude ∈ {|0..1000|}property ∈ {[properties::0944]}

-- “pressure”

units ∈ {[units::387]} -- “mm[Hg]”}}}

ELEMENT[at1200] ∈ { -- diastolic BP name ∈ { -- any synonym of 'diastolic'

Editors:{T Beale, S Heard} Page 31 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

CODED_TEXT ∈ {

code ∈ {

CODE_PHRASE ∈ {[ac0003]}

}}

}

value ∈ {

QUANTITY ∈ {

magnitude ∈ {|0..1000|}

property ∈ {[properties::0944]}

-- “pressure”

units ∈ {[units::387]} -- “mm[Hg]”

}

}

}

ELEMENT[at9000] occurrences ∈ {0..*} ∈ {*}

-- unknown new item

} ... This definition expresses constraints on instances of the types ENTRY, HISTORY, EVENT, ITEM_LIST, ELEMENT, QUANTITY, and CODED_TEXT so as to allow them to represent a blood pressure measurement, consisting of a history of measurement events, each consisting of at least systolic and diastolic pressures, as well as any number of other items (expressed by the [at9000] “any” node near the bottom).

8.4.1 Design-time and Run-time paths

All non-unique sibling nodes in a cADL text that correspond to nodes in data which might be referred to from elsewhere in the archetype (via use_node), or might be queryied at runtime, require a node identifier. It is preferable to assign a ‘design-time meaning’, enabling paths and queries to be expressed using logical meanings rather than meaningless identifiers. When data are created according to a cADL specification, the archetype node identifiers are written into the data, providing a reliable way of finding data nodes, regardless of what other runtime names might have been chosen by the user for the node in question. There are two reasons for doing this. Firstly, querying cannot rely on runtime names of nodes (e.g. names like “sys BP”, “systolic bp”, “sys blood press.” entered by a doctor are unreliable for querying); secondly, it allows runtime data retrieved from a persistence mechanism to be re-associated with the cADL structure which was used to create it.

An example which shows the difference between design-time meanings associated with node identifiers and runtime names is the following, from a SECTION archetype representing the problem/SOAP headings (a simple heading structure commonly used by clinicians to record patient contacts under top-level headings corresponding to the patient’s problem(s), and under each problem heading, the headings “subjective”, “objective”, “assessment”, and “plan”).

SECTION[at0000] matches { -- problem name matches {CODED_TEXT matches {code matches {[ac0001]}}}In the above, the node identifier [at0000] is assigned a meaning such as “clinical problem” in the archetype ontology section. The subsequent lines express a constraint on the runtime name attribute, using the internal code [ac0001]. The constraint [ac0001] is also defined in the archetype ontology section with a formal statement meaning “any clinical problem type”, which could clearly evaluate to thousands of possible values, such as “diabetes”, “arthritis” and so on. As a result, in the runtime data,

Date of Issue: 03 Mar 2007 Page 32 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL - Archetype Definition Language Rev 2.1.0

the node identifier corresponding to “clinical problem” and the actual problem type chosen at runtime by a user, e.g. “diabetes”, can both be found. This enables querying to find all nodes with meaning “problem”, or all nodes describing the problem “diabetes”. Internal [acNNNN] codes are described in Local Constraint Codes on page 28.

8.5 Invariant Section

The invariant section in an ADL archetype introduces assertions which relate to the entire archetype, and can be used to make statements which are not possible within the block structure of the definition section. Any constraint which relates more than one property to another is in this category, as are most constraints containing mathematical or logical formulae. Invariants are expressed in the archetype assertion language, described in section 5 on page 23 .

An invariant statement is a first order predicate logic statement which can be evaluated to a boolean result at runtime. Objects and properties are referred to using paths.

The following simple example says that the speed in kilometres of some node is related to the speed-in-miles by a factor of 1.6:

invariant = (aadl) <# validity: /speed[at0002]/kilometres/magnitude = /speed[at0004]/miles/magnitude * 1.6 #>

Note that in a well-designed archetype, the ‘1.6’ above should be coded and included in the ontology section.

8.6 Ontology Section

8.6.1 Overview

The ontology section of an archetype is expressed in dADL, and is where codes representing node IDs, constraints on text or terms, and bindings to terminologies are defined. Linguistic language translations are added in the form of extra blocks keyed by the relevant language. The following example shows the layout of this section.

ontology = < terminologies_available = <“snomed_ct”, ...> term_definitions = <

[“en”] = < [“at0000”] = <...> ...

>

[“de”] = < [“at0000”] = <...> ...

> > term_binding = <

[“snomed_ct”] = < [“at0000”] = <...> ...

>

... > constraint_definitions = <

Editors:{T Beale, S Heard} Page 33 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

[“en”] = <...> [“ac0001”] = <...> ...

[“de”] = < [“ac0001”] = <...> ...

>

... > constraint_binding = <

[“snomed_ct”] = <...> ... > > The term_definitions section is mandatory, and must be defined for each translation carried out.

Each of these sections can have its own meta-data, which appears within description sub-sections, such as the one shown above providing translation details.

8.6.2 Terminologies_available Sub-section

This section provides the total list of external terminologies which are mentioned anywhere else in the ontology.

terminologies_available = <“snomed_ct”, ...>

8.6.3 Term_definitions Sub-section

This section is where all archetype local terms (that is, terms of the form [atNNNN]) are defined. The following example shows an extract from the English and German term definitions for the archetype local terms in a problem/SOAP headings archetype. Each term is defined using a structure of name/value pairs, and mustat least include the names “text” and “description”, which are akin to the usual rubric, and full definition found in terminologies like SNOMED-CT. Each term object is then included in the appropriate language list of term definitions, as shown in the example below.

term_definitions = < [“en”] = <

[“at0000”] = < text = <"problem"> description = <"The problem experienced by the subject

of care to which the contained information relates"> > [“at0001”] = <

text = <"problem/SOAP headings">

description = <"SOAP heading structure for multiple problems"> > ... [“at4000”] = <

text = <"plan"> description = <"The clinician's professional advice">

> > [“de”] = <

[“at0000”] = < text = <"klinisches Problem"> description = <"Das Problem des Patienten worauf sich diese \

Informationen beziehen"> >

Date of Issue: 03 Mar 2007 Page 34 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL - Archetype Definition Language Rev 2.1.0

[“at0001”] = < text = <"Problem/SOAP Schema"> description = <"SOAP-Schlagwort-Gruppierungsschema fuer

mehrfache Probleme">

>

[“at4000”] = < text = <"Plan"> description = <"Klinisch-professionelle Beratung des Pflegenden">

> > >

In some cases, term definitions may have been lifted from existing terminologies. This is only a safe thing to do if the following conditions apply:

• if there is a lexical match between the intended term in the archetype and the preferred term or a synonym in the terminology;
• the definitions exactly match the need in the archetype;
• if the classification of the term in the terminology would classify real world instances (e.g. people with a certain illness) the same way as intended by the archetype design.

To indicate where definitions come from, a “provenance” tag can be used, as follows:

[“at4000”] = < text = <"plan">; description = <"The clinician's professional advice">; provenance = <"ACME_terminology(v3.9a)">

>

Note that this does not indicate a binding to any term, only its origin. Bindings are described in sec tion 8.6.5 and section 8.6.6.

8.6.4 Constraint_definition Sub-section

The constraint_definition section is of exactly the same form as the term_definition section, and provides the definitions - i.e. the meanings - of the local constraint codes, which are of the form [acNNNN]. Each such code refers to some constraint such as “any term which is a subtype of ‘hepatitis’ in the ICD9AM terminology”; the constraint definitions do not provide the constraints themselves, but define the meanings of such constraints, in a manner comprehensible to human beings, and usable in GUI applications. This may seem a superfluous thing to do, but in fact it is quite important. Firstly, term constraints can only be expressed with respect to particular terminologies - a constraint for “kind of hepatitis” would be expressed in different ways for each terminology which the archetype is bound to. For this reason, the actual constraints are defined in the constraint_binding section. An example of a constraint term definition for the hepatitis constraint is as follows:

[“ac1015”] = < text = <"type of hepatitis"> description = <"any term which means a kind of viral hepatitis">

>

Note that while it often seems tempting to use classification codes, e.g. from the ICD vocabularies, these will rarely be much use in terminology or constraint definitions, because it is nearly always descriptive, not classificatory terms which are needed.

8.6.5 Term_binding Sub-section

This section is used to describe the equivalences between archetype local terms and terms found in external terminologies. The purpose is solely for allowing query engine software which wants to

Editors:{T Beale, S Heard} Page 35 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

search for an instance of some external term to determine what equivalent to use in the archetype. Note that this is distinct from the process of embedding mapped terms in runtime data, which is also possible with the data models of HL7v3, openEHR, and CEN 13606.

A typical term binding section resembles the following:

term_binding = <

[“umls”] = < [“at0000”] = <[umls::C124305]> -- apgar result[“at0002”] = <[umls::0000000]> -- 1-minute event [“at0004”] = <[umls::C234305]> -- cardiac score [“at0005”] = <[umls::C232405]> -- respiratory score[“at0006”] = <[umls::C254305]> -- muscle tone score [“at0007”] = <[umls::C987305]> -- reflex response score [“at0008”] = <[umls::C189305]> -- color score [“at0009”] = <[umls::C187305]> -- apgar score[“at0010”] = <[umls::C325305]> -- 2-minute apgar[“at0011”] = <[umls::C725354]> -- 5-minute apgar[“at0012”] = <[umls::C224305]> -- 10-minute apgar

> >

Each entry simply indicates which term in an external terminology is equivalent to the archetype internal codes. Note that not all internal codes necessarily have equivalents: for this reason, a terminology binding is assumed to be valid even if it does not contain all of the internal codes.

8.6.6 Constraint_binding Sub-section

The last of the ontology sections formally describes bindings to placeholder constraints (see Place holder Constraints on page 62) from the main archetype body. They are described separately because they are terminology-dependent, and because there may be more than one for a given logical constraint. A typical example follows:

constraint_binding = <

[“snomed_ct”] = < [“ac0001”] = <http://terminology.org?query_id=12345> [“ac0002”] = <http://terminology.org?query_id=678910>

> >

In this example, each local constraint code is formally defined to refer to a query defined in a terminology service, in this case, a terminology service that can interrogate the Snomed-CT terminology.

8.7 Revision_history Section

The revision_history section of an archetype shows the audit history of changes to the archetype, and is expressed in dADL syntax. It is optional, and is included at the end of the archetype, since it does not contain content of direct interest to archetype authors, and will monotonically grow in size. Where archetypes are stored in a version-controlled repository such as CVS or an equivalent commercial product, the revision history section would normally be regenerated each time by the authoring software, e.g. via processing of the output of the ‘prs’ command used with SCCS files, or ‘rlog’ for RCS files. The following shows a typical example, with entries in most-recent-first order (although technically speaking, the order is irrelevant to ADL).

revision_history = <

["1.57"] = < committer = <"Miriam Hanoosh">

Date of Issue: 03 Mar 2007 Page 36 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 ADL - Archetype Definition Language Rev 2.1.0

committer_organisation = <"AIHW.org.au"> time_committed = <2004-11-02 09:31:04+1000> revision = <"1.2"> reason = <"Added social history section"> change_type = <"Modification">

> -- etc ["1.1"] = <

committer = <"Enrico Barrios"> committer_organisation = <"AIHW.org.au"> time_committed = <2004-09-24 11:57:00+1000> revision = <"1.1"> reason = <"Updated HbA1C test result reference"> change_type = <"Modification">

>

["1.0"] = < committer = <"Enrico Barrios"> committer_organisation = <"AIHW.org.au"> time_committed = <2004-09-14 16:05:00+1000> revision = <"1.0"> reason = <"Initial Writing"> change_type = <"Creation">

> >

8.8 Validity Rules

This section describes the formal (i.e. checkable) semantics of ADL archetypes. It is recommended that parsing tools use the identifiers published here in their error messages, as an aid to archetype designers.

8.8.1 Global Archetype Validity

The following validity constraints apply to an archetype as a whole. Note that the term “section” means the same as “attribute” in the following, i.e. a section called “definition” in a dADL text is a serialisation of the value for the attribute of the same name.

VARID: archetype identifier validity. The archetype must have an identifier value for the archetype_id section. The identifier must conform to the published openEHR specification for archetype identifiers.

VARCN: archetype concept validity. The archetype must have an archetype term

value in the concept section. The term must exist in the archetype ontology.

VARDF: archetype definition validity. The archetype must have a definition section,

expressed as a cADL syntax string, or in an equivalent plug-in syntax.

VARON: archetype ontology validity. The archetype must have an ontology sec

tion, expressed as a cADL syntax string, or in an equivalent plug-in syntax.

VARDT: archetype definition typename validity. The topmost typename mentioned in the archetype definition section must match the type mentioned in the type-name slot of the first segment of the archetype id.

Editors:{T Beale, S Heard} Page 37 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

ADL - Archetype Definition Language Archetype Definition Language ADL 2 Rev 2.1.0

8.8.2 Coded Term Validity

All node identifiers (‘at’ codes) used in the definition part of the archetype must be defined in the term_definitions part of the ontology.

VATDF: archetype term validity. Each archetype term used as a node identifier the archetype definition must be defined in the term_definitions part of the ontology.

All constraint identifiers (‘ac’ codes) used in the definition part of the archetype must be defined in the constraint_definitions part of the ontology.

VACDF: node identifier validity. Each constraint code used in the archetype definition part must be defined in the constraint_definitions part of the ontology.

8.8.3 Definition Section

The following constraints apply to the definition section of the archetype.

VDFAI: archetype identifier validity in definition. Any archetype identifier mentioned in an archetype slot in the definition section must conform to the published openEHR specification for archetype identifiers.

VDFPT: path validity in definition. Any path mentioned in the definition section must be valid syntactically, and a valid path with respect to the hierarchical structure of the definition section.

Date of Issue: 03 Mar 2007 Page 38 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 The ADL Parsing Process Rev 2.1.0

The ADL Parsing Process

This sectoin is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 39 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

The ADL Parsing Process Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 40 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 Customising ADL Rev 2.1.0

10 Customising ADL

This section is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 41 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Customising ADL Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 42 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2 Relationship of ADL to Other Formalisms Rev 2.1.0

11 Relationship of ADL to Other Formalisms

This section is unchanged from the most recent ADL 1.x specification.

Editors:{T Beale, S Heard} Page 43 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Relationship of ADL to Other Formalisms Archetype Definition Language ADL 2 Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 44 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2

Rev 2.1.0

A References

Publications

1 Beale T. Archetypes: Constraint-based Domain Models for Future-proof Information Systems. OOPSLA 2002 workshop on behavioural semantics. Available at http://www.deepthought.com.au/it/archetypes.html.

2 Beale T. Archetypes: Constraint-based Domain Models for Future-proof Information Systems. 2000. Available at http://www.deepthought.com.au/it/archetypes.html .

3 Beale T, Heard S. The openEHR Archetype Object Model. See http://www.openehr.org/repos itories/spec-dev/latest/publishing/architecture/arche types/archetype_model/REV_HIST.html.

4 Beale T. A Short Review of OCL. See http://www.deepthought.com.au/it/ocl_review.html .

5 Dolin R, Elkin P, Mead C et al. HL7 Templates Proposal. 2002. Available at http://www.hl7.org .

6 Heard S, Beale T. Archetype Definitions and Principles. See http://www.openehr.org/reposi tories/spec-dev/latest/publishing/architecture/archetypes/princi ples/REV_HIST.html.

7 Heard S, Beale T. The openEHR Archetype System. See http://www.openehr.org/reposito- ries/spec-dev/latest/publishing/architecture/archetypes/system/REV_HIST.ht ml .

8 Hein J L. Discrete Structures, Logic and Computability (2nd Ed). Jones and Bartlett 2002. 9 Kilov H, Ross J. Information Modelling: an Object-Oriented Approach. Prentice Hall 1994. 10 Gruber T R. Toward Principles for the Design of Ontologies Used for Knowledge Sharing. in Formal

Ontology in Conceptual Analysis and Knowledge Representation. Eds Guarino N, Poli R. Kluwer Academic Publishers. 1993 (Aug revision).

11 Martin P. Translations between UML, OWL, KIF and the WebKB-2 languages (For-Taxonomy, Frame-CG, Formalized English). May/June 2003. Available at http://meganesia.int.gu.edu.au/~ph martin/WebKB/doc/model/comparisons.html as at Aug 2004.

12 Meyer B. Eiffel the Language (2nd Ed). Prentice Hall, 1992.

13 Patel-Schneider P, Horrocks I, Hayes P. OWL Web Ontology Language Semantics and Abstract Syntax. See http://w3c.org/TR/owl-semantics/ .

14 Smith G. The Object Z Specification Language. Kluwer Academic Publishers 2000. See http://www.itee.uq.edu.au/~smith/objectz.html.

15 Sowa J F. Knowledge Representation: Logical, philosophical and Computational Foundations. 2000, Brooks/Cole, California.

Resources

16 HL7 v3 RIM. See http://www.hl7.org . 17 openEHR. EHR Reference Model. See http://svn.openehr.org/specifica

tion/TRUNK/project_page.htm.

18 Perl Regular Expressions. See http://www.perldoc.com/perl5.6/pod/perlre.html.

19 SynEx project, UCL. http://www.chime.ucl.ac.uk/HealthI/SynEx/.

20 W3C. OWL - the Web Ontology Language.

See http://www.w3.org/TR/2003/CR-owl-ref-20030818/ . 21 W3C. XML Path Language. See http://w3c.org/TR/xpath .

Editors:{T Beale, S Heard} Page 45 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2

Rev 2.1.0

Date of Issue: 03 Mar 2007 Page 46 of 47 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 2

Rev 2.1.0

END OF DOCUMENT

Editors:{T Beale, S Heard} Page 47 of 47 Date of Issue: 03 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org