openEHR logo

Archetype Object Model 1.4 (AOM1.4)

Issuer: openEHR Specification Program

Release: AM latest

Status: STABLE

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: EHR, ADL, AOM, health records, archetypes, constraint language, ISO 13606, openehr

openEHR components
© 2004 - 2024 The openEHR Foundation

The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.

Licence

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser, Implementer Completed

AM Release 2.3.0

1.4.6

SPECAM-84. Fix typos in AOM, ADL 1.4.

R Kavanagh

03 Apr 2023

SPECAM-82. Upgrade AOM1.4 model to use BASE, and to have regular package structure. Correct a UML error to move the invariant on C_MULTIPLE_ATTRIBUTE to C_SINGLE_ATTRIBUTE.

T Beale

14 Feb 2023

1.4.5

SPECAM-69. Support negative durations. See Section 6.2.9. (see also SPECRM-96).

P Bos,
S Garde

09 Sep 2020

1.4.4

SPECPUB-7. Convert citations to bibtex form.

T Beale

15 Dec 2019

AM Release 2.1.0

1.4.3

SPECAM-42Adjust references to BASE packages foundation_types, base_types and resource types.

T Beale

22 Sep 2017

AM Release 2.0.6

1.4.2

Add Appendix C, containing UML diagrams for RM dependencies.

D Boscá

18 May 2016

SPECBASE-4. Change order of type parameters in Hash<V,K> type to Hash<K,V>.

D Boscá

13 Apr 2016

Release 1.0.2

1.0.2

SPEC-257. Correct minor typos and clarify text. Correct reversed definitions of is_bag and is_set in CARDINALITY class.

C Ma,
R Chen,
T Cook

20 Nov 2008

SPEC-251. Allow both pattern and interval constraint on Duration in Archetypes. Add pattern attribute to C_DURATION class.

S Heard

Release 1.0.1

1.0.1

SPEC-200. Correct Release 1.0 typographical errors. Table for missed class ASSERTION_VARIABLE added. Assumed_value assertions corrected; standard_representation function corrected. Added missed adl_version , concept rename from SPEC-153.

D Lloyd,
P Pazos,
R Chen,
C Ma

20 Mar 2007

SPEC-216: Allow mixture of W, D etc in ISO8601 Duration (deviation from standard).

S Heard

SPEC-219: Use constants instead of literals to refer to terminology in RM.

R Chen

SPEC-232. Relax validity invariant on CONSTRAINT_REF .

R Chen

SPEC-233: Define semantics for occurrences on ARCHETYPE_INTERNAL_REF .

K Atalag

SPEC-234: Correct functional semantics of AOM constraint model package.

T Beale

SPEC-245: Allow term bindings to paths in archetypes.

S Heard

Release 1.0

1.0

SPEC-153. Synchronise ADL and AOM attribute naming. SPEC-178. Add Template Object Model to AM. Text changes only. SPEC-167. Add AUTHORED_RESOURCE class. Remove description package to resource package in Common IM.

T Beale

10 Nov 2005

Release 0.96

0.6

SPEC-134. Correct numerous documentation errors in AOM. Including cut and paste error in TRANSLATION_DETAILS class in Archetype package. Corrected hyperlinks in Section 2.3.

D Lloyd

20 Jun 2005

SPEC-142. Update ADL grammar to support assumed values. Changed C_PRIMITIVE and C_DOMAIN_TYPE .

S Heard,
T Beale

SPEC-146: Alterations to am.archetype.description from CEN MetaKnow

D Kalra

SPEC-138. Archetype-level assertions.

T Beale

SPEC-157. Fix names of OPERATOR_KIND class attributes

T Beale

Release 0.95

0.5.1

Corrected documentation error - return type of ARCHETYPE_CONSTRAINT . has_path
add optionality markers to Primitive types UML diagram.
Removed erroneous aggregation marker from ARCHETYPE_ONTOLOGY . parent_archetype and ARCHETYPE_DESCRIPTION . parent_archetype .

D Lloyd

20 Jan 2005

0.5

SPEC-110. Update ADL document and create AOM document.
Includes detailed input and review from:

  • DSTC, Australia

  • CHIME, University College London

  • Ocean Informatics

Initial Writing. Taken from ADL document 1.2draft B.

T Beale
A Goodchild
Z Tun
T Austin
D Kalra
N Lea
D Lloyd
S Heard
T Beale

10 Nov 2004

Acknowledgements

Primary Author

  • Thomas Beale, Ars Semantica, UK

Supporters

The work reported in this paper has been funded by the following organisations:

  • UCL (University College London) - Centre for Health Informatics and Multiprofessional Education (CHIME);

  • Ocean Informatics.

Special thanks to Prof David Ingram, founding Director of CHIME, UCL, who provided a vision and collegial working environment ever since the days of GEHR (1992).

Trademarks

  • 'openEHR' is a trademark of the openEHR Foundation

  • 'Java' is a registered trademark of Oracle Corporation

  • 'Microsoft' is a trademark of the Microsoft Corporation

1. Preface

1.1. Purpose

This document contains the definitive statement of archetype semantics, in the form of an object model for archetypes. The model presented here can be used as a basis for building software that processes archetypes, independent of their persistent representation; equally, it can be used to develop the output side of parsers that process archetypes in a linguistic format, such as the openEHR Archetype Definition Language (ADL), XML-instance and so on. As a specification, it can be treated as an API for archetypes.

It is recommended that the openEHR ADL document be read in conjunction with this document, since it contains a detailed explanation of the semantics of archetypes, and many of the examples are more obvious in ADL, regardless of whether ADL is actually used with the object model presented here or not.

Prerequisite documents for reading this document include:

Related documents include:

1.3. Nomenclature

In this document, the term 'attribute' denotes any stored property of a type defined in an object model, including primitive attributes and any kind of relationship such as an association or aggregation. XML 'attributes' are always referred to explicitly as 'XML attributes'.

1.4. Status

This specification is in the STABLE state. The development version of this document can be found at https://specifications.openehr.org/releases/AM/latest/AOM1.4.html.

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

TBD: (example To Be Determined paragraph)

Note
this specification is a re-formatted issue of the original AOM 1.4 Specification from openEHR Release 1.0.2. There are slight changes in formatting, citations and other references, corrections to typographical errors and changed syntax colourisation due to the use of more modern language-based syntax colourisers in the publishing tools.
Note
for users requiring the most recent form of ADL and archetype technology in general, the Archetype Definition Language 2 (ADL2) specifications should be used. In particular, the Archetype Technology Overview should be referred to for the most current state of Archetype Technology.

1.5. Feedback

Feedback may be provided on the openEHR ADL forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the AM component Change Request tracker.

1.6. Conformance

Conformance of a data or software artifact to an openEHR specification is determined by a formal test of that artifact against the relevant openEHR Implementation Technology Specification(s) (ITSs), such as an IDL interface or an XML-schema. Since ITSs are formal derivations from underlying models, ITS conformance indicates model conformance.

1.7. Background

1.7.1. What is an Archetype?

Archetypes are constraint-based models of domain entities, or what some might call "structured business rules". Each archetype describes configurations of data instances whose classes are described in a reference model; the instance configurations are considered to be valid exemplars of a particular domain concept. Thus, in medicine, an archetype might be designed to constrain configurations of instances of a simple node/arc information model, that express a "microbiology test result" or a "physical examination". Archetypes can be composed, specialised, and templated for local use. The archetype concept has been described in detail by Beale (2000), Beale (2002). Most of the detailed formal semantics are described in the openEHR Archetype Definition Language. The openEHR archetype framework is described in the openEHR Archetypes Technical Overview.

1.7.2. Context

The object model described in this document relates to linguistic forms of archetypes as shown in the figure below. The model (upper right in the figure) is the object-oriented semantic equivalent of the ADL the Archetype Definition Language BNF language definition, and, by extension, any formal transformation of it. Instances of the model (lower right on the figure) are themselves archetypes, and correspond one-to-one with archetype documents expressed in ADL or a related language.

syntax model relationship
Figure 1. Relationship of Archetype Object Model to Archetype Languages

1.8. Tools

Various tools exist for creating and processing archetypes. The ADL Workbench is a reference compiler, visualiser and editor. The openEHR tools can be downloaded from the website . Source projects can be found at the openEHR Github project.

1.9. Changes from Previous Versions

1.9.1. Version 0.6 to 2.0

As part of the changes carried out to ADL version 1.3, the archetype object model specified here is revised, also to version 2.0, to indicate that ADL and the AOM can be regarded as 100% synchronised specifications.

  • added a new attribute adl_version : String to the ARCHETYPE class;

  • changed name of ARCHETYPE.concept_code attribute to concept.

2. The Archetype Object Model

2.1. Design Background

An underpinning principle of openEHR is the use of archetypes and templates, which are formal models of domain content, and are used to control data structure and content during creation, modification and querying. The elements of this architecture are twofold.

  • The openEHR Reference Model (RM), defining the structure and semantics of information in terms of information models (IMs). The RM models correspond to the ISO RM/ODP information viewpoint, and define the data of openEHR EHR systems. The information model is designed to be invariant in the long term, to minimise the need for software and schema updates.

  • The openEHR Archetype Model (AM), defining the structure and semantics of archetypes and templates. The AM consists of the archetype language definition language (ADL), the Archetype Object Model (AOM) and the openEHR Archetype profile (oAP).

The purpose of ADL is to provide an abstract syntax for textually expressing archetypes and templates. The AOM defines the object model equivalent, in terms of a UML model. It is a generic model, meaning that it can be used to express archetypes for any reference model in a standard way. ADL and the AOM are brought together in an ADL parser: a tool which can read ADL archetype texts, and whose parse-tree (resulting in-memory object representation) is instances of the AOM. The TOM defines the object model of templates, which are themselves used to put archetypes together into local information structures, usually corresponding to screen forms.

The purpose of the openEHR Archetype Profile is to define which classes and attributes of the openEHR RM can be sensibly archetyped, and to provide custom archetype classes.

2.2. Package Structure

The openEHR Archetype Object Model is defined as the package am.archetype, as illustrated below. It is shown in the context of the openEHR am.archetype packages.

AM aom14 packages
Figure 2. Package Overview

2.3. Model Overview

The model described here is a pure object-oriented model that can be used with archetype parsers and software that manipulates archetypes. It is independent of any particular linguistic expression of an archetype, such as ADL or OWL, and can therefore be used with any kind of parser.

It is dependent on the openEHR Release 1.0.3 Support IM (assumed_types and identifiers packages), a small number of the openEHR Data Types (openEHR Release 1.0.3 Data Types IM), and the resource package from the openEHR Release 1.0.3 Common IM. These dependencies are shown for convenience in the [Reference Model Dependencies] appendix.

2.3.1. Archetypes as Objects

The following figure illustrates various processes that can be responsible for creating an archetype object structure, including parsing, database retrieval and GUI editing. A parsing process that would typically turn a syntax expression of an archetype (ADL, XML, OWL) into an object one. The input file is converted by a parser into an object parse tree, shown on the right of the figure, whose types are specified in this document. Database retrieval will cause the reconstruction of an archetype in memory from a structured data representation, such as relational data, object data or XML. Direct in-memory editing by a user with a GUI archetype editor application will cause on-the-fly creation and destruction of parts of an archetype during the editing session, which would eventually cause the archetype to be stored in some form when the user decides to commit it.

After initial parsing, the in-memory representation is then validated by the semantic checker of the ADL parser, which can verify numerous things, such as that term codes referenced in the definition section are defined in the ontology section. It can also validate the classes and attributes mentioned in the archetype against a specification for the relevant information model (e.g. in XMI or some equivalent).

archetype parsing process
Figure 3. Archetype Parsing Process

As shown in the figure, the definition part of the in-memory archetype consists of alternate layers of object and attribute constrainer nodes, each containing the next level of nodes. In this document, the word 'attribute' refers to any data property of a class, regardless of whether regarded as a 'relationship' (i.e. association, aggregation, or composition) or 'primitive' (i.e. value) attribute in an object model. At the leaves are primitive object constrainer nodes constraining primitive types such as String, Integer etc. There are also nodes that represent internal references to other nodes, constraint reference nodes that refer to a text constraint in the constraint binding part of the archetype ontology, and archetype constraint nodes, which represent constraints on other archetypes allowed to appear at a given point. The full list of concrete node types is as follows:

C_COMPLEX_OBJECT

any interior node representing a constraint on instances of some non-primitive type, e.g. ENTRY, SECTION;

C_ATTRIBUTE

a node representing a constraint on an attribute (i.e. UML 'relationship' or 'primitive attribute') in an object type;

C_PRIMITIVE_OBJECT

a node representing a constraint on a primitive (built-in) object type;

ARCHETYPE_INTERNAL_REF

a node that refers to a previously defined object node in the same archetype. The reference is made using a path;

CONSTRAINT_REF

a node that refers to a constraint on (usually) a text or coded term entity, which appears in the ontology section of the archetype, and in ADL, is referred to with an "acNNNN" code. The constraint is expressed in terms of a query on an external entity, usually a terminology or ontology;

ARCHETYPE_SLOT

a node whose statements define a constraint that determines which other archetypes can appear at that point in the current archetype. It can be thought of like a keyhole, into which few or many keys might fit, depending on how specific its shape is. Logically it has the same semantics as a C_COMPLEX_OBJECT, except that the constraints are expressed in another archetype, not the current one.

The typename nomenclature "C_COMPLEX_OBJECT", "C_PRIMITIVE_OBJECT", "C_ATTRIBUTE" used here is intended to be read as "constraint on xxxx", i.e. a "C_COMPLEX_OBJECT" is a "constraint on a complex object (defined by a complex reference model type)". These type-names are used below in the formal model.

2.3.2. The Archetype Ontology

There are no linguistic entities at all in the definition part of an archetype, with the possible exception of constraints on text items which might have been defined in terms of regular expression patterns or fixed strings. All linguistic entities are defined in the ontology part of the archetype, in such a way as to allow them to be translated into other languages in convenient blocks. As described in the openEHR ADL document, there are four major parts in an archetype ontology section: term definitions, constraint definitions, term bindings and constraint bindings. The former two define the meanings of various terms and textual constraints which occur in the archetype; they are indexed with unique identifiers which are used within the archetype definition body. The latter two ontology sections describe the mappings of terms used internally to external terminologies. Due to the well-known problems with terminologies (described in some detail in the openEHR ADL 1.4 specification, and also by e.g. Rector (2000) and others), mappings may be partial, incomplete, approximate, and occasionally, exact.

2.3.3. Archetype Specialisation

Archetypes can be specialised. The formal rules of specialisation are described in the openEHR Archetype Semantics document (forthcoming), but in essence are easy to understand. Briefly, an archetype is considered a specialisation of another archetype if it mentions that archetype as its parent, and only makes changes to its definition such that its constraints are 'narrower' than those of the parent. Any data created via the use of the specialised archetype is thus conformant both to it and its parent. This notion of specialisation corresponds to the idea of 'substitutability', applied to data.

Every archetype has a 'specialisation depth'. Archetypes with no specialisation parent have depth 0, and specialised archetypes add one level to their depth for each step down a hierarchy required to reach them.

2.3.4. Archetype Composition

In the interests of re-use and clarity of modelling, archetypes can be composed to form larger structures semantically equivalent to a single large archetype. Composition allows two things to occur: for archetypes to be defined according to natural 'levels' or encapsulations of information, and for the reuse of smaller archetypes by a multitude of others. Archetype slots are the means of composition, and are themselves defined in terms of constraints.

3. The Archetype Package

3.1. Overview

The model of an archetype, illustrated in the following figure, is straightforward at an abstract level, mimicking the structure of an archetype document as defined in the openEHR Archetype Definition Language (ADL) document. An archetype is modelled as a particular kind of AUTHORED_RESOURCE, and as such, includes descriptive meta-data, language information and revision history. The ARCHETYPE class adds identifying information, a definition - expressed in terms of constraints on instances of an object model, and an ontology. The archetype definition, the 'main' part of an archetype, is an instance of a C_COMPLEX_OBJECT, which is to say, the root of the constraint structure of an archetype always takes the form of a constraint on a non-primitive object type. The last section of an archetype, the ontology, is represented by its own class, and is what allows the archetypes to be natural language- and terminology-neutral.

AM aom14.archetype
Figure 4. am.aom14.archetype Package

3.2. Class Descriptions

3.2.1. ARCHETYPE Class

Class

ARCHETYPE

Description

Archetype equivalent to ARCHETYPED class in Common reference model. Defines semantics of identfication, lifecycle, versioning, composition and specialisation.

Inherit

AUTHORED_RESOURCE

Attributes

Signature

Meaning

1..1

definition: C_COMPLEX_OBJECT

Root node of the definition of this archetype.

1..1

ontology: ARCHETYPE_ONTOLOGY

The ontology of the archetype.

0..1

adl_version: String

ADL version if archetype was read in from an ADL sharable archetype.

1..1

archetype_id: ARCHETYPE_ID

Multi-axial identifier of this archetype in archetype space.

1..1

concept: String

The normative meaning of the archetype as a whole, expressed as a local archetype code, typically “at0000”.

0..1

parent_archetype_id: ARCHETYPE_ID

Identifier of the specialisation parent of this archetype.

0..1

invariants: List<ASSERTION>

Invariant statements about this object. Statements are expressed in first order predicate logic, and usually refer to at least two attributes.

0..1
(redefined)

uid: HIER_OBJECT_ID

OID identifier of this archetype.

Functions

Signature

Meaning

1..1

concept_name (
a_lang: String[1]
): String

post-condition: Result.is_equal (definition.node_id)

The concept name of the archetype in language a_lang; corresponds to the term definition of the concept attribute in the archetype ontology.

1..1

physical_paths (): List<String>

Set of language-independent paths extracted from archetype. Paths obey Xpath-like syntax and are formed from alternations of C_OBJECT.node_id and C_ATTRIBUTE.rm_attribute_name values.

1..1

logical_paths (
lang: String[1]
): List<String>

Set of language-dependent paths extracted from archetype. Paths obey the same syntax as physical_paths, but with node_ids replaced by their meanings from the ontology.

1..1

specialisation_depth (): Integer

post-condition: Result = terminology.specialisation_depth

Specialisation depth of this archetype; larger than 0 if this archetype has a parent. Derived from terminology.specialisation_depth.

1..1

is_specialised (): Boolean

post-condition: Result implies parent_archetype_id /= Void

True if this archetype is a specialisation of another.

1..1

is_valid (): Boolean

Post: not (node_ids_valid and internal_references_valid and constraint_references_valid) implies not Result

True if the archetype is valid overall; various tests should be used, including checks on node_ids, internal references, and constraint references.

1..1

node_ids_valid (): Boolean

True if every node_id found on a C_OBJECT node is found in ontology.term_codes.

0..1

previous_version (): String

Version of predecessor archetype of this archetype, if any.

1..1

internal_references_valid (): Boolean

True if every ARCHETYPE_INTERNAL_REF. target_path refers to a legitimate node in the archetype definition.

1..1

constraint_references_valid (): Boolean

True if every CONSTRAINT_REF.reference found on a C_OBJECT node in the archetype definition is found in ontology.constraint_codes.

1..1

short_concept_name (): String

The short concept name of the archetype extracted from the archetype_id.

1..1

version (): String

Invariants

Inv_concept_valid: ontology.has_term_code (concept_code)

Inv_specialisation_validity: is_specialised implies specialisation_depth > 0

Inv_invariants_valid: invariants /= Void implies not invariants.is_empty

Inv_uid_validity: uid /= Void implies not uid.is_empty

Inv_version_validity: version /= Void and then version.is_equal(archetype_id.version_id)

Inv_description_valid: description /= Void

Inv_original_language_valid: original_language /= void and then language /= Void

4. Constraint Model Package

4.1. Overview

The figure below illustrates the class model of an archetype definition. This model is completely generic, and is designed to express the semantics of constraints on instances of classes which are themselves described in UML (or a similar object-oriented meta-model). Accordingly, the major abstractions in this model correspond to major abstractions in object-oriented formalisms, including several variations of the notion of 'object' and the notion of 'attribute'. The notion of 'object' rather than 'class' or 'type' is used because archetypes are about constraints on data (i.e. 'instances', or 'objects') rather than models, which are constructed from 'classes'.

An informal way of understanding the model is as follows. An archetype definition is an instance of a C_COMPLEX_OBJECT, which can be thought of as expressing constraints on an object that is of some particular reference model type (recorded in the attribute rm_type_name), and which is larger than a simple instance of a primitive type such as String or Integer. The constraints define what configurations of reference model class instances are considered to conform to the archetype. For example, certain configurations of the classes PARTY, ADDRESS, CLUSTER and ELEMENT might be defined by a Person archetype as allowable structures for 'people with identity, contacts, and addresses'. Because the constraints allow optionality, cardinality and other choices, a given archetype usually corresponds to a set of similar configurations of objects. At the leaf nodes of an archetype definition are C_PRIMITIVE_OBJECT nodes, defining the constraints on leaf values of objects, i.e. Integers, Strings etc.

AM aom14.archetype.constraint model
Figure 5. aom14.archetype.constraint_model Package

4.2. Semantics

The effect of the model is to create archetype description structures that are a hierarchical alternation of object and attribute constraints, as shown in Figure 3. This structure can be seen by inspecting an ADL archetype, or by viewing an archetype in openEHR ADL Workbench, and is a direct consequence of the object-oriented principle that classes consist of properties, which in turn have types that are classes. (To be completely correct, types do not always correspond to classes in an object model, but it does not make any difference here). The repeated object/attribute hierarchical structure of an archetype provides the basis for using paths to reference any node in an archetype. Archetype paths follow a syntax that is a subset of the W3C Xpath syntax.

4.2.1. All Node Types

A small number of properties are defined for all node types. The path feature computes the path to the current node from the root of the archetype, while the has_path function indicates whether a given path can be found in an archetype. The is_valid function indicates whether the current node and all sub-nodes are internally valid according to the semantics of this archetype model. The is_subset_of function is used for comparison between corresponding nodes from different archetypes, in order to asert specialisation.

4.2.2. Attribute Node Types

Constraints on attributes are represented by instances of the two subtypes of C_ATTRIBUTE: C_SINGLE_ATTRIBUTE and C_MULTIPLE_ATTRIBUTE. For both subtypes, the common constraint is whether the corresponding instance (defined by the rm_attribute_name attribute) must exist. Both subtypes have a list of children, representing constraints on the object value(s) of the attribute.

Single-valued attributes (such as Person.date_of_birth: Date) are constrained by instances of the type C_SINGLE_ATTRIBUTE, which uses the children to represent multiple alternative object constraints for the attribute value.

Multiply-valued attributes (such as Person.contacts: List<Contact>) are constrained by an instance of C_MULTIPLE_ATTRIBUTE, which allows multiple co-existing member objects of the container value of the attribute to be constrained, along with a cardinality constraint, describing ordering and uniqueness of the container. The following figure illustrates the two possibilities.

c attributes single multiple
Figure 6. Single and Multiple-valued C_ATTRIBUTEs

The need for both existence and cardinality constraints in the C_MULTIPLE_ATTRIBUTE class 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 required. 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.

4.2.3. Object Node Types

4.2.3.1. Node_id and Paths

The node_id attribute in the class C_OBJECT, inherited by all subtypes, is of great importance in the archetype constraint model. It has two functions:

  • it allows archetype object constraint nodes to be individually identified, and in particular, guarantees sibling node unique identification;

  • it is the main link between the archetype definition (i.e. the constraints) and the archetype ontology, because each node_id is a 'term code' in the ontology section.

The existence of node_ids in an archetype allows archetype paths to be created, which refer to each node. Not every node in the archetype needs a node_id, if it does not need to be addressed using a path; any leaf or near-leaf node which has no sibling nodes from the same attribute can safely have no node_id.

4.2.3.2. Defined Object Nodes (C_DEFINED_OBJECT)

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.

Any_allowed

The any_allowed function of a node indicates that any value permitted by the reference model for the attribute or type in question is allowed by the archetype; its use permits the logical idea of a completely "open" constraint to be simply expressed, avoiding the need for any further substructure. Any_allowed is effected in subtypes to indicate in concrete terms when it is True, usually related to Void attribute values.

Assumed_value

When archetypes are defined to have optional parts, an ability to define 'assumed' values is useful. For example, an archetype for the concept 'blood pressure measurement' might contain an optional protocol section describing the patient position, with choices 'lying', 'sitting' and 'standing'. Since the section is optional, data could be created according to the archetype which does not contain the protocol section. However, a blood pressure cannot be taken without the patient in some position, so clearly there could be an implied value for patient position. Amongst clinicians, basic assumptions are nearly always made for such things: in general practice, the position could always safely be assumed to be "sitting" if not otherwise stated; in the hospital setting, "lying" would be the normal assumption. The assumed values feature of archetypes allows such assumptions to be explicitly stated so that all users/systems know what value to assume when optional items are not included in the data. Assumed values are definable at the leaf level only, which appears to be adequate for all purposes described to date; accordingly, they appear in descendants of C_PRIMITIVE and also C_DOMAIN_TYPE.

The notion of assumed values is distinct from that of 'default values'. The latter is a local requirement, and as such is stated in templates; default values do appear in data, while assumed values don’t.

Valid_value

The valid_value function tests a reference model object for conformance to the archetype. It is designed for recursive implementation in which a call to the function at the top of the archetype definition would cause a cascade of calls down the tree. This function is the key function of an 'archetype-enabled kernel' component that can perform runtime data validation based on an archetype definition.

Default_value

This function is used to generate a reasonable default value of the reference object being constrained by a given node. This allows archetype-based software to build a 'prototype' object from an archetype which can serve as the initial version of the object being constrained, assuming it is being created new by user activity (e.g. via a GUI application). Implementation of this function will usually involve use of reflection libraries or similar.

4.2.3.3. Complex Objects (C_COMPLEX_OBJECT)

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.

4.2.3.4. Primitive Types

Constraints on primitive types are defined by the classes inheriting from C_PRIMITIVE, namely C_STRING, C_INTEGER and so on. These types do not inherit from ARCHETYPE_CONSTRAINT, but rather are related by association, in order to allow them to have the simplest possible definitions, independent even from the rest of ADL, in the hope of acceptance in heath standardisation organisations. Technically, avoiding inheritance from ARCHETYPE_CONSTRAINT / C_PRIMITIVE_OBJECT into these base types (in other words, coalescing the classes C_PRIMITIVE_OBJECT and C_PRIMITIVE) does not pose a problem, but could be effected at a later date if desired.

4.2.3.5. Domain-specific Extensions (C_DOMAIN_TYPE)

The main part of the archetype constraint model allows any type in a reference model to be archetyped - i.e. constrained - in a standard way, which is to say, by a regular cascade of C_COMPLEX_OBJECT / C_ATTRIBUTE / C_PRIMITIVE_OBJECT objects. This generally works well, especially for 'outer' container types in models. However, it occurs reasonably often that lower level logical 'leaf' types need special constraint semantics that are not conveniently achieved with the standard approach. To enable such classes to be integrated into the generic constraint model, the class C_DOMAIN_TYPE is included. This enables the creation of specific C_ classes, inheriting from C_DOMAIN_TYPE, which represent custom semantics for particular reference model types. For example, a class called C_QUANTITY might be created which has different constraint semantics from the default effect of a C_COMPLEX_OBJECT / C_ATTRIBUTE cascade representing such constraints in the generic way (i.e. systematically based on the reference model). An example of domain-specific extension classes is shown in the section Appendix A.

4.2.3.6. Reference Objects (C_REFERENCE_OBJECT)

The subtypes of C_REFERENCE_OBJECT, namely, ARCHETYPE_SLOT, ARCHETYPE_INTERNAL_REF and CONSTRAINT_REF are used to express, respectively, a 'slot' where further archetypes can be used to continue describing constraints; a reference to a part of the current archetype that expresses exactly the same constraints needed at another point; and a reference to a constraint on a constraint defined in the archetype ontology, which in turn points to an external knowledge resource, such as a terminology.

A CONSTRAINT_REF is really a proxy for a set of constraints on an object that would normally occur at a particular point in the archetype as a C_COMPLEX_OBJECT, but where the actual definition of the constraints is outside the archetype definition proper, and is instead expressed in the binding of the constraint reference (e.g. 'ac0004') to a query or expression into an external service (e.g. a terminology service). The result of the query could be something like:

  • a set of allowed CODED_TERMs e.g. the types of hepatitis

  • an INTERVAL<QUANTITY> forming a reference range

  • a set of units or properties or other numerical item

See Placeholder constraints in the ADL specification for a fuller explanation.

4.2.4. Assertions

The C_ATTRIBUTE and subtypes of C_OBJECT enable constraints to be expressed in a structural fashion such that any constraint concerning a single attribute may be expressed, including recursively. In addition to this, any instance of a C_COMPLEX_OBJECT may include one or more invariants. Invariants are statements in a form of predicate logic, which can also be used to state constraints on parts of an object. They are not needed to constrain single attributes (since this can be done with an appropriate C_ATTRIBUTE), 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. Invariants are expressed using a syntax derived from the OMG’s OCL syntax (adapted for use with objects rather than classes).

Assertions are also 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 ADL document.

4.3. Class Definitions

4.3.1. ARCHETYPE_CONSTRAINT Class

Class

ARCHETYPE_CONSTRAINT (abstract)

Description

Archetype equivalent to LOCATABLE class in openEHR Common reference model. Defines common constraints for any inheritor of LOCATABLE in any reference model.

Functions

Signature

Meaning

1..1
(abstract)

is_subset_of (
other: ARCHETYPE_CONSTRAINT[1]
): Boolean

True if constraints represented by this node, ignoring any sub-parts, are narrower or the same as other. Typically used during validation of special-ised archetype nodes.

1..1
(abstract)

is_valid (): Boolean

1..1

path (): String

Path of this node relative to root of archetype.

1..1

has_path (
a_path: String[1]
): Boolean

True if the relative path a_path exists at this node.

4.3.2. C_ATTRIBUTE Class

Class

C_ATTRIBUTE (abstract)

Description

Abstract model of constraint on any kind of attribute node.

Inherit

ARCHETYPE_CONSTRAINT

Attributes

Signature

Meaning

1..1

rm_attribute_name: String

Reference model attribute within the enclosing type represented by a C_OBJECT.

1..1

existence: Interval<Integer>

Constraint on every attribute, regardless of whether it is singular or of a container type, which indicates whether its target object exists or not (i.e. is mandatory or not).

0..1

children: List<C_OBJECT>

Child C_OBJECT nodes. Each such node represents a constraint on the type of this attribute in its reference model. Multiples occur both for multiple items in the case of container attributes, and alternatives in the case of singular attributes.

Functions

Signature

Meaning

1..1

any_allowed (): Boolean

Post: Result := children = Void or else children.is_empty

True if any value (i.e. instance) of the reference model attribute represented by this C_ATTIRBUTE is allowed.

Invariants

Rm_attribute_name_valid: not rm_attribute_name.is_empty

Existence_set: existence.lower >= 0 and existence.upper <= 1

Children_validity: any_allowed xor children /= Void

4.3.3. C_SINGLE_ATTRIBUTE Class

Class

C_SINGLE_ATTRIBUTE

Description

Concrete model of constraint on a single-valued attribute node. The meaning of the inherited children attribute is that they are alternatives.

Inherit

C_ATTRIBUTE

Functions

Signature

Meaning

0..1

alternatives (): List<C_OBJECT>

List of alternative constraints for the single child of this attribute within the data.

Invariants

Members_valid: alternatives /= Void and then alternatives.for_all(co: C_OBJECT | co.occurrences.upper <= 1)

4.3.4. C_MULTIPLE_ATTRIBUTE Class

Class

C_MULTIPLE_ATTRIBUTE

Description

Concrete model of constraint on multiply-valued (ie. container) attribute node.

Inherit

C_ATTRIBUTE

Attributes

Signature

Meaning

1..1

cardinality: CARDINALITY

Cardinality of this attribute constraint, if it constraints a container attribute.

Functions

Signature

Meaning

0..1

members (): List<C_OBJECT>

List of constraints representing members of the container value of this attribute within the data. Semantics of the uniqueness and ordering of items in the container are given by the cardinality.

4.3.5. CARDINALITY Class

Class

CARDINALITY

Description

Express constraints on the cardinality of container objects which are the values of multiply-valued attributes, including uniqueness and ordering, providing the means to state that a container acts like a logical list, set or bag. The cardinality cannot contradict the cardinality of the corresponding attribute within the relevant reference model.

Attributes

Signature

Meaning

1..1

interval: Interval<Integer>

The interval of this cardinality.

1..1

is_ordered: Boolean

True if the members of the container attribute to which this cardinality refers are ordered.

1..1

is_unique: Boolean

True if the members of the container attribute to which this cardinality refers are unique.

Functions

Signature

Meaning

1..1

is_bag (): Boolean

True if the semantics of this cardinality represent a bag, i.e. unordered, non-unique membership.

1..1

is_list (): Boolean

True if the semantics of this cardinality represent a list, i.e. ordered, non-unique membership.

1..1

is_set (): Boolean

True if the semantics of this cardinality represent a bag, i.e. unordered, non-unique membership.

4.3.6. C_OBJECT Class

Class

C_OBJECT (abstract)

Description

Abstract model of constraint on any kind of object node.

Inherit

ARCHETYPE_CONSTRAINT

Attributes

Signature

Meaning

1..1

rm_type_name: String

Reference model type that this node corresponds to.

1..1

occurrences: Interval<Integer>

Occurrences of this object node in the data, under the owning attribute. Upper limit can only be greater than 1 if owning attribute has a cardinality of more than 1).

1..1

node_id: String

Semantic identifier of this node, used to dis-tinguish sibling nodes. All nodes must have a node_id; for nodes under a container C_ATTRIBUTE, the id must be an id-code must be defined in the archetype terminolo-gy. For valid structures, all node ids are id-codes. For C_PRIMITIVE_OBJECTs, it will have the special value Primitive_node_id.

4.3.7. C_DEFINED_OBJECT Class

Class

C_DEFINED_OBJECT (abstract)

Description

Abstract parent type of C_OBJECT subtypes that are defined by value, i.e. whose definitions are actually in the archetype rather than being by reference.

Inherit

C_OBJECT

Attributes

Signature

Meaning

0..1

assumed_value: Any

Value to be assumed if none sent in data.

Functions

Signature

Meaning

1..1
(abstract)

valid_value (
a_value: Any[1]
): Boolean

True if a_value is valid with respect to constraint expressed in concrete instance of this type.

1..1
(abstract)

prototype_value (): Any

Generate a prototype value from this constraint object.

1..1

has_assumed_value (): Boolean

True if there is an assumed value.

0..1
(abstract)

default_value (): Any

Generate a default value from this constraint object.

1..1
(abstract)

any_allowed (): Boolean

Post: Result = attributes.is_empty

True if any value of the reference model type being constrained is allowed. Redefine in descendants.

Invariants

Assumed_value_valid: has_assumed_value implies valid_value(assumed_value)

4.3.8. C_COMPLEX_OBJECT Class

Class

C_COMPLEX_OBJECT

Description

Constraint on complex objects, i.e. any object that consists of other object constraints.

Inherit

C_DEFINED_OBJECT

Attributes

Signature

Meaning

0..1

attributes: List<C_ATTRIBUTE>

List of constraints on attributes of the reference model type represented by this object.

Functions

Signature

Meaning

1..1
(effected)

any_allowed (): Boolean

Post: Result = attributes.is_empty

True if any value of the reference model type being constrained is allowed.

Invariants

Attributes_valid: ` any_allowed xor (attributes /= Void and not attributes.is_empty)`

4.3.9. C_PRIMITIVE_OBJECT Class

Class

C_PRIMITIVE_OBJECT

Description

Constraint on a primitive type.

Inherit

C_DEFINED_OBJECT

Attributes

Signature

Meaning

1..1

item: C_PRIMITIVE

Object actually defining the constraint.

Functions

Signature

Meaning

1..1
(effected)

any_allowed (): Boolean

Post: Result = item = Void

True if any value of the type being constrained in item is allowed.

Invariants

Item_valid: any_allowed xor item /= Void

4.3.10. C_DOMAIN_TYPE Class

Class

C_DOMAIN_TYPE (abstract)

Description

Abstract parent type of domain-specific constrainer types, to be defined in external packages.

Inherit

C_DEFINED_OBJECT

Functions

Signature

Meaning

1..1
(abstract)

standard_equivalent (): C_COMPLEX_OBJECT

Standard (i.e. C_OBJECT) form of constraint.

4.3.11. C_REFERENCE_OBJECT Class

Class

C_REFERENCE_OBJECT (abstract)

Description

Abstract parent type of C_OBJECT subtypes that are defined by reference.

Inherit

C_OBJECT

4.3.12. ARCHETYPE_SLOT Class

Class

ARCHETYPE_SLOT

Description

Constraint describing a slot' where another archetype can occur.

Inherit

C_REFERENCE_OBJECT

Attributes

Signature

Meaning

0..1

includes: List<ASSERTION>

List of constraints defining other archetypes that could be included at this point.

0..1

excludes: List<ASSERTION>

List of constraints defining other archetypes that cannot be included at this point.

Invariants

Includes_valid: includes /= Void implies not includes.is_empty

Excludes_valid: excludes /= Void implies not excludes.is_empty

Validity: any_allowed xor (includes /= Void or excludes /= Void)

4.3.13. ARCHETYPE_INTERNAL_REF Class

Class

ARCHETYPE_INTERNAL_REF

Description

A constraint defined by proxy, using a reference to an object constraint defined elsewhere in the same archetype.

Note that since this object refers to another node, there are two objects with available occurrences values. The local occurrences value on an ARCHETYPE_INTERNAL_REF should always be used; when setting this from a serialised form, if no occurrences is mentioned, the target occurrences should be used (not the standard default of {1..1}); otherwise the locally specified occurrences should be used as normal. When serialising out, if the occurrences is the same as that of the target, it can be left out.

Inherit

C_REFERENCE_OBJECT

Attributes

Signature

Meaning

1..1

target_path: String

Reference to an object node using archetype path notation.

Invariants

Consistency: not any_allowed

Target_path_valid: target_path /= Void and then not target_path.is_empty

4.3.14. CONSTRAINT_REF Class

Class

CONSTRAINT_REF

Description

Reference to a constraint described in the same archetype, but outside the main constraint structure. This is used to refer to constraints expressed in terms of external resources, such as constraints on terminology value sets.

Inherit

C_REFERENCE_OBJECT

Attributes

Signature

Meaning

1..1

reference: String

Reference to a constraint in the archetype local ontology.

Invariants

Consistency: not any_allowed

5. The Assertion Package

5.1. Overview

Assertions are expressed in archetypes in typed first-order predicate logic (FOL). They are used in two places: to express archetype slot constraints, and to express rules in complex object constraints. In both of these places, their role is to constrain something inside the archetype. Constraints on external resources such as terminologies are expressed in the constraint binding part of the archetype ontology, described in Section 7. The assertion package is illustrated below.

AM aom14.archetype.assertion
Figure 7. aom14.archetype.assertion Package

5.2. Semantics

Archetype assertions are statements which contain the following elements:

  • variables, which are inbuilt, archetype path-based, or external query results;

  • manifest constants of any primitive type, including the date/time types

  • arithmetic operators: +, *, -, /, ^ (exponent), % (modulo division)

  • relational operators: >, <, >=, <=, =, !=, matches

  • boolean operators: not, and, or, xor

  • quantifiers applied to container variables: for_all, exists

The written syntax of assertions is defined in the openEHR ADL document. The package described here is currently designed to allow the representation of a general-purpose binary expression tree, as would be generated by a parser. This may be replaced in the future by a more specific model, if needed.

This relatively simple model of expressions is sufficiently powerful for representing FOL expressions on archetype structures, although it could clearly be more heavily subtyped.

5.3. Class Descriptions

5.3.1. ASSERTION Class

Class

ASSERTION

Description

Structural model of a typed first order predicate logic assertion, in the form of an expression tree, including optional variable definitions.

Attributes

Signature

Meaning

0..1

tag: String

Expression tag, used for differentiating multiple assertions.

0..1

string_expression: String

String form of expression, in case an expression evaluator taking String expressions is used for evaluation.

1..1

expression: EXPR_ITEM

Root of expression tree.

0..1

variables: List<ASSERTION_VARIABLE>

Definitions of variables used in the assertion expression.

Invariants

Tag_valid: tag /= Void implies not tag.is_empty

Expression_valid: expression /= Void and then expression.type.is_equal(“BOOLEAN”)

5.3.2. EXPR_ITEM Class

Class

EXPR_ITEM (abstract)

Description

Abstract parent of all expression tree items.

Attributes

Signature

Meaning

1..1

type: String

Type name of this item in the mathematical sense. For leaf nodes, must be the name of a primitive type, or else a reference model type. The type for any relational or boolean operator will be “Boolean”, while the type for any arithmetic operator, will be “Real” or “Integer”.

5.3.3. EXPR_LEAF Class

Class

EXPR_LEAF

Description

Expression tree leaf item representing one of:

  • a manifest constant of any primitive type;

  • a path referring to a value in the archetype;

  • a constraint;

  • a variable reference.

Inherit

EXPR_ITEM

Attributes

Signature

Meaning

1..1

reference_type: String

Type of reference: “constant”, “attribute”, “function”, “constraint”. The first three are used to indicate the referencing mechanism for an operand. The last is used to indicate a constraint operand, as happens in the case of the right-hand operand of the ‘matches’ operator.

1..1

item: Any

The value referred to; a manifest constant, an attribute path (in the form of a String), or for the right-hand side of a ‘matches’ node, a constraint, often a C_PRIMITIVE_OBJECT.

5.3.4. EXPR_OPERATOR Class

Class

EXPR_OPERATOR (abstract)

Description

Abstract parent of operator types.

Inherit

EXPR_ITEM

Attributes

Signature

Meaning

0..1

precedence_overridden: Boolean

True if the natural precedence of operators is overridden in the expression represented by this node of the expression tree. If True, parentheses should be introduced around the totality of the syntax expression corresponding to this operator node and its operands.

1..1

operator: OPERATOR_KIND

Code of operator.

5.3.5. EXPR_UNARY_OPERATOR Class

Class

EXPR_UNARY_OPERATOR

Description

Unary operator expression node.

Inherit

EXPR_OPERATOR

Attributes

Signature

Meaning

1..1

operand: EXPR_ITEM

Operand node.

5.3.6. EXPR_BINARY_OPERATOR Class

Class

EXPR_BINARY_OPERATOR

Description

Binary operator expression node.

Inherit

EXPR_OPERATOR

Attributes

Signature

Meaning

1..1

left_operand: EXPR_ITEM

Left operand node.

1..1

right_operand: EXPR_ITEM

Right operand node.

5.3.7. ASSERTION_VARIABLE Class

Class

ASSERTION_VARIABLE

Description

Definition of a named variable used in an assertion expression.

Attributes

Signature

Meaning

1..1

name: String

Name of variable.

1..1

definition: String

Formal definition of the variable.

5.3.8. OPERATOR_KIND Enumeration

Enumeration

OPERATOR_KIND

Description

Enumeration type for operator types in assertion expressions.

Attributes

Signature

Meaning

op_eq

Equals operator (= or ==)

op_ne

Not equals operator (!= or /=)

op_le

Less-than or equals operator (<=)

op_lt

Less-than operator (<=)

op_ge

Greater-than or equals operator (>=)

op_gt

Greater-than operator (>)

op_matches

Matches operator (matches or is_in)

op_not

Not logical operator

op_and

And logical operator

op_or

Or logical operator.

op_xor

Xor logical operator

op_implies

Implies logical operator

op_for_all

For-all (universal) quantifier

op_exists

Exists quantifier

op_plus

Arithmetic plus operator (+)

op_minus

Arithmetic minus operator (-)

op_multiply

Arithmetic multiplication operator (*)

op_divide

Arithmetic division operator (/)

op_exponent

Arithmetic exponentiation operator (^)

6. Primitive Package

6.1. Overview

Ultimately any archetype definition will devolve down to leaf node constraints on instances of primitive types. The primitive package, illustrated in the following figure, defines the semantics of constraint on such types.

AM aom14.archetype.constraint model.primitive
Figure 8. aom14.archetype.constraint_model.primitive Package

Most of the types provide at least two alternative ways to represent the constraint; for example the C_DATE type allows the constraint to be expressed in the form of a pattern (defined in the ADL specification) or an Interval<Date>. Note that the interval form of dates is probably only useful for historical date checking (e.g. the date of an antique or a particular batch of vaccine), rather than constraints on future date/times.

6.2. Class Descriptions

6.2.1. C_PRIMITIVE Class

Class

C_PRIMITIVE (abstract)

Description

Parent of types representing constraints on primitive types.

Attributes

Signature

Meaning

0..1

assumed_value: Any

Value to be assumed if none sent in data.

Functions

Signature

Meaning

1..1
(abstract)

default_value (): Any

Generate a default value from this constraint object.

1..1
(abstract)

has_assumed_value (): Boolean

True if there is an assumed value.

1..1
(abstract)

valid_value (
a_value: Any[1]
): Boolean

True if a_value is valid with respect to constraint expressed in concrete instance of this type.

Invariants

Assumed_value_valid: has_assumed_value implies valid_value(assumed_value)

6.2.2. C_BOOLEAN Class

Class

C_BOOLEAN

Description

Constraint on instances of Boolean. Both attributes cannot be set to False, since this would mean that the Boolean value being constrained cannot be True or False.

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

1..1

true_valid: Boolean

True if the value True is allowed.

1..1

false_valid: Boolean

True if the value False is allowed.

0..1
(redefined)

assumed_value: Boolean

The value to assume if this item is not included in data, due to being part of an optional structure.

6.2.3. C_STRING Class

Class

C_STRING

Description

Constraint on instances of STRING.

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

pattern: String

Regular expression pattern for proposed instances of String to match.

0..1

list: List<String>

Set of Strings specifying constraint.

1..1

list_open: Boolean

True if the list is being used to specify the constraint but is not considered exhaustive.

0..1
(redefined)

assumed_value: String

The value to assume if this item is not included in data, due to being part of an optional structure.

Functions

Signature

Meaning

1..1
(effected)

valid_value (
a_value: String[1]
): Boolean

True if a_value is valid with respect to constraint expressed in concrete instance of this type.

6.2.4. C_INTEGER Class

Class

C_INTEGER

Description

Constraint on instances of Integer.

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

list: List<Integer>

Set of Integers specifying constraint.

0..1

range: Interval<Integer>

Range of Integers specifying constraint.

0..1
(redefined)

assumed_value: Integer

The value to assume if this item is not included in data, due to being part of an optional structure.

6.2.5. C_REAL Class

Class

C_REAL

Description

Constraint on instances of Real.

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

list: List<Real>

Set of Reals specifying constraint.

0..1

range: Interval<Real>

Range of Real specifying constraint.

0..1
(redefined)

assumed_value: Real

The value to assume if this item is not included in data, due to being part of an optional structure.

6.2.6. C_DATE Class

Class

C_DATE

Description

ISO 8601-compatible constraint on instances of Date in the form either of a set of validity values, or an actual date range. There is no validity flag for ‘year’, since it must always be by definition mandatory in order to have a sensible date at all. Syntax expressions of instances of this class include “YYYY-??-??” (date with optional month and day).

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

day_validity: VALIDITY_KIND

Validity of day in constrained date.

0..1

month_validity: VALIDITY_KIND

Validity of month in constrained date.

0..1

timezone_validity: VALIDITY_KIND

Validity of timezone in constrained date.

0..1

range: Interval<Iso8601_date>

Interval of Dates specifying constraint.

0..1
(redefined)

assumed_value: Iso8601_date

The value to assume if this item is not included in data, due to being part of an optional structure.

Invariants

Month_validity_optional: month_validity = {VALIDITY_KIND}.optional implies (day_validity = {VALIDITY_KIND}.optional or day_validity = {VALIDITY_KIND}.disallowed)

Month_validity_disallowed: month_validity = {VALIDITY_KIND}.disallowed implies day_validity = {VALIDITY_KIND}.disallowed

Validity_is_range: validity_is_range = (range /= Void)

6.2.7. C_TIME Class

Class

C_TIME

Description

ISO 8601-compatible constraint on instances of Time. There is no validity flag for ‘hour’, since it must always be by definition mandatory in order to have a sensible time at all. Syntax expressions of instances of this class include “HH:??:xx” (time with optional minutes and seconds not allowed).

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

minute_validity: VALIDITY_KIND

Validity of minute in constrained time.

0..1

second_validity: VALIDITY_KIND

Validity of second in constrained time.

0..1

millisecond_validity: VALIDITY_KIND

Validity of millisecond in constrained time.

0..1

timezone_validity: VALIDITY_KIND

Validity of timezone in constrained date.

0..1

range: Interval<Iso8601_time>

Interval of Times specifying constraint.

0..1
(redefined)

assumed_value: Iso8601_time

The value to assume if this item is not included in data, due to being part of an optional structure.

Functions

Signature

Meaning

1..1

validity_is_range (): Boolean

True if validity is in the form of a range; useful for developers to check which kind of constraint has been set.

Invariants

Minute_validity_optional: minute_validity = {VALIDITY_KIND}.optional implies (second_validity = {VALIDITY_KIND}.optional or second_validity = {VALIDITY_KIND}.disallowed)

Minute_validity_disallowed: minute_validity = {VALIDITY_KIND}.disallowed implies second_validity = {VALIDITY_KIND}.disallowed

Second_validity_optional: second_validity = {VALIDITY_KIND}.optional implies (millisecond_validity = {VALIDITY_KIND}.optional or millisecond_validity = {VALIDITY_KIND}.disallowed)

Second_validity_disallowed: second_validity = {VALIDITY_KIND}.disallowed implies millisecond_validity = {VALIDITY_KIND}.disallowed Validity_is_range: validity_is_range = (range /= Void)

6.2.8. C_DATE_TIME Class

Class

C_DATE_TIME

Description

ISO 8601-compatible constraint on instances of Date_Time. There is no validity flag for ‘year’, since it must always be by definition mandatory in order to have a sensible date/time at all. Syntax expressions of instances of this class include “YYYY-MM-DDT??:??:??” (date/time with optional time) and “YYYY-MMDDTHH:MM:xx” (date/time, seconds not allowed).

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

month_validity: VALIDITY_KIND

Validity of month in constrained date.

0..1

day_validity: VALIDITY_KIND

Validity of day in constrained date.

0..1

hour_validity: VALIDITY_KIND

Validity of hour in constrained time.

0..1

minute_validity: VALIDITY_KIND

Validity of minute in constrained time.

0..1

second_validity: VALIDITY_KIND

Validity of second in constrained time.

0..1

millisecond_valdity: VALIDITY_KIND

Validity of millisecond in constrained time.

0..1

timezone_valdity: VALIDITY_KIND

Validity of timezone in constrained date.

0..1

range: Interval<Iso8601_date_time>

Range of Date_times specifying constraint.

0..1
(redefined)

assumed_value: Iso8601_date_time

The value to assume if this item is not included in data, due to being part of an optional structure.

Functions

Signature

Meaning

1..1

validity_is_range (): Boolean

True if validity is in the form of a range; useful for developers to check which kind of constraint has been set.

Invariants

Month_validity_optional:: month_validity = {VALIDITY_KIND}.optional implies (day_validity = {VALIDITY_KIND}.optional or day_validity = {VALIDITY_KIND}.disallowed)

Month_validity_disallowed: month_validity = {VALIDITY_KIND}.disallowed implies day_validity = {VALIDITY_KIND}.disallowed

Day_validity_optional: day_validity = {VALIDITY_KIND}.optional implies (hour_validity = {VALIDITY_KIND}.optional or hour_validity = {VALIDITY_KIND}.disallowed)

Day_validity_disallowed: day_validity = {VALIDITY_KIND}.disallowed implies hour_validity = {VALIDITY_KIND}.disallowed

Hour_validity_optional: hour_validity = {VALIDITY_KIND}.optional implies (minute_validity = {VALIDITY_KIND}.optional or minute_validity = {VALIDITY_KIND}.disallowed)

Hour_validity_disallowed: hour_validity = {VALIDITY_KIND}.disallowed implies minute_validity = {VALIDITY_KIND}.disallowed

Minute_validity_optional: minute_validity = {VALIDITY_KIND}.optional implies (second_validity = {VALIDITY_KIND}.optional or second_validity = {VALIDITY_KIND}.disallowed)

Minute_validity_disallowed: minute_validity = {VALIDITY_KIND}.disallowed implies second_validity = {VALIDITY_KIND}.disallowed

Second_validity_optional: second_validity = {VALIDITY_KIND}.optional implies (millisecond_validity = {VALIDITY_KIND}.optional or millisecond_validity = {VALIDITY_KIND}.disallowed)

Second_validity_disallowed: second_validity = {VALIDITY_KIND}.disallowed implies millisecond_validity = {VALIDITY_KIND}.disallowed

Validity_is_range: validity_is_range = (range /= Void)

6.2.9. C_DURATION Class

Class

C_DURATION

Description

ISO 8601-compatible constraint on instances of Duration. In ISO 8601 terms, constraints might are of the form “PWD” (weeks and/or days), “PDTHMS” (days, hours, minutes, seconds) and so on.

Both range and the constraint pattern can be set at the same time, corresponding to the ADL constraint "PWD/|P0W..P50W|".

As for all of openEHR, two ISO 8601 exceptions are allowed:

  • the ‘W’ (week) designator can be mixed in - the allowed patterns are: P[Y|y][M|m][D|d][T[H|h][M|m][S|s]] and P[W|w];

  • the values used in an interval constraint may be negated, i.e. a leading minus ('-') sign may be used.

Inherit

C_PRIMITIVE

Attributes

Signature

Meaning

0..1

years_allowed: Boolean

0..1

months_allowed: Boolean

True if months are allowed in the constrained Duration.

0..1

weeks_allowed: Boolean

0..1

days_allowed: Boolean

True if days are allowed in the constrained Duration.

0..1

hours_allowed: Boolean

True if hours are allowed in the constrained Duration.

0..1

minutes_allowed: Boolean

True if minutes are allowed in the constrained Duration.

0..1

seconds_allowed: Boolean

0..1

fractional_seconds_allowed: Boolean

True if fractional seconds are allowed in the constrained Duration.

0..1

range: Interval<Iso8601_duration>

Range of Durations specifying constraint.

0..1
(redefined)

assumed_value: Iso8601_duration

The value to assume if this item is not included in data, due to being part of an optional structure.

7. Terminology Package

7.1. Overview

All linguistic and terminological entities in an archetype are represented in the ontology part of an archetype, whose semantics are given in the ontology package, shown below.

AM aom14.archetype.ontology
Figure 9. aom14.archetype.ontology Package

An archetype ontology consists of the following things.

  • A list of terms defined local to the archetype. These are identified by 'atNNNN' codes, and perform the function of archetype node identifiers from which paths are created. There is one such list for each natural language in the archetype. A term 'at0001' defined in English as 'blood group' is an example.

  • A list of external constraint definitions, identified by 'acNNNN' codes, for constraints defined external to the archetype, and referenced using an instance of a CONSTRAINT_REF. There is one such list for each natural language in the archetype. A term 'ac0001' corresponding to 'any term which is-a blood group', which can be evaluated against some external terminology service.

  • Optionally, a set of one or more bindings of term definitions to term codes from external terminologies.

  • Optionally, a set of one or more bindings of the external constraint definitions to external resources such as terminologies.

7.2. Semantics

7.2.1. Specialisation Depth

Any given archetype occurs at some point in a lineage of archetypes related by specialisation, where the depth is reflected by the specialisation_depth attribute. An archetype which is not a specialisation of another has a specialisation_depth of 0. Term and constraint codes introduced in the terminology of specialised archetypes (i.e. which did not exist in the terminology of the parent archetype) are defined in a strict way, using '.' (period) markers. For example, an archetype of specialisation depth 2 will use term definition codes like the following:

  • at0.0.1 - a new term introduced in this archetype, which is not a specialisation of any previous term in any of the parent archetypes;

  • at0001.0.1 - a term which specialises the 'at0001' term from the top parent. An intervening '.0' is required to show that the new term is at depth 2, not depth 1;

  • at0001.1.1 - a term which specialises the term 'at0001.1' from the immediate parent, which itself specialises the term 'at0001' from the top parent.

This systematic definition of codes enables software to use the structure of the codes to more quickly and accurately make inferences about term definitions up and down specialisation hierarchies. Constraint codes on the other hand do not follow these rules, and exist in a flat code space instead.

7.2.2. Term and Constraint Definitions

Local term and constraint definitions are modelled as instances of the class ARCHETYPE_TERM, which is a code associated with a list of name/value pairs. For any term or constraint definition, this list must at least include the name/value pairs for the names "text" and "description". It might also include such things as "provenance", which would be used to indicate that a term was sourced from an external terminology. The attribute term_attribute_names in ARCHETYPE_ONTOLOGY provides a list of attribute names used in term and constraint definitions in the archetype, including "text" and "description", as well as any others which are used in various places.

7.3. Class Descriptions

7.3.1. ARCHETYPE_ONTOLOGY Class

Class

ARCHETYPE_ONTOLOGY

Description

Local ontology of an archetype.

Attributes

Signature

Meaning

1..1

term_codes: List<String>

List of all term codes in the ontology. Most of these correspond to “at” codes in an ADL archetype, which are the node_ids on C_OBJECT descendants. There may be an extra one, if a different term is used as the overall archetype concept from that used as the node_id of the outermost C_OBJECT in the definition part.

1..1

constraint_codes: List<String>

List of all term codes in the ontology. These correspond to the “ac” codes in an ADL archetype, or equivalently, the CONSTRAINT_REF.reference values in the archetype definition.

1..1

parent_archetype: ARCHETYPE

Archetype which owns this terminology.

0..1

terminologies_available: List<String>

List of terminologies to which term or constraint bindings exist in this terminology.

1..1

specialisation_depth: Integer

Specialisation depth of this archetype. Unspecialised archetypes have depth 0, with each additional level of specialisation adding 1 to the specialisation_depth.

1..1

term_attribute_names: List<String>

Functions

Signature

Meaning

1..1

has_language (
a_lang: String[1]
): Boolean

True if terminology ‘a_terminology’ is present in archetype ontology.

1..1

has_terminology (
a_terminology_id: String[1]
): Boolean

True if terminology `a_terminology' is present in archetype ontology.

1..1

has_term_code (
a_code: String[1]
): Boolean

True if term_codes has a_code.

1..1

has_constraint_code (
a_code: String[1]
): Boolean

True if constraint_codes has a_code.

1..1

term_definition (
a_lang: String[1],
a_code: String[1]
): ARCHETYPE_TERM

Pre: has_language (a_lang)
Pre2: has_term_code (a_code)

Term definition for a code, in a specified language.

1..1

constraint_definition (
a_code: String[1],
a_lang: String[1]
): ARCHETYPE_TERM

Pre: has_language (a_lang)
Pre_2: has_constraint_code (a_code)

Constraint definition for a code, in a specified language.

1..1

term_binding (
a_terminology: String[1],
a_code: String[1]
): CODE_PHRASE

Pre: has_term_binding (a_terminology_id, a_code)

Binding of constraint corresponding to a_code in target external terminology a_terminology_id, as a string, which is usually a formal query expression.

1..1

constraint_binding (
a_terminology_id: String[1],
a_code: String[1]
): String

Binding of constraint corresponding to a_code in target external terminology a_terminology_id, as a string, which is usually a formal query expression.

Invariants

Original_language_validity: code_set (Code_set_id_languages).has_concept_id (original_language)

concept_code_validity: id_codes.has (concept_code)

Term_bindings_validity: bindings /= void implies not bindings.is_empty

Parent_archetype_valid: parent_archetype.ontology = Current

7.3.2. ARCHETYPE_TERM Class

Class

ARCHETYPE_TERM

Description

Representation of any coded entity (term or constraint) in the archetype ontology.

Attributes

Signature

Meaning

1..1

code: String

Code of this term.

0..1

items: Hash<String, String>

Hash of keys (“text”, “description” etc) and corresponding values. Hash of keys ("text", "description" etc) and corresponding values.

Functions

Signature

Meaning

0..1

keys (): List<String>

List of all keys used in this term.

Invariants

Code_valid: not code.is_empty

Appendix A: Domain-specific Extension Example

A.1. Overview

Domain-specific classes can be added to the archetype constraint model by inheriting from the class C_DOMAIN_TYPE. This section provides an example of how domain-specific constraint classes are added to the archetype model. Actual additions to the AOM for openEHR are documented in the openEHR Archetype Profile (oAP) specification.

A.2. Scientific/Clinical Computing Types

The following figure shows the general approach, used to add constraint classes for commonly used concepts in scientific and clinical computing, such as 'ordinal' (used heavily in medicine, particularly in pathology testing), 'coded term' (also heavily used in clinical computing) and 'quantity', a general scientific measurement concept. The constraint types shown are C_ORDINAL, C_CODED_TEXT and C_QUANTITY which can optionally be used in archetypes to replace the default constraint semantics represented by the use of instances of C_OBJECT / C_ATTRIBUTE to constrain ordinals, coded terms and quantities. The following model is intended only as an example, and does not try to define any normative semantics of the particular constraint types shown.

AM aom14.openehr archetype profile
Figure 10. aom14.openehr_archetype_profile package

A.3. Class Descriptions

A.3.1. C_ORDINAL Class

Class

C_ORDINAL

Description

Constrainer class for Ordinal data.

Inherit

C_DOMAIN_TYPE

Attributes

Signature

Meaning

0..1

list: List<ORDINAL>

Value set of allowed Ordinals in the constraint.

A.3.2. ORDINAL Class

Class

ORDINAL

Description

Constrainer object representing a single Ordinal value.

Attributes

Signature

Meaning

1..1

symbol: CODE_PHRASE

Terminology code providing the Ordinal’s symbol.

1..1

value: Integer

Ordinal value.

A.3.3. C_QUANTITY Class

Class

C_QUANTITY

Description

Constrainer class for Quantity data.

Inherit

C_DOMAIN_TYPE

Attributes

Signature

Meaning

1..1

property: String

Name of physical property for Quantities being constrained.

0..1

list: List<C_QUANTITY_ITEM>

Value set of allowed individual Quantity item constraints in this Quantity constraint.

A.3.4. C_QUANTITY_ITEM Class

Class

C_QUANTITY_ITEM

Description

Constrainer class for a single Quantity.

Attributes

Signature

Meaning

1..1

magnitude: Interval<Real>

Quantity magnitude constraint.

0..1

units: String

Optional units constraint.

A.3.5. C_CODED_TEXT Class

Class

C_CODED_TEXT

Description

Constrainer class for Coded text data.

Inherit

C_DOMAIN_TYPE

Attributes

Signature

Meaning

1..1

terminology: String

Terminology identifier.

0..1

code_list: List<String>

Optional list of codes from the terminology. No list means any code from the terminology is allowed.

0..1

reference: String

Appendix B: Using Archetypes with Diverse Reference Models

B.1. Overview

The archetype model described in this document can be used with any reference model which is expressed in UML or a similar object-oriented formalism. It can also be used with E/R models. The following section describes is use a number of reference models used in clinical computing.

B.2. Clinical Computing Use

To Be Continued:

  • data types

  • class naming

  • domain archetype semantics versus LCD semantics of exchange models

  • mapping from C_DOMAIN_TYPE subtypes into various RMs

References

Beale, T. (2000). Archetypes: Constraint-based Domain Models for Future-proof Information Systems. Retrieved from https://www.openehr.org/publications/archetypes/archetypes_beale_web_2000.pdf

Beale, T. (2002). Archetypes: Constraint-based Domain Models for Future-proof Information Systems. In K. Baclawski & H. Kilov (Eds.), Eleventh OOPSLA Workshop on Behavioral Semantics: Serving the Customer (pp. 16–32). Northeastern University, Boston. Retrieved from https://www.openehr.org/publications/archetypes/archetypes_beale_oopsla_2002.pdf

Rector, A. (2000). Clinical Terminology: Why Is It So Hard? Methods of information in medicine, 38, 239–52.