Evolution from ADL 1.4

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.

EVALUATION[at0000.1] ∈ {	-- Diagnosis
    /data/items[at0002.1]/value ∈
        DV_CODED_TEXT ∈ {...}
    }
 }

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

What has been added?

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

Artefact type flags in ARCHETYPE class

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.

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 ∈ {...}
  		}
        }

}

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.

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    }}

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

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

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

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

Node Cloning

Conditional nodes

To be continued

Template Computational Artefacts

Operational templates

Overview

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