Archetype Object Model 2 (AOM2)

The changes in release 2 of the ADL/AOM formalism are designed to make the formalism more computable with respect to terminology, and enable more rigorous validation and flattening operations.

The changes are as follows.

The changes in release 1.5 are made to better facilitate the representation of specialised archetypes. The key semantic capability for specialised archetypes is to be able to support a differential representation, i.e. to express a specialised archetype only in terms of the changed or new elements in its definition, rather than including a copy of unchanged elements. Doing the latter is clearly unsustainable in terms of change management.

The changes are as follows.

Changes made from Release 1.3 to 1.4:

Various definitional constants are used in the AOM. These are defined in the aom2.definitions package from the AM component and are shown below.

All archetype variants based on ARCHETYPE have a human-readable, structured identifier defined by the ARCHETYPE_HRID class. This identifier places the artefact in a multi-dimensional space based on a namespace, its reference model class and its informational concept. This class defines an atomised representation of the identifier, enabling variant forms to be used as needed. Its various parts can be understood from the following diagram, which also shows the computed semantic_id and physical_id forms.

For specialised archetypes, the parent_archetype_id is also required. This is a string reference to an archetype, and is normally the 'interface' form of the id, i.e. down to the major version only. In some circumstances, it is useful to include the minor and patch version numbers as well.

An important aspect of identification relates to the rules governing when the HRID namespace changes or is retained, with respect to when 'moves' or 'forks' occur. Its value is always the same as one of the original_namespace and custodian_namespace properties inherited from AUTHORED_RESOURCE.description (or both, in the case where they are the same). A full explanation of the identification system and rules is given in the openEHR Archetype Identification specification.

Two machine identifiers are defined for archetypes. The ARCHETYPE.uid attribute defines a machine identifier equivalent to the human readable ARCHETYPE.archetype_id.semantic_id , i.e. ARCHETYPE_HRID up to its major version, and changes whenever the latter does. It is defined as optional but to be practically useful would need to be mandatory for all archetypes within a custodian organisation where this identifier was in use. It could in principle be synthesised at any time for a custodian that decided to implement it.

The ARCHETYPE.build_uid attribute is also optional, and if used, is intended to provide a unique identifier that corresponds to any change in version of the artefact. At a minimum, this means generating a new UUID for each change to:

For every change made to an archetype inside a controlled repository (for example, addition or update of meta-data fields), this field should be updated with a new UUID value, generated in the normal way.

The ARCHETYPE.adl_version attribute in ADL 1.4 was used to indicate the ADL release used in the archetype source file from which the AOM structure was created (the version number comes from the amendment record of the ADL2 specification. In the current and future AOM and ADL specifications, the meaning of this attribute is generalised to mean 'the version of the archetype formalism' in which the current archetype is expressed. For reasons of convenience, the version number is still taken from the ADL specification, but now refers to all archetype-related specifications together, since they are always updated in a synchronised fashion.

The ARCHETYPE.rm_release attribute designates the release of the reference model on which the archetype is based, in the archetype’s current version. This means rm_release can change with new versions of the archetype, where re-versioning includes upgrading the archetype to a later RM release. However, such upgrading still has to obey the basic rule of archetype compatibility: later minor, patch versions and builds cannot create data that is not valid with respect to the prior version.

This should be in the same semver.org 3-part form as the ARCHETYPE_HRID.release_version property, e.g. "1.0.2". This property does not indicate conformance to any particular reference model version(s) other than the named one, since most archetypes can easily conform to more than one. More minimal archetypes are likely to technically conform to more old and future releases than more complex archetypes.

The ARCHETYPE.is_generated flag is used to indicate that an archetype has been machine-generated from another artefact, e.g. an older ADL version (say 1.4), or a non-archetype artefact. If true, it indicates to tools that the current archetype can potentially be overwritten, and that some other artefact is considered the primary source. If manual authoring occurs, this attribute should be set to False.

Governance meta-data is visible primarily in the RESOURCE_DESCRIPTION class, inherited via AUTHORED_RESOURCE, and consists of items relating to management and intellectual property status of the artefact. A typical form of these is shown in the screenshot in Figure 8.

Authorship meta-data consists of items such as author name, contributors, and translator information, and is visualised in the figure below.

Various descriptive meta-data may be provided for an archetype in multiple translations in the RESOURCE_DESCRIPTION_ITEM class, using one instance for each translation language, as shown in the figure below.

The archetype definition is the main definitional part of an archetype and is an instance of a C_COMPLEX_OBJECT . This means that the root of the constraint structure of an archetype always takes the form of a constraint on a non-primitive object type.

The terminology section of an archetype is represented by its own classes, and is what allows archetypes to be natural language- and terminology-neutral. It is described in detail in Section 7.

An archetype may include one or more rules. Rules are statements expressed in a subset of predicate logic, which can be used to state constraints on multiple parts of an object. They are not needed to constrain single attributes or objects (since this can be done with an appropriate C_ATTRIBUTE or C_OBJECT ), but are necessary for constraints referring to more than one attribute, such as a constraint that 'systolic pressure should be >= diastolic pressure' in a blood pressure measurement archetype. They can also be used to declare variables, including external data query results, and make other constraints dependent on a variable value, e.g. the gender of the record subject.

Lastly, the annotations section, inherited from the AUTHORED_RESOURCE class, can be included as required. This section is of particular relevance to archetypes and templates, and is used to document individual nodes within an archetype or template, and/or nodes in reference model data, that may not be constrained in the archetype, but whose specific use in the archetyped data needs to be documented. In the former case, the annotations are keyed by an archetype path, while in the latter case, by a reference model path.

The model in Figure 6 defines the structures of a number of variants of the 'archetype' idea. All concrete instances are instances of one of the concrete descendants of ARCHETYPE. Figure 11 illustrates the typical object structure of a source archetype - the form of archetype created by an authoring tool - represented by a DIFFERENTIAL_ARCHETYPE instance. Mandatory parts are shown in bold.

Source archetypes can be specialised, in which case their definition structure is a partial overlay on the flat parent, or 'top-level', in which case the definition structure is complete. C_ARCHETYPE_ROOT instances may only occur representing direct references to other archetypes - 'external references'.

A flat archetype is generated from one or more source archetypes via the flattening process described in the next chapter of this specification, (also in the ADL specification). This generates a FLAT_ARCHETYPE from a DIFFERENTIAL_ARCHETYPE instance. The main two changes that occur in this operation are a) specialised archetype overlays are applied to the flat parent structure, resulting in a full archetype structure, and b) internal references (use_nodes) are replaced by their expanded form, i.e. a copy of the subtrees to which they point.

This form is used to represent the full 'operational' structure of a specialised archetype, and has two uses. The first is to generate backwards compatible ADL 1.4 legacy archetypes (always in flat form); the second is during the template flattening process, when the flat forms of all referenced archetypes and templates are ultimately combined into a single operational template.

Figure 12 illustrates the structure of a source template, i.e instances of TEMPLATE. A source template is an archetype containing C_ARCHETYPE_ROOT objects representing slot fillers - each referring to an external archetype or template, or potentially an overlay archetype.

Another archetype variant, also shown in Figure 12 is the template overlay, i.e. an instance of TEMPLATE_OVERLAY. These are purely local components of templates, and include only the definition and terminology. The definition structure is always a specialised overlay on something else, and may not contain any slot fillers or external references, i.e. no C_ARCHETYPE_ROOT objects. No identifier, adl_version, languages or description are required, as they are considered to be propagated from the owning root template. Accordingly, template overlays act like a simplified specialised archetype. Template overlays can be thought of as being similar to 'anonymous' or 'inner' classes in some object-oriented programming languages.

Figure 13 illustrates the resulting operational template, or compiled form of a template. This is created by building the composition of referenced archetypes and/or templates and/or template overlays, in their flattened form, to generate a single 'giant' archetype. The root node of this archetype, along with every archetype/template root node within, is represented using a C_ARCHETYPE_ROOT object. An operational template also has a component_terminologies property containing the ontologies from every constituent archetype, template and overlay.

More details of template development, representation and semantics are described in the next section.

Some properties are defined for all node types, described in the following sections.

Constraints on reference model attributes, including computed attributes (represented by functions with no arguments in most programming languages), are represented by instances of C_ATTRIBUTE. The expressible constraints include:

In the case of single-valued attributes (such as Person.date_of_birth) the children represent one or more alternative object constraints for the attribute value.

For multiply-valued attributes (such as Person.contacts: List<Contact>), a cardinality constraint on the container can be defined. The constraint on child objects is essentially the same except that more than one of the alternatives can co-exist in the data. Figure 17 illustrates the two possibilities.

The appearance of both existence and cardinality constraints in C_ATTRIBUTE deserves some explanation, especially as the meanings of these notions are often confused in object-oriented literature. An existence constraint indicates whether an object will be found in a given attribute field, while a cardinality constraint indicates what the valid membership of a container object is. Cardinality is only required for container objects such as List<T> , Set<T> and so on, whereas existence is always possible. If both are used, the meaning is as follows: the existence constraint says whether the container object will be there (at all), while the cardinality constraint says how many items must be in the container, and whether it acts logically as a list, set or bag. Both existence and cardinality are optional in the model, since they are only needed to override the settings from the reference model.

The following sections apply to all object nodes in an archetype, i.e. instances of any descendant of C_OBJECT.

Two subtypes of C_OBJECT, namely ARCHETYPE_SLOT and C_COMPLEX_OBJECT_PROXY are used to express constraints in the form of references to other constraints, rather than directly.

An ARCHETYPE_SLOT defines a 'slot' specifying other archetypes that can be plugged in at that point, in terms of constraints on archetype identifiers. These are expressed as instances of the ARCHETYPE_ID_CONSTRAINT class, a specialised version of the ELOM EL_CONSTRAINT_EXPRESSION class.

The type C_COMPLEX_OBJECT_PROXY represents a reference to another part of the current archetype that expresses exactly the same constraints needed at the point where the proxy appears.

The C_DEFINED_OBJECT subtype corresponds to the category of C_OBJECTs that are defined in an archetype by value, i.e. by inline definition. Four properties characterise C_DEFINED_OBJECTs as follows.

Along with C_ATTRIBUTE, C_COMPLEX_OBJECT is the key structuring type of the constraint_model package, and consists of attributes of type C_ATTRIBUTE, which are constraints on the attributes (i.e. any property, including relationships) of the reference model type. Accordingly, each C_ATTRIBUTE records the name of the constrained attribute (in rm_attr_name) , the existence and cardinality expressed by the constraint (depending on whether the attribute it constrains is a multiple or single relationship), and the constraint on the object to which this C_ATTRIBUTE refers via its children attribute (according to its reference model) in the form of further C_OBJECTs.

Constraints on primitive types are defined by the descendants of C_PRIMITIVE_OBJECT, i.e. C_STRING , C_INTEGER and so on. The primitive constraint types are represented in such a way as to accommodate both 'tuple' constraints and logically unary constraints, using a tuple array (C_PRIMITIVE_TUPLE.members) whose members are each a primitive constraint corresponding to each primitive type in the tuple. Tuple constraints are second order constraints, described below, enabling co-varying constraints to be stated. In the unary case, the constraint is the first member of a tuple array.

C_PRIMITIVE_OBJECT instances represented in ADL 'short' form are created with a fixed id-code ADL_CODE_DEFINITIONS.primitive_node_id as the value of node_id (see Section 2.3.3). For regularly structured C_PRIMITIVE_OBJECT instances, a normal node identifier is required.

The primitive constraint for each primitive type may itself be complex. Its formal type is the type of the constraint accessor in each C_PRIMITIVE_OBJECT descendant. The use of constrainer types for each assumed primitive RM type is summarised in the following table.

The RM primitive types listed above are assumed to exist (possibly with different names) within any RM used as the basis for creating archetypes. Where any do not exist - e.g. if there are no date/time types in a particular RM - no archetype constraints can be defined for such nodes. Where the types have different names, name mapping can be performed as described in Section 11.4 below.

This facility can be used to effect the following mappings from C_PRIMITIVE_OBJECT descendants (C_STRING, C_INTEGER etc) to the types found in any particular RM.

The openEHR architecture assumes that primitive types representing 'date', 'time' and 'date_time' exist within every development environment, however such types or classes may be named. Within openEHR, these primitive types are named Iso8601_date etc., and are defined in the openEHR Foundation Types Specification.

As described in the openEHR ADL2 specification, these types are constrained using either value intervals or patterns. Both kinds of constraint are formally represented by the classes C_DATE, C_TIME and C_DATE_TIME. (A fourth time-related type, 'Duration' is constrained somewhat differently by the AOM class C_DURATION).

ADL2 value range constraints, such as the date range |2004-05-20..2005-05-19| are represented in the relevant constrainer meta-class (in this case C_DATE) by an attribute of the form constraint: List<Interval<Iso8601_date>>. Similarly, an ADL2 date/time range constraint such as |<2005-05-19T23:59:59| is represented by C_DATE_TIME.constraint of type List<Interval<Iso8601_date_time>>. The List<> structure allows such constraints to include more than one disjoint range.

The other means of expressing constraints in ADL2 is via patterns based on the ISO 8601 extended syntax form (i.e. the form that uses '-' and ':' characters in dates and times, respectively). These allow partial dates and times to be stated. Thus, the time constraint hh:??:XX means: any time consisting of hours, optional minutes, and no seconds. A full table of such constraint patterns is provided in the ADL2 specification.

Pattern constraints are represented within the AOM classes C_DATE etc. via the attribute pattern_constraint: String, inherited from the abstract class C_TEMPORAL. Validity may be checked using features defined on the class C_TEMPORAL_DEFINITIONS, such as valid_date_constraint_patterns, and also valid_date_constraint_replacements, for checking redefinitions within specialised archetypes.

Date/time pattern constraints are computationally represented via functions like month_validity(): VALIDITY_KIND, defined on C_DATE, C_TIME and C_DATE_TIME, where VALIDITY_KIND is an enumeration type defined in the openEHR Base Types. The lexical elements of the patterns are mapped to the values of VALIDITY_KIND as follows:

Accordingly, the '??' within the date constrainer pattern yyyy-??-XX maps to the result optional of the function C_DATE.month_validity().

Duration constraints follow the same general approach as Date/time constraints, such that the C_DURATION meta-class provides a range constraint attribute constraint: List<Interval<Iso8601_duration>> as well as the inherited attribute pattern_constraint: String to represent pattern constraints. These are described in openEHR ADL2 specification.

However, the pattern constraints are of a simpler form, and do not use the ?? or XX lexical elements. The pattern interpretation functions defined on C_DURATION are therefore of the form years_allowed: (): Boolean, months_allowed: (): Boolean. Validity of duration pattern constraints may be checked using relevant functions defined on C_TEMPORAL_DEFINITIONS.

Enumeration types in the reference model are assumed to have semantics expected in UML, and mainstream programming languages, i.e. to be a distinct type based on a primitive type, normally Integer or String. Each such type consists of a set of values from the domain of its underlying type, thus, a set of Integer, String or other primitive values. Each of these values is assumed to be named in the manner of a symbolic constant. Although strictly speaking UML doesn’t require an enumerated type to be based on an underlying primitive type, programming languages do, hence the assumption here that values from the domain of such a type are involved.

A constraint on an enumerated type therefore consists of an AOM instance of a C_PRIMITIVE descendant, almost always C_INTEGER or C_STRING . The flag is_enumerated_type_constraint defined on C_PRIMITIVE indicates that a given C_PRIMITIVE is a constrainer for an enumerated type.

Since C_PRIMITIVEs don’t have type names in ADL, the type name is inferred by any parser or compiler tool that deserialises an archetype from ADL, and stored in the rm_type attribute inherited from C_OBJECT . An example is shown below of a type enumeration.

A parser that deserialises from an object dump format such as ODIN, JSON or XML will not need to do this.

The form of the constraint itself is simply a series of Integer, String or other primitive values, or an equivalent range or ranges. In the above example, the ADL equivalent of the pk_percent, pk_fraction constraint on a field of type PROPORTION_KIND is in fact just \{2, 3}, and it is visualised by lookup to show the relevant symbolic names.

Tuple constraints are designed to account for the very common need to constrain the values of more than one RM class attribute together. This effectively treats the attributes in question as a tuple, and the corresponding object constraints are accordingly modelled as tuples as well. A detailed explanation of tuples can be found in the ADL2 specification’s section on second order constraints. Additions to the main constraint model to support tuples are shown below.

In this model, the type C_ATTRIBUTE_TUPLE groups the co-constrained C_ATTRIBUTEs under a C_COMPLEX_OBJECT. Currently, the concrete type is limited to being C_PRIMITIVE_OBJECT to reduce complexity, and since it caters for all known examples of tuple constraints. In principle, any C_DEFINED_OBJECT could be allowed, and this may change in the future.

The tuple constraint type replaces all domain-specific constraint types defined in ADL/AOM 1.4, including C_DV_QUANTITY and C_DV_ORDINAL.

These additions allow standard constraint structures (i.e. C_ATTRIBUTE / C_COMPLEX_OBJECT / C_PRIMITIVE_OBJECT hierarchies) to be 'annotated', while leaving the first order structure intact. The following example shows an archetype instance structure in which a notional ORDINAL type is constrained. The logical requirement is to constrain a ORDINAL to one of three instance possibilities, each of which consists of a pair of values for the attributes value and symbol, of type Integer and TERMINOLOGY_CODE respectively. Each of these three instance constraints should be understood as an alternative for the single valued owning attribute, ELEMENT .value. Tuple constraints achieve the requirement to express the constraints as pairs not just as allowable alternatives at the final leaf level, which would incorrectly allowing any mixing of the Integer and code values.

Assertions are used in ARCHETYPE_SLOTs, in order to express the 'included' and 'excluded' archetypes for the slot. In this case, each assertion is an expression that refers to parts of other archetypes, such as its identifier (e.g. 'include archetypes with short_concept_name matching xxxx '). Assertions are modelled here as a generic expression tree of unary prefix and binary infix operators. Examples of archetype slots in ADL syntax are given in the openEHR ADL2 specification.