Overview

The sections below describe all the changes to ADL/AOM 1.4 to support more powerful archetyping and also templating defined in ADL 2. In this design approach, the operational template is the key formal artefact for information systems and data, since it is the joining point between specification and all downstream computable forms of archetypes. The latter include template-based schemas for messages; template-based data objects for programmatically creating templated data, and any documentary form of a template.

Key specifications:

ADL 2 : the updated Archetype Definition Language, now including specialisation, external references, slot filling
AOM 2 : the updated Archetype Object Model, including specialisation & slot filling semantics, validity conditions, and improvements to ontology and primitive types packages
Knowledge Artefact Identification specification: rules and semantics of archetype and template identifiers and references
Template Specification: a description of how ADL and AOM are used to create templates; description of the Template Object Model defining operational templates (OPTs).
Common Information Model : the resource package describes some of the generic semantics of any resource, including documents and archetypes. Some of the capabilities used by archetypes such as translation meta-data and annotations are defined here.

Archetype Object Model in pictures (UML)

The AOM as it now stands consists of the following key parts:

The ARCHETYPE (root) class	The main constraint model	The primitive constraint types	The tuple part of the model

Summary of Changes

The following table lists ADL/AOM 2 changes and additions to the ADL/AOM 1.4 version of the formalism, with items not yet completely specified and/or implemented indicated at the bottom.

Item	Description	Practical significance
ADDED: ARCHETYPE.artefact_type TODO: this will probably be converted to a function and replaced by is_template and is_overlay flags.	A new attribute has been added to the ARCHETYPE class to enable various instantiations of the AOM to be designated as having different design intention - 'archetype', 'template', 'template-component', 'operational template'.	Allows ADL/AOM being used for archetypes, and various forms of templates
ADDED: path-based constraints for specialised archetypes	All specialised archetypes and templates state their constraints in a 'differential form' as follows: EVALUATION[at0000.1] ∈ { -- Diagnosis /data/items[at0002.1]/value ∈ DV_CODED_TEXT ∈ {...} } }	All specialised archetypes and templates will now be properly maintainable by tools, compared to the current situation where specialised archetypes contain copies of elements from the parent artefact/
ADDED: 'before' and 'after' keywords for item ordering in containers	The 'before' and 'after' keywords can be used to specify the ordering of elements added to a container in a specialised archetype or template.	Ensures authors can maintain ordering of all items within container attributes, including over specialisation.
ADDED: 'generated' marker	Used to indicate that the artefact was generated by software, rather than authored by hand. This flag will probably not be needed in future, since legacy archetypes will now have the .adl extension, whereas source archetypes will be .adls and generated flat-form archetypes are .adlf.	Can be used to mark an artefact as generated by software.
ADDED: negation operator to express exclusions	In specialised archetypes and templates particularly, unneeded elements from the parent artefact can now be logically be removed using the !matches operator. This is in addition to setting occurrences matches {0}, which is the more common form.	Provides a way to remove terms from value-sets in specialised archetypes and templates.
ADDED: C_ARCHETYPE_ROOT class	This new class allows an archetype to refer to another archetype, without having to use an archetype slot. Also used to perform slot-filling in templates.	Supports archetype refactoring and reuse, as well as template slot-filling.
ADDED: annotations section	Annotations can now be added on a per-node basis, with each annotation having one or more facets (representation = Hash<T>). Annotations can be associated with archetype or pure RM paths. The latter allows archetype and template designers to describe the specific use of a RM element that is not mentioned in the archetype. To achieve this, annotations can be associated with an RM path (of which an archetype path is just a special case).	Supports fine-grained documentation of elements of archetypes and templates, as well as the intended use of non-archetype RM elements in the context of that particular archetype or template.
ADDED: slot redefinition semantics, including slot-filling	The semantics of redefining archetype slots in specialised archetypes and templates is now stated; slot-filling is regarded as a part of redefinition. This allows templates to be formally considered as being the same as specialised archetypes.	Templates can now be represented using the AOM/ADL formalism rather than a separate formalism.
ADDED: default values	The AOM now allows default values to be included on any node.	Supports default value setting in templates.
ADDED: pass_through node flag TODO: probably move this to its own section like annotations; see tech list discussions	The AOM now includes a 'pass_through' flag on C_COMPLEX_OBJECT indicating that this node is not significant in terms of display.	Allows nodes required for structuring data but otherwise redundant for screen display and reporting to be detected by rendering software.
ADDED: reference model subtype matching semantics	Specialised archetypes and templates can now redefine the reference model type of a node, e.g. DV_TEXT into DV_CODED_TEXT.	Allows free text constraints to be changed to coded-only constraints.
ADDED: node congruence & conformance semantics	Rules have now been defined for determining if a node in a specialised artefact is conformant (consistent) or congruent (the same as) a corresponding node in the parent.	Proper validation of specialised archetypes and templates can be implemented.
ADDED: flattening semantics for operational templates	The rules for generating an operational template from source template & archetypes are now defined.	Tools can implement a reliable transform from source artefacts to the operational artefact.
ADDED: tuple construct	Support for second order constraints, described here.	Provides a formalisation for covarying properties, e.g. units & value ranges (such as 0-100 C / 32 - 212 F).
ADDED: group construct	Supports groups within container attributes. Original proposal on this page.
ADDED: Archetype ID namespaces	All controlled archetypes now have their id prefixed with the relevant org namespace.	Prevents clashes between similar /same archetypes created by different organisations.
CHANGED: existence is now optional	Due to reference model checking, the ADL 1.4 semantics of mandatory defaults for existence have been removed; now the reference model is always used to determine the underlying existence of an attribute.	Archetypes and templates now only carry existence if it is different from the reference model.
CHANGED: cardinality constraints are now optional (keyword still required for multiple-valued attributes)	Due to reference model checking, the ADL 1.4 semantics of mandatory defaults for cardinality have been removed; now the reference model is always used to determine the underlying cardinality of an attribute. However, a standalone 'cardinality' marker is still required on container attributes, to support early stage parsing and display, without the aid of a reference model (which might not always be available).	Archetypes and templates now carry the cardinality keyword on container attributes, but only include a constraint if it is different from the reference model.
CHANGED: rules for at-codes	Rules have been stated for when at-codes need to be specialised, according to the changes stated in the specialised artefact.	Editing tools can determine when node ids need to be used in specialised artefacts.
CHANGED: invariants and declarations merged into rules section of archetype	A single 'rules' section is now used to contain invariant and declaration statements, which define constraints over multiple nodes in the artefact. The formalism and model of rules has been substantially improved.	Simplifies overall artefact structure; allows constraints to refer to external entities, such as patient data, time etc.
CHANGED: terminology_extract section added to ONTOLOGY	A terminology_extract sub-section is now included in the ontology section of an archetype, enabling codes & rubrics from terminology to be included. Mostly used for templates.	Templates can directly include small extracts of external terminologies, making them standalone for such value-sets.
CHANGED: C_PRIMITIVE_OBJECT merged with C_PRIMITIVE.	These two classes have been separate, but mostly replicate functionality. Merging them has clarified some leaf level ADL/AOM semantics and simplifed the class model.	Improves AOM comprehensibility, and simplifies tooling slightly, with no impact on semantics.
REMOVED: C_DOMAIN_TYPE, C_DV_QUANTITY, C_DV_ORDINAL, C_CODE_PHRASE	The C_DV_QUANTITY and C_DV_ORDINAL types, and the C_DOMAIN_TYPE mechanism have all been removed, and are replaced by the RM type-independent 'tuple' feature.	Special syntax used in openEHR ADL 1.4 archetypes will be converted to standard ADL 1,5 syntax, which will be interpretable by any ADL/AOM tool.
CHANGED: removed CONSTRAINT_REF;	ref-sets now modelled using primitive type C_TERMINOLOGY_CODE	External ref-sets specified using same meta-class as inline value sets.
CHANGED: node id-code specialisation only required if desired, or when 1:many specialisation occurs	narrowed or zero'd occurrences should not require at-code specialisation, as is currently specified.
TODO: addition of semantic slot type	See this sub-page for a discussion on the advanced semantics of slots, and how it simplifies templates.
OBSOLETE: node ids for C_DV_QUANTITY in ADL	This change has been made obsolete, by the removal of the C_DV_QUANTITY and C_DV_ORDINAL types, and the C_DOMAIN_TYPE mechanism. ADL: currently we cannot put a node-id on a dADL node like a C_DV_QUANTITY, or a special syntax node, like C_DV_ORDINAL or C_CODE_PHRASE. This does not affect the AOM or XML serialised form.
TODO: finalise rules syntax (XPath-based)
CHANGED: node-id mandatory on every node, but term definition only mandatory for C_OBJECTs under container attirbutes.	Currently node_id is specified as mandatory on all nodes. At-codes now replaces with id-codes; rule for mandatory definition in term_definitions is that only node-ids on nodes under container attirbutes are required to have definitions.	Greatly simplifies tooling software and reasoning on archetypes.
TODO: 1 template = 1 file	In the current model, a template consists of a root template and potentially numerous template_components, which are just specialisations of archetypes chosen to fill slots. Even if the template only performs slot-filling but no further constraining, template_components are used to create the hierarchy of archetype slot-flling references.	Easier to handle templates outside of tools, e.g. in email.
TODO: enable specialisation of leaf node just to add 'assumed' value.	Assumed values are likely to be added in local archetypes and templates, to a widely shared archetype. There should be a convenient way to add them to nodes whose value constraints are already defined.
TODO: support for defining functionally derived nodes.
TODO: support for re-ordering existing nodes without otherwise redefining them.	Example: address and name archetypes have parts commonly used around the world, but the item ordering varies according to country. The idea would be to allow a redefinition of the order. If done directly, it would imply the compiler allowing through minimal references to existing nodes in the parent e.g. just TYPE[at-code] within multiply-valued attributes. Otherwise, something could be done with use_nodes.

Detailed Description

Design approach

Specialisation Semantics

Fully defined semantics of specialised archetypes are now available. The summary of what a specialised archetype is:

A non-specialised (i.e. top-level) archetype defines an instance space that is a subset of the space defined by the class in the reference information model on which the archetype is based.
A specialised archetype can specialise only one parent archetype, i.e. single inheritance.
A specialised archetype defines an instance space defining the following elements:
- unchanged object and attribute constraints inherited from the parent archetype;
- and one or more:
  - redefined object constraints, that are proper subsets of the corresponding parent object constraints;
  - redefined attribute constraints, that are proper subsets of the corresponding parent attribute constraints;
  - extensions, i.e. object constraints added to a container attribute with respect to the corresponding attribute in the parent archetype, but only as allowed by the underlying reference model.
All elements defined in a parent archetype are either inherited unchanged or redefined in a specialised child.
Specialised archetypes are expressed differentially with respect to the parent, i.e. they do not mention purely inherited elements, only redefinitions and extensions.
Redefinition cannot remove an object constraint; only narrow it to a reduced instance space.
Extensions always define an additional subset of the instance space defined by the reference model element being extended (i.e. to which the 'new' objects belong). The extension capability allows archetypes to remain extensible without having to know in advance how or if they will be extended.

Source, flat and operational forms of archetypes supported

Specialised archetypes in their authored form are represented in 'differential' form. The syntax is the same as for non-specialised archetypes, with two additions: specialisation paths and ordering indicators (both described below). For a specialised archetype therefore, the lineage of archetypes back to the ultimate parent must be taken into account in order to obtain its complete semantics.

Differential form means that the only attributes or objects mentioned are those that redefine corresponding elements in the parent and those that introduce new elements. The differential approach to representation of specialised archetypes give rise to the need for a flat form of a specialised archetype: the equivalent archetype defined by the sum of the (differential) child and its parent, as if the child archetype had been defined standalone. The flat form of archetypes is used for building templates, and subsequently at runtime. It is generated by 'compressing' the effects of inheritance of the parent to the specialised child into a single archetype, and applies recursively all the way up an archetype lineage to the ultimate parent, which must be a top-level (non-specialised) archetype. For a top-level archetype, the flat-form is the same as its differential form (i.e. in a top-level archetype, every node is considered to be an extension node).

What has been added?

The following features have been added to ADL and/or the AOM.

Artefact type flags in ARCHETYPE class

New flags have been added to ARCHETYPE: is_template and is_overlay. Coupled with the various subtypes of ARCHETYPE, every possible source and generated type now has a mapping, as follows:

source archetype (differential) => DIFFERENTIAL_ARCHETYPE
source template (differential, top-level) => DIFFERENTIAL_ARCHETYPE; is_template = True
source template overlay (differential, private component) => DIFFERENTIAL_ARCHETYPE; is_template = True; is_overlay = True
flat archetype => FLAT_ARCHETYPE
flat template => FLAT_ARCHETYPE; is_template = True
operational template => OPERATIONAL_TEMPLATE; is_template = True
RETAIN? A new function has been added to the ARCHETYPE class to enable various instantiations of the AOM to be designated as having different design intentions:
archetype - a reusable model of a domain concept based on a reference model
template - a localised or specialised model that aggregates and chooses elements of archetypes to create a data set
template_overlay- a sub-part of a template, expressed as a specialised archetype
operational_template - a generated, flattened operational form of a template & constituent archetypes that is suitable for runtime use, and/or further artefact generation, including message schemas.
This attribute is used by tools to distinguish these different artefacts, even though they are all expressed using the one formalism, i.e. the AOM, or a serialisation of it. See below for details on how templates are supported.

Path-based constraints for specialised archetypes

The ability to state a path, known as a 'differential path', rather than just an attribute, allowing redefinition blocks deep in the structure to be stated with respect to a path rather than having to be nested within numerous containing blocks on which no redefinition occurs.

Example in ADL 1.5:

EVALUATION[at0000.1] ∈ {	-- Diagnosis
  	/data/items[at0002.1]/value ∈ {
  		DV_CODED_TEXT ∈ {
  			defining_code ∈ {[ac0.1]}		-- Any term that 'is_a' diagnosis
  		}
  	}
  	/data/items cardinality ∈ {0..*; ordered} ∈ {
  		ELEMENT[at0.32] occurrences ∈ {0..1} ∈ {	-- Status
  			value ∈ {...}
  		}
        }

}

Archetype Object Model:

These paths are modelled in the AOM constraint_model
package as shown below.

Before and after keywords for ordering items in specialised archetypes

Within container attributes, the order of objects may be significant from the point of view of domain users, i.e. the container may be considered as an ordered list. This is easy to achieve in top-level archetype, using the 'ordered' qualifier on a cardinality constraint. However when particular node(s) are redefined into multiple specialised nodes, or new nodes added by extension, the desired order of the new nodes may be such that they should occur interspersed at particular locations among nodes defined in the parent archetype. In the following example, the ordering of the ELEMENT and CLUSTER nodes introduced in this specialised archetype is specified by 'before' and 'after' clauses.

ADL 1.5 example:

EVALUATION[at0000.1] ∈ {	-- Diagnosis
    /data/items cardinality ∈ {0..*; ordered} ∈ {
        before [at0003]
  	ELEMENT[at0.32] occurrences ∈ {0..1} ∈ {...}	   -- Status
  	after [at0031]
  	CLUSTER[at0.35] occurrences ∈ {0..1} ∈ {...}	-- Diagnostic criteria    }}

Archetype Object Model:
The ordering modifiers on C_OBJECTs
are modelled in the AOM constraint_model package
as C_OBJECT.sibling_order.

Optional 'generated' marker in the archetype first line

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

archetype (adl_version=1.4; generated)
    openEHR-EHR-ENTRY.haematology.v1

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.

Use of Negation operator to define value set exclusions in specialised archetypes

To remove values:

Parent archetype:

ELEMENT[at0007] occurrences ∈ {0..*} ∈ {	-- System
	name ∈ {
		DV_CODED_TEXT ∈ {
			defining_code∈ {
				[local::
				at0008, 	-- Cardiovascular system
				at0009, 	-- Respiratory system
				at0010, 	-- Gastro-intestinal system
				at0011, 	-- Reticulo-Endothelial system
				at0012, 	-- Genito-urinary system
				at0013, 	-- Endocrine System
				at0014, 	-- Central nervous system
				at0015]	 -- Musculoskeletal system
			}
		}
	}
}

Specialised archetype:

.../name/defining_code ∉ { -- ~matches in text form
	[local::
	at0012, 	-- Genito-urinary system
	at0013] 	-- Endocrine System
}

Use of 0 occurrences to remove types from parent archetype:

ELEMENT[at0003] ∈ {
	value ∈ {
		DV_QUANTITY ∈ *
		DV_INTERVAL<DV_QUANTITY> ∈ *
                DV_COUNT ∈ *
		DV_INTERVAL<DV_COUNT> ∈ *
	}
}

 
The intention is to remove the DV_INTERVAL<*> alternatives. This
is achieved by redefining the enclosing object to remove the relevant types:

ELEMENT[at0003.1] ∈ {
	value ∈ {
		DV_INTERVAL<DV_QUANTITY> occurrences ∈ {0}
                DV_INTERVAL<DV_COUNT> occurrences ∈ {0}
        }
}

To remove subtype possibilities allowed by the RM; The following example matches any PARTY instance with the exception of instances of COMPANY or GROUP subtypes. Achieved by setting occurrences to {0} or using negation operator?

 counter_party ∈ {
	PARTY ∈ { ... }
	COMPANY occurrences ∈ {0}
	GROUP occurrences ∈ {0}
}

Match negation is modelled in the AOM constraint_model package as C_ATTRIBUTE.match_negated (red box #2).

Direct archetype reference

In ADL/AOM 1.4, the only way to join an archetype to another was with a slot. However, experience has shown that refactoring of archetypes to extract a shared lower level archetypes often means that there are multiple archetypes that need to reference just one other archetype. This can now be done by a direct reference, using the new C_ARCHETYPE_ROOT class. This class is the same as a C_COMPLEX_OBJECT but instead of carrying an at-code identifier, it carries an archetype id. It is also used in templates to fill slots, and is the archetype root point node type in operational templates. The following diagram illustrates.

Optional annotations section added

This feature enables specific annotation text items to be added to individual nodes in the archetype definition. Each annotation is keyed by path, and consists of a list of one or more meta-data items, each keyed by a unique string, typically 'purpose'. The representation in serialised formats such as ADL and XML will be a block list at (or near) the end of the archetype, rather than annotations interpolated throughout the definition section. This allows the annotations to be easily removed or re-processed. For example, annotations might be used during the archetype design phase, but maybe be pared down to a final minimal set or even removed at publishing time. This can more easily be done with such a representation.

During the work with the UK NHS CfH project, it became clear that this feature was desirable both for templates and archetypes. It has therefore been added to the Common authored_resource package, from which both archetype and template structures inherit.

 annotations
	annotations = <
		["/data/items[at0.37]/items[at0.38]/value"] = < -- Clin st. / Stage
			items = <
				["message requirement"] = <"staging field in msg type 2345">
				["guideline"] = <"http://guidelines.org/gl24.html#staging">
				["data dict equivalent"] = <"NHS data item aaa.1">
			>
		>
		["/data/items[at0.37]/items[at0.39]/value"] = < -- Clin st. / Tumour
			items = <
				["message requirement"] = <"tumour field in msg type 2345">
				["guideline"] = <"http://guidelines.org/gl24.html#mass">
				["data dict equivalent"] = <"NHS data item aaa.2">
			>
		>
	>

This addition is made in the reference model to the AUTHORED_RESOURCE class, as the new class ANNOTATION. See below (item #1 indicated in red).

Slot redefinition

The key addition to the AOM formalism to support templates is the ability to specialise a slot with 'fillers', i.e. archetypes or other templates that will be used at the slot point, for a particular purpose. A slot within an archetype can be specialised by any combination of the following:

one or more slot-fillers;
a redefinition of the slot itself, either to narrow the set of archetypes it matches, or to close it to filling in either further specialisations, or at runtime.

Both types of redefinition are generally used by templates rather than published archetypes, since the business of filling slots is mostly related to local use-case specific uses of archetypes rather than part of the initial design.
The following example shows a slot from a SECTION archetype for the concept 'history_medical_surgical' archetype.

SECTION[at0001] ∈ {    -- Past history
    items ∈ {
        allow_archetype EVALUATION [at0002] ∈ {    -- Past problems
            include
                archetype_id/value matches {
                    /openEHR-EHR-EVALUATION\.clinical_synopsis\.v1
                        |openEHR-EHR-EVALUATION\.excluded(-[a-z0-9_]+)*\.v1
                        |openEHR-EHR-EVALUATION\.injury\.v1
                        |openEHR-EHR-EVALUATION\.problem(-[a-z0-9_]+)*\.v1/}
            exclude
                archetype_id/value ∈ {/.*/}
        }
    }
}

This slot specification allows EVALUATION archetypes for the concepts 'clinical synopsis', various kinds of 'exclusions' and 'problems', and 'injury' to be used, and no others. The following fragment of ADL shows how the slot is filled in a template, using the keywords use_archetype and use_template. In this syntax, the node identification is a variation on the normal archetype at-codes. Within the template, the identifier of the used archetype is also the identifier of that node. However, the original at-code (if defined) must also be mentioned, so as to indicate which slot the used archetype is filling. Templates may also be used to fill slots in the same way. Thus, in the following example, two archetypes and a template are designated to fill the at0002 slot defined in the above fragment of ADL.

use_archetype SECTION[openEHR-EHR-SECTION.history_medical_surgical.v1] ∈ {
    /items ∈ {
        use_archetype EVALUATION[at0002, org.openehr::openEHR-EHR-EVALUATION.problem.v1]
        use_template EVALUATION[at0002, uk.nhs.cfh::openEHR-EHR-EVALUATION.t_ed_diagnosis.v1]
        use_archetype EVALUATION[at0002, org.openehr::openEHR-EHR-EVALUATION.clin_synopsis.v1]
    }
}

Since node identifiers are only required to disambiguate multiple sibling nodes, they may not exist on all nodes in a typical archetype. It is therefore possible to have a slot that carries no node identifier (e.g. due to being under a single-valued attribute); a use_archetype specification within a template will accordingly only mention the archetype identifier, with no node id, as per the following example (archetype followed by a template).

INSTRUCTION[at0000] matches {    -- Medication order
    activities matches {
        ACTIVITY[at0001] ∈ {    -- Medication activity
            description ∈ {
                allow_archetype ITEM_TREE ∈ {
                    include
                        archetype_id/value ∈ {...}
                }
            }
        }
    }
}

A template containing a filler for this slot would be as follows:

use_archetype INSTRUCTION[openEHR-EHR-INSTRUCTION.medication.v1] ∈ {
    /activities[at0001]/description ∈ {
        use_archetype ITEM_TREE[org.openehr::openEHR-EHR-ITEM_TREE.medication.v1]
    }
}

Slots can be recursively filled in the above fashion, according to the possibilities offered by the chosen archetypes or templates. The following ADL fragment shows two levels of slot-filling:

use_archetype COMPOSITION[openEHR-EHR-COMPOSITION.xxx.v1] ∈ {
    /content ∈ {
        use_archetype SECTION[at0001,org.openehr::openEHR-EHR-SECTION.yyy.v1] ∈ {
            /items ∈ {
                use_template EVALUATION[at0002,uk.nhs.cfh::openEHR-EHR-EVALUATION.t_xx.v1]
                use_archetype EVALUATION[at0002,org.openehr::openEHR-EHR-EVALUATION.xx.v1]
                use_archetype EVALUATION[at0003,org.openehr::openEHR-EHR-EVALUATION.xx.v1]
            }
        }
    }
}

Note that in the above the archetype fillers are specified as published archetypes, but in reality, it is far more likely that template-specific specialisations of these archetypes would be used. The identification and organisation of such archetypes is described in the openEHR Templates document.In addition to or instead of specifying slot fillers, it is possible in a slot specialisation to narrow the slot definition, or to close it. If fillers are specified, closing the slot as well is typical. This is done by including an overridden version of the archetype slot object itself, with the 'closed' constraint set, as in the following example:

use_archetype SECTION[org.openehr::openEHR-EHR-SECTION.history_medical_surgical.v1] ∈ {
    /items ∈ {
        use_archetype EVALUATION[at0002 = openEHR-EHR-EVALUATION.problem.v1]
        allow_archetype EVALUATION[at0002] closed
    }
}

Narrowing the slot is done with a replacement allow_archetype statement containing a narrowed set of match criteria.

Default values

Templates can define default values for object nodes in archetypes, typically leaf and near-leaf nodes. This capability is available via a new default_value attribute on the C_DEFINED_OBJECT class, shown in the following figure.

Pass_through node setting

In some templates, there is a parent node which groups child nodes, but which does not add any meaning in the structure as displayed or presented in any way. The pass_through attribute can now be set on any C_DEFINED_OBJECT to indicate that the node can be omitted from display, reporting or other similar human-viewing situations.

UPDATE (Feb 2012) - we will probably replace this by a 'soft' setting in a new section called 'implementation_directives' or 'operational_instructions' or similar, as per recent list discussions.

Conformance and congruence functions formally define specialisation relationships

The node_conforms_to() and node_congruent_to() functions in C_OBJECT and C_ATTRIBUTE have been added to formally define specialisation relationship. They replace the old subset() function defined in AOM 1.4.

Tuple Construct

See here for the original proposal. This has now been successfully implemented (Aug 2013). The class model is as follows:

An example Archetype structure using this:

Group Construct

See this sub-page for original proposal. STILL IN DESIGN (Aug 2013).

What has changed?

Existence and cardinality constraints are optional

This change, although seemingly innocuous, probably has the most impact on current tooling and archetypes. The idea is that both existence and cardinality constraints on the C_ATTRIBUTE class should become optional, rather than being mandatory, as they are in ADL/AOM 1.4. In the past, they were mandatory because archetype parsing was assumed to occur with no access to a formal reference model description, and clearly the existence and cardinality had to be stated somewhere. This is clearly not ideal, since it makes more sense only to have to state these constraints where they differ (i.e. are narrower) from those built into the reference model. The most common example is needing to make an RM existence of 0..1 (optional) into 1..1 (mandatory). More recently, reference model 'checking' has become available in both the reference parser and the Java tools, meaning that it is now possible to remove useless cardinality and existence constraints from archetypes.

Impact on existing archetypes:

Currently, existence is not shown in ADL archetypes if it happens to be the same as the default, which in ADL 1.4 was set to 1..1. This has the benign effect that most of the time, existence is not set at all by the editing tools, and the default of 1..1 is irrelevant - i.e. archetypes can now be parsed so that unstated existence is assumed to mean 'use the RM existence defined for this attribute', rather than use the arbitrary existence 1..1;
In cases where existence has been set to 0..1 (the widest possible existence constraint), ADL parsers should now assume that the intention was to follow the reference model - an existence of 0..1 should therefore be removed (even if the RM is narrower on this attribute);
Cardinality is currently set on all container attributes in ADL 1.4 archetypes, since there is no other way of knowing for sure if the attribute is in fact a container, rather than a single-attribute with multiple alternatives. Usually it has been set to 0..*, even where the reference model has 1..* (e.g. CLUSTER.items). Now, the cardinality keyword can be used on its own simply to indicate a container attribute, with no further constraint if none is needed. ADL 1.5 parsers should change their behaviour to a) look for a standalone cardinality constraint, so as to know when a container attribute has been found and b) to remove cardinality statements of 0..* wherever they occur, on the basis that this is the widest possible cardinality, and is therefore intended to follow the reference model (even when the RM constraint is narrower, like in the CLUSTER situation).
For other cardinality constraints, e.g. 0..4, 0..8 etc., a new cardinality constraint should be constructed by ADL parsers to fit inside the RM (which might state 1..*), meaning that 0..4 on CLUSTER.items would become 1..4.

Impact on existing ADL parsers/compilers:

Eiffel reference compiler:
- this still assumes that existence and cardinality are stated on every attribute at least within top-level archetypes (i.e. it would allow specialised ones to not state it, on the assumption that inheritance flattening can be used to find out what the existence and cardinality must be). This can be changed by using the RM in pass 1 parsing, to discover which attributes are container attributes, and constructing the AOM objects in the right way.
- the changes in parsing described above would have to be implemented;
- Validation would also have to be changed to perform inheritance flattening all the way through to the reference model.
Java ADL parser:
- TBD

Impact on existing openEHR EHR implementations:

There will clearly be some impact on existing implementations, including the Java and Python implementations, as well as the commercial implementations.

Semantics of reference model subtype matching are now described

Previously the rules to do with redefinition of types from the reference model in an archetype were unclear. These have now been stated in the new specialisation section of the ADL specification.

The following cADL statement defines an instance space that includes any instance of
any of the concrete subtypes of the PARTY class within an instance of the class XXXX in the figure.

counter_party ∈ {
	PARTY ∈ {... }
}

However, in some circumstances, it may be desirable to define a constraint that will
match a particular subtype in a specific way, while other subtypes are matched by the
more general rule. Under a single-valued attribute, this can be done as follows:

counter_party ∈ {
	PARTY ∈ { ... }
	PERSON ∈ {
		date_of_birth ∈ { ... }
	}
}

This cADL text says that the instance value of the counter_party attribute in the data
can either be a PERSON object matching the PERSON block, with a date_of_birth
matching the given range, or else any other kind of PARTY object.
Under a multiply-valued attribute, the alternative subtypes are included as identified
child members. The following example illustrates a constraint on the counter_parties
attribute of instances of the class YYYY in FIGURE 7.

counter_parties cardinality ∈ * ∈ {
	PERSON[at0004] ∈ {
		date_of_birth ∈ { ... }
	}
	ORGANISATION[at0005] ∈ {
		date_of_registration ∈ { ... }
	}
	PARTY[at0006] ∈ { ... }
}

The above says that ORGANISATION and PERSON instances in the data can only match
the ORGANISATION and PERSON constraints stated above, while an instance any other
subtype of PARTY must match the PARTY constraint.

Rules for when node identifiers (at-codes) are required in archetypes

From ADL 1.5 Section 5.3.11

ADL takes a minimalist approach and does not require node identifiers where sibling object nodes can be otherwise distinguished.
Node identifiers are mandatory in the following cases:

* for an attribute defined as multiply-valued in the underlying information model (i.e. a container type such as a List<T>, Set<T> etc), all immediate child object nodes. This applies even if a  particular archetype only specifies one child object of the attribute;
* for single-valued attributes with more than one child, all immediate child object nodes;
* with the exception of use_node constraints where the node identifier can be inferred from that of the target node.

In all other cases node identifiers are optional.

 
These rules apply to the flattened archetype in all cases, which means that for the second case, node identifiers are needed on all alternative nodes, regardless of which specialisation child introduces them in an inheritance lineage.

Rules described for the construction of node identifier at-codes in specialised archetypes

Redefinition semantics for node identifiers are somewhat special. They can be redefined for purely semantic purposes (e.g. to redefine 'heart rate' to 'fetal heart rate') - this is what happens on the root node of every archetype. However, if any other aspect of the immediate object node, i.e. occurrences, reference model type, or the constraint type is changed, the node identifier must be redefined.

Where an identifier is defined on a node in a parent archetype, redefined versions of the node carry a node identifier that is a specialised version of the identifier of the original. As a consequence, this means that the identifier of the root node of a specialised archetype will always be redefined, indicating the more specific 'type' of instances it defines.

The syntactic form of the identifier of a redefined node is a copy of the original followed by a dot ('.'), optionally intervening instances of the pattern '0.' and then a further non-zero number, i.e.:

atNNNN {.0}* .N

This permits node identifiers from a given level to be redefined not just at the next level, but at multiple levels below.
Examples of redefined node identifiers:

at0001.1 -- redefinition of at0001 at level 1 specialisation
at0001.0.1 -- redefinition of at0001 node in level 2 specialisation archetype
at0001.1.1 -- redefinition of at0001.1 in level 2 specialisation archetype.

Extension nodes carry node identifiers according to the rule mentioned above. The node identifier syntax of an extension node commences with at least one instance of the pattern '0.'. The structure of node identifiers for both kinds of node thus always indicates at what level the identifier was introduced, given by the number of dots.
Examples of redefined node identifiers:

at0.1 -- identifier of extension node introduced at level 1
at0.0.1 -- identifier of extension node introduced at level 2

Declarations and invariants sections merged into 'rules' section

This syntax will most likely move toward the a-path variant of XPath defined by Zilics in their openEHR implementation.

rules

    $diagnosis:CODE_PHRASE ::= /data/items[at0002.1]/value/defining_code
    $date_of_birth:ISO8601_DATE ::= query("patient", "date_of_birth")
    $has_diabetes:Boolean ::= query("patient", "has_diagnosis", "snomed_ct::1234567")
    $is_female:Boolean ::= query("patient", "is_female")
    $age ::= $current_date - $date_of_birth

 
    $is_female and $age > 15 implies exists /some/path/to/data/item/for/women

Validity Rules are now included in the AOM

As of ADL/AOM 1.5, all archetype validity rules are moved to the AOM, making the AOM the primary 'source of truth' on the archetype formalism. The validity statements are interpolated within the class definitions whose semantics they define. Typical rules (from the C_ATTRIBUTE class) are as follows:

VCARM: attribute name reference model validity: an attribute name introducing an attribute constraint block must be defined in the underlying information model as an attribute of the type which introduces the enclosing object block.
VCAEX: archetype attribute reference model existence conformance: the existence of an attribute must conform, i.e. be the same or narrower, to the existence of the corresponding attribute in the underlying information model.
VCAM: archetype attribute reference model multiplicity conformance: the multiplicity, i.e. whether an attribute is multiply- or single-valued, of an attribute must conform to that of the corresponding attribute in the underlying information model.
VSANCE: specialised archetype attribute node existence conformance: the existence of a redefined attribute node in a specialised archetype must conform to the existence of the corresponding node in the flat parent archetype by having an identical range, or a range wholly contained by the latter.
VSAM: specialised archetype attribute multiplicity conformance: the multiplicity, i.e. whether an attribute is multiply- or single-valued, of a redefined attribute must conform to that of the corresponding attribute in the parent archetype.

Each rule has a unique identifier code, and a text description. For archetype parsers and compilers, a form that is likely to be more useful is the 'error' file that converts the rules to error messages, and includes variable items, so that parsers can report errors directly relating to the specification. A dADL-format set of error messages exists already for the reference compiler, and it is proposed to make this a standard resource for Archetype processing of any kind. Naturally, the use of this resource by other parser/compiler authors will help to improve its quality.

Primitive date/time type simplification

Primitive date/time types (C_DATE etc.) have been simplified and made to correspond with Support IM ISO8601 date/time types. See the updated model for the archetype.primitive package.

Validation algorithms added in appendix

TBC

Templates

Overall design

A template is now defined as a root 'template archetype' and one or more template-component archetypes. Both the root and the components are normal archetypes with the artefact_type attribute set to one of the values 'template', 'template-component', or 'archetype' (where completely unmodified archetypes are used).

Node Cloning

The concept of creating a number of more specialised variants of a container attribute child object node within a template is exactly as for any normal archetype. The node in question is redefined by one or more 'clones' whose at-codes are specialisations of the at-code of the original node. The term 'clone' is actually a misnomer, because as soon as any cloning operation is performed, the resultant nodes or subtrees are independent, and can be further specialised separately.

Optionally, the occurrences of the original node may be reduced to{0}, meaning that no occurrences of data matching only the generic node may be created, i.e. all data instances must match one of the specialised nodes. FIGURE 5 illustrates the cloning of the at0013 ('panel item') node from a generic 'lab result' archetype into a number of specific types of children, namely LDL, HDL and total cholesterol. Because node specialisation in templates is performed in the same way as for an archetype, the effect on querying is the same: all cloned (specialised) nodes carry a specialised version of the parent at-code, and will match a query containing the any parent at-code in a path or expression. Thus, a query including the archetype path .../data/events[at0006]/items[at0013] will match the at0013.1, at0013.2 and at0013.3 items above, and if at0013 instances had been allowed, these would be matched as well.

In many cases, a node being 'cloned' is the parent of a further subtree of child attributes and object nodes, at least some of which have their own at-codes. If an entire subtree were cloned by a tool, the only node that must have a redefined node identifier is the root node, i.e. the node which is now replaced by multiple duplicates at under some container attribute. Once the cloning operation is complete, further constraining of each copy can take place independently.

Repeated use of Same Archetype
Another frequent scenario is for the same archetype to be required more than once at the same slot, usually for very generic archetypes that will be specialised in some way each time they are used. At an archetype root point, the node identifier is an archetype identifier, not an at-code, so initially it may not seem clear how multiple copies of the same archetype could be used in a template. In fact, each such copy has to be locally specialised into a t-archetype, which will carry its own redefinitions, at a minimum, for the 'name' attribute in the case of openEHR reference model LOCATABLE descendants.

Conditional nodes

To be continued

Template Computational Artefacts

Template-related artefacts are shown in the figure. The
main thing to be aware of is that an 'openEHR Template'
is an artefact that references archetypes, and adds its
own constraints with respect to each reference, whereas
an Operational Template is the result of evaluating a
Template against the Archetype library to generate a
self-standing artefact which is like a single big archetype.

Operational templates

Overview

The figure to the right illustrates the template package. As can be seen from the model, an operational template has only two differences from a flat archetype definition. The first is that the root object is a C_ARCHETYPE_ROOT rather than a C_COMPLEX_OBJECT, and the second is the addition of the ontology structures from the constituent archetypes. The first difference is due to the fact that in a flattened archetype all archetype root points (including the top one) are replaced by C_ARCHETYPE_ROOT objects, which carry the relevant archetype identifiers.

The second difference is due to the fact that the flattening process usually involves more than one archetype, due to slot filling, meaning that the operational template has to explicitly include the flattened ontologies of all component archetypes in addition to its own ontology (which is that of the template root).

Flattening semantics

use_nodes are expanded out to copies of the referenced nodes
ac_code nodes remain as is, unless there is a terminology binding where we use a subtype of constraint_ref that has a terminology uri.
unneeded languages are stripped
unfilled slots: an ARCHETYPE_SLOT object is retained
filled slots - disappear
ontology includes:
- template codes section
- section for each archetype, indexed by archetype id

Terminology Section

TBC