Archetype Object Model 1.4 (AOM1.4)
| Issuer: openEHR Specification Program | |
|---|---|
Release: AM Release-2.0.6 |
Status: STABLE |
Revision: [latest_issue] |
Date: [latest_issue_date] |
Keywords: EHR, ADL, AOM, health records, archetypes, constraint language, 13606 |
|
| © 2004 - 2021 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 |
|
Support |
Issues: Problem Reports |
Amendment Record
| Issue | Details | Raiser, Implementer | Completed |
|---|---|---|---|
R E L E A S E 2.0.6 |
|||
Add Appendix C, containing UML diagrams for RM dependencies. |
D Boscá |
||
SPECBASE-4. Change order of type parameters in |
D Boscá |
13 Apr 2016 |
|
R E L E A S E 1.0.2 |
|||
1.0.2 |
SPEC-257. Correct minor typos and clarify text. Correct reversed definitions of |
C Ma, |
20 Nov 2008 |
SPEC-251. Allow both pattern and interval constraint on Duration in Archetypes. Add pattern attribute to |
S Heard |
||
R E L E A S E 1.0.1 |
|||
1.0.1 |
D Lloyd, |
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 |
R Chen |
||
SPEC-233: Define semantics for |
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 |
||
R E L E A S E 1.0 |
|||
1.0 |
T Beale |
10 Nov 2005 |
|
R E L E A S E 0.96 |
|||
0.6 |
SPEC-134. Correct numerous documentation errors in AOM. Including cut and paste error in |
D Lloyd |
20 Jun 2005 |
SPEC-142. Update ADL grammar to support assumed values. Changed |
S Heard, |
||
SPEC-146: Alterations to am.archetype.description from CEN MetaKnow |
D Kalra |
||
SPEC-138. Archetype-level assertions. |
T Beale |
||
SPEC-157. Fix names of |
T Beale |
||
R E L E A S E 0.95 |
|||
0.5.1 |
Corrected documentation error - return type of |
D Lloyd |
20 Jan 2005 |
0.5 |
SPEC-110. Update ADL document and create AOM document.
Initial Writing. Taken from ADL document 1.2draft B. |
T Beale |
10 Nov 2004 |
Acknowledgements
Primary Author
-
Thomas Beale, Ocean Informatics UK; openEHR Architecture Review Board (ARB)
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.
1.2. Related Documents
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/Release-2.0.6/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 archteype 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 technical mailing list.
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 [1], [2]. 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.
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 : Stringto theARCHETYPEclass; -
changed name of
ARCHETYPE.concept_codeattribute toconcept.
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 in Figure Figure 2. It is shown in the context of the openEHR am.archetype packages.
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.2 Support IM (assumed_types and identifiers packages), a small number of the openEHR Data Types (openEHR Release 1.0.2 Data Types IM), and the resource package from the openEHR Release 1.0.2 Common IM. These dependencies are shown for convenience in the Appendix C 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).
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 nonprimitive 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-
an 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 typenames 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. [3] 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 'substitubility', 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
It 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 a 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.
A utility class, VALIDITY_KIND is also included in the Archetype package. This class contains one integer attribute and three constant definitions, and is intended to be used as the type of any attribute in this constraint model whose value is logically 'mandatory', 'optional', or 'disallowed'. It is used in this model in the classes C_DATE, C_TIME and C_DATE_TIME.
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
definition: |
Root node of the definition of this archetype. |
1..1 |
ontology: |
The ontology of the archetype. |
0..1 |
adl_version: |
ADL version if archetype was read in from an ADL sharable archetype. |
1..1 |
archetype_id: |
Multi-axial identifier of this archetype in archetype space. |
0..1 |
uid: |
OID identifier of this archetype. |
1..1 |
concept: |
The normative meaning of the archetype as a whole, expressed as a local archetype code, typically “at0000”. |
0..1 |
parent_archetype_id: |
Identifier of the specialisation parent of this archetype. |
0..1 |
invariants: |
Invariant statements about this object. Statements are expressed in first order predicate logic, and usually refer to at least two attributes. |
Functions |
Signature |
Meaning |
concept_name ( |
The concept name of the archetype in language a_lang; corresponds to the term definition of the concept attribute in the archetype ontology. |
|
physical_paths (): |
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. |
|
logical_paths ( |
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. |
|
specialisation_depth (): |
Specialisation depth of this archetype; larger than 0 if this archetype has a parent. Derived from terminology.specialisation_depth. |
|
is_specialised (): |
True if this archetype is a specialisation of another. |
|
is_valid (): |
True if the archetype is valid overall; various tests should be used, including checks on node_ids, internal references, and constraint references. |
|
node_ids_valid (): |
True if every node_id found on a C_OBJECT node is found in ontology.term_codes. |
|
previous_version (): |
Version of predecessor archetype of this archetype, if any. |
|
internal_references_valid (): |
True if every ARCHETYPE_INTERNAL_REF. target_path refers to a legitimate node in the archetype definition. |
|
constraint_references_valid (): |
True if every CONSTRAINT_REF.reference found on a C_OBJECT node in the archetype definition is found in ontology.constraint_codes. |
|
short_concept_name (): |
The short concept name of the archetype extracted from the archetype_id. |
|
version (): |
||
Invariants |
Inv_concept_valid: |
|
Inv_specialisation_validity: |
||
Inv_invariants_valid: |
||
Inv_uid_validity: |
||
Inv_version_validity: |
||
Inv_description_valid: |
||
Inv_original_language_valid: |
||
3.2.2. VALIDITY_KIND Enumeration
Enumeration |
VALIDITY_KIND |
|
|---|---|---|
Description |
An enumeration of three values that may commonly occur in constraint models. Use as the type of any attribute within this model, which expresses constraint on some attribute in a class in a reference model. For example to indicate validity of Date/Time fields. |
|
Attributes |
Signature |
Meaning |
mandatory |
Constant to indicate mandatory presence of something. |
|
optional |
Constant to indicate optional presence of something. |
|
prohibited |
Constant to indicate disallowed presence of something. |
|
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 a 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.
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 the figure 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 subnodes 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.
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_idis a 'term code' in theontologysection.
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 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 archteype-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 aproach. 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_TERMse.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 appopriate 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 |
(abstract) |
is_subset_of ( |
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. |
(abstract) |
is_valid (): |
|
path (): |
Path of this node relative to root of archetype. |
|
has_path ( |
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
rm_attribute_name: |
Reference model attribute within the enclosing type represented by a C_OBJECT. |
1..1 |
existence: |
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: |
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 |
any_allowed (): |
True if any value (i.e. instance) of the reference model attribute represented by this C_ATTIRBUTE is allowed. |
|
Invariants |
Rm_attribute_name_valid: |
|
Existence_set: |
||
Children_validity: |
||
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 |
|
|
Functions |
Signature |
Meaning |
alternatives (): |
List of alternative constraints for the single child of this attribute within the data. |
|
4.3.4. C_MULTIPLE_ATTRIBUTE Class
Class |
C_MULTIPLE_ATTRIBUTE |
|
|---|---|---|
Description |
Concrete model of constraint on multiply-valued (ie. container) attribute node. |
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
1..1 |
cardinality: |
Cardinality of this attribute constraint, if it constraints a container attribute. |
Functions |
Signature |
Meaning |
members (): |
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. |
|
Invariants |
Members_valid: |
|
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: |
The interval of this cardinality. |
1..1 |
is_ordered: |
True if the members of the container attribute to which this cardinality refers are ordered. |
1..1 |
is_unique: |
True if the members of the container attribute to which this cardinality refers are unique. |
Functions |
Signature |
Meaning |
is_bag (): |
True if the semantics of this cardinality represent a bag, i.e. unordered, non-unique membership. |
|
is_list (): |
True if the semantics of this cardinality represent a list, i.e. ordered, non-unique membership. |
|
is_set (): |
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
rm_type_name: |
Reference model type that this node corresponds to. |
1..1 |
occurrences: |
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: |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
assumed_value: |
Value to be assumed if none sent in data. |
Functions |
Signature |
Meaning |
(abstract) |
valid_value ( |
True if a_value is valid with respect to constraint expressed in concrete instance of this type. |
(abstract) |
prototype_value (): |
Generate a prototype value from this constraint object. |
has_assumed_value (): |
True if there is an assumed value. |
|
(abstract) |
default_value (): |
Generate a default value from this constraint object. |
(abstract) |
any_allowed (): |
True if any value of the reference model type being constrained is allowed. Redefine in descendants. |
Invariants |
Assumed_value_valid: |
|
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
attributes: |
List of constraints on attributes of the reference model type represented by this object. |
Functions |
Signature |
Meaning |
(effected) |
any_allowed (): |
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
item: |
Object actually defining the constraint. |
Functions |
Signature |
Meaning |
(effected) |
any_allowed (): |
True if any value of the type being constrained in item is allowed. |
Invariants |
Item_valid: |
|
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 |
|
|
Functions |
Signature |
Meaning |
(abstract) |
standard_equivalent (): |
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 |
|
|
4.3.12. ARCHETYPE_SLOT Class
Class |
ARCHETYPE_SLOT |
|
|---|---|---|
Description |
Constraint describing a slot' where another archetype can occur. |
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
0..1 |
includes: |
List of constraints defining other archetypes that could be included at this point. |
0..1 |
excludes: |
List of constraints defining other archetypes that cannot be included at this point. |
Invariants |
Includes_valid: |
|
Excludes_valid: |
||
Validity: |
||
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
target_path: |
Reference to an object node using archetype path notation. |
Invariants |
Consistency: |
|
Target_path_valid: |
||
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
reference: |
Reference to a constraint in the archetype local ontology. |
Invariants |
Consistency: |
|
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 Figure [terminology_package]. The assertion package is illustrated below.
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: |
Expression tag, used for differentiating multiple assertions. |
0..1 |
string_expression: |
String form of expression, in case an expression evaluator taking String expressions is used for evaluation. |
1..1 |
expression: |
Root of expression tree. |
0..1 |
variables: |
Definitions of variables used in the assertion expression. |
Invariants |
Tag_valid: |
|
Expression_valid: |
||
5.3.2. EXPR_ITEM Class
Class |
EXPR_ITEM (abstract) |
|
|---|---|---|
Description |
Abstract parent of all expression tree items. |
|
Attributes |
Signature |
Meaning |
1..1 |
type: |
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:
|
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
1..1 |
reference_type: |
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: |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
precedence_overridden: |
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: |
Code of operator. |
5.3.5. EXPR_UNARY_OPERATOR Class
Class |
EXPR_UNARY_OPERATOR |
|
|---|---|---|
Description |
Unary operator expression node. |
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
1..1 |
operand: |
Operand node. |
5.3.6. EXPR_BINARY_OPERATOR Class
Class |
EXPR_BINARY_OPERATOR |
|
|---|---|---|
Description |
Binary operator expression node. |
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
1..1 |
left_operand: |
Left operand node. |
1..1 |
right_operand: |
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: |
Name of variable. |
1..1 |
definition: |
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.
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: |
Value to be assumed if none sent in data. |
Functions |
Signature |
Meaning |
(abstract) |
default_value (): |
Generate a default value from this constraint object. |
(abstract) |
has_assumed_value (): |
True if there is an assumed value. |
(abstract) |
valid_value ( |
True if a_value is valid with respect to constraint expressed in concrete instance of this type. |
Invariants |
Assumed_value_valid: |
|
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 |
|
|
Attributes |
Signature |
Meaning |
1..1 |
true_valid: |
True if the value True is allowed. |
1..1 |
false_valid: |
True if the value False is allowed. |
0..1 |
assumed_value: |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
pattern: |
Regular expression pattern for proposed instances of String to match. |
0..1 |
list: |
Set of Strings specifying constraint. |
1..1 |
list_open: |
True if the list is being used to specify the constraint but is not considered exhaustive. |
0..1 |
assumed_value: |
The value to assume if this item is not included in data, due to being part of an optional structure. |
Functions |
Signature |
Meaning |
(effected) |
valid_value ( |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
list: |
Set of Integers specifying constraint. |
0..1 |
range: |
Range of Integers specifying constraint. |
0..1 |
assumed_value: |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
list: |
Set of Reals specifying constraint. |
0..1 |
range: |
Range of Real specifying constraint. |
0..1 |
assumed_value: |
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
day_validity: |
Validity of day in constrained date. |
0..1 |
month_validity: |
Validity of month in constrained date. |
0..1 |
timezone_validity: |
Validity of timezone in constrained date. |
0..1 |
range: |
Interval of Dates specifying constraint. |
0..1 |
assumed_value: |
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_disallowed: |
||
Validity_is_range: |
||
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
minute_validity: |
Validity of minute in constrained time. |
0..1 |
second_validity: |
Validity of second in constrained time. |
0..1 |
millisecond_validity: |
Validity of millisecond in constrained time. |
0..1 |
timezone_validity: |
Validity of timezone in constrained date. |
0..1 |
range: |
Interval of Times specifying constraint. |
0..1 |
assumed_value: |
The value to assume if this item is not included in data, due to being part of an optional structure. |
Functions |
Signature |
Meaning |
validity_is_range (): |
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_disallowed: |
||
Second_validity_optional: |
||
Second_validity_disallowed: |
||
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 |
|
|
Attributes |
Signature |
Meaning |
0..1 |
month_validity: |
Validity of month in constrained date. |
0..1 |
day_validity: |
Validity of day in constrained date. |
0..1 |
hour_validity: |
Validity of hour in constrained time. |
0..1 |
minute_validity: |
Validity of minute in constrained time. |
0..1 |
second_validity: |
Validity of second in constrained time. |
0..1 |
millisecond_valdity: |
Validity of millisecond in constrained time. |
0..1 |
timezone_valdity: |
Validity of timezone in constrained date. |
0..1 |
range: |
Range of Date_times specifying constraint. |
0..1 |
assumed_value: |
The value to assume if this item is not included in data, due to being part of an optional structure. |
Functions |
Signature |
Meaning |
validity_is_range (): |
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_disallowed: |
||
Day_validity_optional: |
||
Day_validity_disallowed: |
||
Hour_validity_optional: |
||
Hour_validity_disallowed: |
||
Minute_validity_optional: |
||
Minute_validity_disallowed: |
||
Second_validity_optional: |
||
Second_validity_disallowed: |
||
Validity_is_range: |
||
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. In official ISO 8601:2004, the ‘W’ (week) designator cannot be mixed in; allowing it is an openEHR-wide exception. Both range and the constraint pattern can be set at the same time, corresponding to the ADL constraint PWD/|P0W..P50W|. |
|
Inherit |
|
|
Attributes |
Signature |
Meaning |
0..1 |
years_allowed: |
|
0..1 |
months_allowed: |
True if months are allowed in the constrained Duration. |
0..1 |
weeks_allowed: |
|
0..1 |
days_allowed: |
True if days are allowed in the constrained Duration. |
0..1 |
hours_allowed: |
True if hours are allowed in the constrained Duration. |
0..1 |
minutes_allowed: |
True if minutes are allowed in the constrained Duration. |
0..1 |
seconds_allowed: |
|
0..1 |
fractional_seconds_allowed: |
True if fractional seconds are allowed in the constrained Duration. |
0..1 |
range: |
Range of Durations specifying constraint. |
0..1 |
assumed_value: |
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.
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 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 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 which owns this terminology. |
0..1 |
terminologies_available: |
List of terminologies to which term or constraint bindings exist in this terminology. |
1..1 |
specialisation_depth: |
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: |
|
Functions |
Signature |
Meaning |
has_language ( |
True if terminology ‘a_terminology’ is present in archetype ontology. |
|
has_terminology ( |
True if terminology `a_terminology' is present in archetype ontology. |
|
has_term_code ( |
True if term_codes has a_code. |
|
has_constraint_code ( |
True if constraint_codes has a_code. |
|
term_definition ( |
Term definition for a code, in a specified language. |
|
constraint_definition ( |
Constraint definition for a code, in a specified language. |
|
term_binding ( |
Binding of constraint corresponding to a_code in target external terminology a_terminology_id, as a string, which is usually a formal query expression. |
|
constraint_binding ( |
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: |
|
concept_code_validity: |
||
Term_bindings_validity: |
||
Parent_archetype_valid: |
||
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: |
Code of this term. |
0..1 |
items: |
Hash of keys (“text”, “description” etc) and corresponding values. Hash of keys ("text", "description" etc) and corresponding values. |
Functions |
Signature |
Meaning |
keys (): |
List of all keys used in this term. |
|
Invariants |
Code_valid: |
|
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 meansurement 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.
Appendix B: Using Archetypes with Diverse Reference Models
Appendix C: Reference Model Dependencies
The following shows Reference Model extracts relevant to the AOM.
C.1. RM 1.0.2 support.assumed_types package
C.2. RM 1.0.2 support.identification package
C.6. RM 1.0.2 common.resource package
C.6.2. TRANSLATION_DETAILS Class
Class |
TRANSLATION_DETAILS |
|
|---|---|---|
Description |
Class providing details of a natural language translation. |
|
Attributes |
Signature |
Meaning |
1..1 |
language: |
Language of the translation. |
1..1 |
author: |
Translator name and other demographic details. |
0..1 |
accreditaton: |
Accreditation of translator, usually a national translator’s registration or association membership id. |
0..1 |
other_details: |
Any other meta-data. |
Invariants |
Language_valid: |
|
C.6.3. RESOURCE_DESCRIPTION Class
Class |
RESOURCE_DESCRIPTION |
|
|---|---|---|
Description |
Defines the descriptive meta-data of a resource. |
|
Attributes |
Signature |
Meaning |
1..1 |
original_author: |
Original author of this resource, with all relevant details, including organisation. |
0..1 |
other_contributors: |
Other contributors to the resource, probably listed in name <email> form. |
1..1 |
lifecycle_state: |
Lifecycle state of the resource, typically including states such as: initial, submitted, experimental, awaiting_approval, approved, superseded, obsolete. |
0..1 |
resource_package_uri: |
URI of package to which this resource belongs. |
0..1 |
other_details: |
Additional non language-senstive resource meta-data, as a list of name/value pairs. |
1..1 |
parent_resource: |
Reference to owning resource. |
1..1 |
details: |
Details of all parts of resource description that are natural language-dependent, keyed by language code. |
Invariants |
Original_author_valid: |
|
Lifecycle_state_valid: |
||
Details_valid: |
||
Language_valid: |
||
Parent_resource_valid: |
||
C.6.4. RESOURCE_DESCRIPTION_ITEM Class
Class |
RESOURCE_DESCRIPTION_ITEM |
|
|---|---|---|
Description |
Language-specific detail of resource description. When a resource is translated for use in another language environment, each RESOURCE_DESCRIPTION_ITEM needs to be copied and translated into the new language. |
|
Attributes |
Signature |
Meaning |
1..1 |
language: |
The localised language in which the items in this description item are written. Coded from openEHR Code Set languages . |
1..1 |
purpose: |
Purpose of the resource. |
0..1 |
keywords: |
Keywords which characterise this resource, used e.g. for indexing and searching. |
0..1 |
use: |
Description of the uses of the resource, i.e. contexts in which it could be used. |
0..1 |
misuse: |
Description of any misuses of the resource, i.e. contexts in which it should not be used. |
0..1 |
copyright: |
Optional copyright statement for the resource as a knowledge resource. |
0..1 |
original_resource_uri: |
URIs of original clinical document(s) or description of which resource is a formalisation, in the language of this description item; keyed by meaning. |
0..1 |
other_details: |
Additional language-senstive resource metadata, as a list of name/value pairs. |
Invariants |
Language_valid: |
|
Purpose_valid: |
||
Use_valid: |
||
misuse_valid: |
||
copyright_valid: |
||