ADL - Archetype Definition Language

ADL has a small number of keywords which are reserved for use in archetype declarations, as follows:

All of these words can safely appear as identifiers in the definition and terminology sections.

Deprecated keywords include:

The first word in a source ADL archetype declares the artefact type, and is one of the following keywords:

The flattened form of any of the above types starts with the keyword 'flat' followed by the artefact type.

A fourth artefact type is also possible.

In the definition section of an ADL archetype, a specific set of codes is used as node identifiers. Identifier codes always appear in brackets ([] ), and begin with the 'id' prefix. Specialisations of locally coded concepts have the same root, followed by 'dot' extensions, e.g. [id10.2] . From a terminology point of view, these codes have no implied semantics - the 'dot' structuring is used as an optimisation on node identification.

In the definition section of an ADL archetype, a second set of codes is used for terms denoting constraints on coded items. Term 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 ([]) and are prefixed with "at", e.g. at10 . Codes of any length are acceptable in ADL archetypes. Specialisations of locally coded concepts have the same root, followed by 'dot' extensions, e.g. at10.2 . From a terminology point of view, these codes have no implied semantics - the 'dot' structuring is used as an optimisation on node identification.

A third kind of local code is used to stand for value set constraints on coded text items in the body of the archetype. Because they are language- and/or terminology-sensitive, they are defined in the terminology section, and referenced by codes prefixed by "ac", e.g. [ac9].

An ADL version identifier is mandatory in all archetypes, and is expressed as a string of the form adl_version=N.M , or N.M.P, where N.M[.P] is the ADL release identifier.

An RM (Reference Model) Release identifier is mandatory in all archetypes, and is expressed as a string of the form rm_release=N.M, or N.M.P, where the version number indicates the release of the reference model on which the archetype is based.

A unique identifier for the archetype in the form of a GUID can be specified using the syntax below:

This identifier is set at initial creation or at any time later, and never subsequently changes. It acts as an identifier for the physical artefact, regardless of what semantics are changed, including changes to the constituent parts of the multi-axial identifier.

A build_uid identifier can also be specified, with a GUID value, identifying the current artefact. This identifier changes whenever any change is made to the text of the archetype, and can thus be used to disambiguate subsequent versions.

A namespaced archetype has an identification section like the following examples:

Namespaces are used to distinguish locally created artefacts representing a given concept (such as 'haematology result') from an artefact created elsewhere intended to represent the same concept.

Once a namespace is attached to an archetype, it is considered a part of the identifier, and never changed, even if the archetype moves to a new publishing organisation. This ensures the constant relationship between archetypes and the data created using them.

The archetype identifier may include a namespace, in the form of a reverse domain name, which denotes the original authoring organisation. The lack of a namespace in the identifier indicates an ad hoc, uncontrolled artefact, not formally associated with any organisation, typical for experimental archetypes, and pre-ADL 1.5 archetypes not yet upgraded to have a namespace. The main part of the identifier is multi-axial concept identifier.

A typical identification sectionfor an ad hoc archetype is as follows:

The multi-axial archetype identifier identifies archetypes in a global concept space within a given namespace. It is also known as an 'ontological' identifier, since the concept space can be understood as an ontology of informational concepts on which the archetypes are based. The syntax of the identifier is described in the openEHR Identification Specification. The structure of the concept space is essentially two-level, with the first level being a reference model class (e.g. openEHR OBSERVATION class) and the second being a domain concept (e.g. 'haematology result').

Because namespaces are usually treated hierarchically, higher level namespaces (e.g. '.org' domains) are assumed to be includable by more local namespaces, with the result that the concept definition space is inherited as well.

The archetype identifier of any specialised archetype, including all templates, follows the same rules as for non-specialised archetypes.

ADL 2 Archetypes contain 3-part version identifiers, with optional qualifiers, following the openEHR Artefact Knowledge Identification specification. Examples below:

The version identifier variants are summarised as follows:

The following syntax validity rule applies in the identification section:

A flag indicating whether the archetype was generated or authored can be included after the version, as follows:

This marker is used to support the migration to differential archetype representation introduced in ADL 1.5, to enable proper representation of specialised archetypes. The 'generated' marker can be used on specialised archetypes - i.e. ADL 1.5 style .adls files - generated from flat archetypes - ADL 1.4 .adl files - and also in flat archetypes generated from differential files, by an inheritance-flattening process.

A flag indicating whether the archetype is change-controlled or not can be included after the version, as follows:

This flag may have the two values "controlled" and "uncontrolled" only, and is an aid to software. Archetypes that include the "controlled" flag should have the revision history section included, while those with the "uncontrolled" flag, or no flag at all, may omit the revision history. This enables archetypes to be privately edited in an early development phase without generating large revision histories of little or no value.

A 'concept' section was required up until ADL 1.4. In ADL 1.5, the concept section is deprecated, but allowed, enabling ADL 1.4 archetypes to be treated as valid. It will be removed in a future version of ADL, since it is completely redundant.

All archetypes represent some real world concept, such as a "patient", a "blood pressure", or an "ante-natal examination". The concept is always coded, ensuring that it can be displayed in any language the archetype has been translated to. A typical concept section is as follows:

In this concept definition, the term definition of [at0000] is the proper description corresponding to the "haematology-cbc" section of the archetype identifier above.

The following syntax validity rule applies to the concept section, if present, allowing parsers to correctly ignore it:

All archetype object constraint nodes require a node identifier. When data are created according to the definition section of an archetype, the archetype node identifiers can be 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").

In the above, the node identifier [id1] is assigned a meaning such as "clinical problem" in the archetype terminology section. The subsequent lines express a constraint on the runtime name attribute, using the internal code [ac1] . The constraint [ac1] is also defined in the archetype terminology 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, 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].

Semantically, an assertion 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 within an assertion.

A reference to an object in data, including a leaf value, is expressed using an archetype path. All such paths are absolute (i.e. contain a leading '/') and are understood to be with respect to the root of the current archetype.

Types of assertions used in archetypes include:

Each of these is described below.

The rules section may also include computational statements that can be used to compute values for specific fields, generally based on some published algorithm, rather than just asserting a relationship between various fields. The following shows a set of statements similar to the example above, but with the field bound to $mean_arterial_pressure now having its value set, not just tested. The assignment operator (:=) is used to achieve this.

One of the basic characteristics of any underlying information model which may be archetyped is that its class attributes are already named, typically in English, if the model is internationally shared or standardised. Archetyping solves effective renaming and language-independence of object nodes, via the mechanism of id-codes, but attribute names are by default unchangeable and mono-lingual. Experience in archetype-based modelling has shown that renaming of RM attributes within the context of an archetype is a common need, usually because the attribute name chosen in the original model is not sufficiently specific for some users of a particular archetype. An example is the openEHR class COMPOSITION, which has an attribute composer. For particular archetypes corresponding to specific sub-domains in healthcare, or specific geographies, a preferable name may be author; additionally, any such name (even the original) may be needed in multiple languages.

In ADL, re-labelling of RM attributes is called aliasing, and is achieved by mentioning an RM attribute path in the archetype and associating an alias with it, in the form of an at-code, defined according to the usual rules of specialisation. Aliasing may apply to any valid RM path in the archetype, i.e. any path through RM objects referenced in the archetype. If archetype-specific nodes are referenced in a path, the settings relate to those paths only in the data, but if not, the settings relate to any matching RM path through the data.

A second need, related to the above, is that archetype modellers sometimes need to know what elements are already in an information model, so they don’t try to remodel them again as redundant object nodes. In a simple implementation of an archetype authoring tool, attributes not so far archetyped will be all hidden, perhaps with a possibility of showing them all. However, commonly, finer-grained control is needed whereby particular attributes, possibly only on particular object nodes need to be made visible in a modelling tool, in order to indicate they need not be modelled.

For this reason a 'show' marker can be associated with the path of an non-constrained RM attribute, causing it to be made visible in a modelling tool. Taking into account archetype and template specialisation, it should also be possible to add a 'hide' marker, in order to hide an attribute marked as 'show' in a specialisation parent. It has also been found by experience that sometimes a constrained RM attribute from a parent archetype needs to be hidden in a specialisation child. Thus, the general case is that 'hide' and 'show' markers can be associated with any RM attribute path (constrained or unconstrained) in the archetype.

Since both of these needs relate to the visibility of RM attributes in an archetype, and are specfied in terms of RM attribute paths, an rm_overlay sub-section called rm_visibility is used to specify them. The following example illustrates the use of this section to force visibility and aliasing of one attribute, and hiding of another attribute within an archetype.

This section describes the syntax of the terminology section of an archetype. The following section, [Terminology Integration] describes the semantics.

The terminology section of an archetype is expressed in ODIN, and is where codes representing node identifiers, constraints on coded term values, 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 general layout of this section.

The term_definitions section is mandatory, and must contain definitions for all terms requiring them, in all translations in use in the archetype. Terms requiring definitions include:

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 must at least include the names "text" and "description", which correspond 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.

In some cases, term definitions may have been lifted from existing terminologies (only a safe thing to do if the definitions exactly match the need in the archetype). To indicate where definitions come from, a "provenance" tag can be used, as follows:

Note that this does not indicate a binding to any term, only the origin of its definition. Bindings are described below.

The term_definitions section also includes definitions for archetype-local constraint codes, which are of the form [acN] in the definition part of an archetype. Each such code refers to a terminology 'value set', i.e. a set of possible terms that could be used as the value of the data item being constrained. These constraints are defined in two parts. First, the ac code itself is defined - this names the value set. For example:

The second part is the value set contents. This can be defined either as an 'internal' value set consisting of at-codes, or else as being a value set defined in an external terminology and referenced via a binding. An internal value set is defined using an entry in the value_sets sub-section for the ac code, containing a list of at-code member values. Each of those members must have its own definition in the term_definitions section. The following shows the structures required.

A value set and/or its constituent terms may also have 'bindings' to externally defined terms and values sets. Object node id-codes may also have bindings, establishing external codings for the names of elements in an archetype. Binding is achieved in the term_bindings sub-section. Bindings are grouped under the target terminology they relate to, and each one consists of a key and a target. There are variations of each.

Keys can be any one of:

Binding targets are expressed as URIs that follow the model for terminology URIs published by IHTSDO [IHTSDO_URIs] or a similar model, in the case of terminologies other than SNOMED CT. Because URIs are native types in ADL/ODIN, they do not need quotes.

Bindings may be defined for a given set of terms for more than one terminology, enabling the different bindings to be used in different contexts, e.g. hospital deployment versus aged care.

The following is an extract from a test archetype based on the openEHR Apgar archetype, showing the different types of bindings:

The reason for code and path keys for id-codes is to enable two types of id-code bindings. A binding to a simple code such as id26|Total|, above, means that the bound term (referred to by the URI http://snomedct.info/id/249228009) has a context-independent correlation to the id-code. However, a 'pre-coordinated' code such as SNOMED CT 169895004|Apgar score at 1 minute| cannot be bound just to id26|Total|, but rather to the node representing the 1-minute total, i.e. at the path /data[id3]/events[id4|1 minute|]/data[id2]/items[id26]. Such paths can be considered as equivalent to a 'post-coordinated' code, and thus the binding establishes a correspondence between an internal post-coordination and an external pre-coordinated code.

In the example shown below, the id4 code identifies a 'temperature' node in an archetype, and the codes id3, id5, id6 etc correspond to various times such as 'any', '1-hour average', '1-hour maximum' and so on. Some terminologies (notably LOINC, the laboratory terminology in this example) define pre-coordinated codes, such as '1 hour body temperature'; these clearly correspond not to single codes such as id4 in the archetype, but to whole paths.

Bindings to external value sets are also included in the bindings section, also as URIs:

In this example, each local constraint code is formally defined to refer to a value set whose identifier is known in the SNOMED CT terminology.

The next section describes the semantics of term constraining, value sets and binding in some detail.