cADL - Constraint ADL

The following keywords are recognised in cADL:

Symbol equivalents for some of the above are given in the following table.

cADL constraints are written in a block-structured style, similar to block-structured programming languages like C. A typical block resembles the following (the recurring pattern /.+/ is a regular expression matching a non-empty string):

In the above, each block is introduced by an identifier (shown in blue) from an information model. The identifiers alternate between type-names (upper case in this example, or 'camel' case) and type attribute names (lower case). Here, 'type-name' indicates the name of a type, which may be a class name, or may be a derived generic type name. An 'attribute name' is the name of an attribute in the inheritance-flattened form of a type, i.e. may be be defined in an ancestor class of the class to which the type-name most directly corresponds.

Blocks introduced by a type name are known as object blocks or object nodes, while those introduced by an attribute name are attribute blocks or attribute nodes.

The block identifier is followed by the ∈ operator (equivalent text keyword: matches or is_in ) followed by an open brace, is the start of a 'block', which continues until the closing matching brace (normally visually indented to match the line at the beginning of the block).

An object block or node can be thought of as a constraint matching a set of instances conforming to the type which introduces the block.

The example above expresses a constraint on an instance of the type PERSON ; the constraint is expressed by everything inside the PERSON block. The two blocks at the next level define constraints on properties of PERSON , in this case name and addresses. Each of these constraints is expressed in turn by the next level containing constraints on further types, and so on. The general structure is therefore a recursive nesting of constraints on types, followed by constraints on attributes (of that type), followed by types (being the types of the attribute under which it appears) until leaf nodes are reached.

In a cADL text, comments are defined as follows:

Identifiers in cADL texts correspond to entities - types and attributes - in an information model. The latter is typically an object-oriented model, but may just as easily be an entity-relationship model or any other typed model of information. A UML model compatible with the example above is shown in UML Model of Person. Note that there can be more than one model compatible with a given fragment of cADL syntax, and in particular, there are usually more properties and classes in the reference model than are mentioned in the cADL constraints. In other words, a cADL text includes constraints only for those parts of a model that are useful or meaningful to constrain.

Constraints expressed in cADL cannot invalidate those from the information model. For example, the PERSON.family_name attribute is mandatory in the model in the above PERSON model, so it is not valid to express a constraint allowing the attribute to be optional. In general, a cADL archetype can only further constrain an existing information model. However, it must be remembered that for very generic models consisting of only a few classes and a lot of optionality, this rule is not so much a limitation as a way of adding meaning to information. Thus, for a demographic information model which has only the types PARTY and PERSON, one can write cADL which defines the concepts of entities such as COMPANY , EMPLOYEE , PROFESSIONAL , and so on, in terms of constraints on the types available in the information model.

This general approach can be used to express constraints for instances of any information model. The following example shows how to express a constraint on the value property of an ELEMENT class to be a DV_QUANTITY with a suitable range for expressing blood pressure.

In this specification, the terms underlying information model and reference model are equivalent and refer to the information model on which a cADL text is based.

Node identifier codes appear after all type identifiers in a cADL text. They take the form of an 'id-code' in brackets, e.g. [id3]. The id-code of a root object in a structure is always id1, or for specialised archetypes, id1.1, id1.1.1 etc. The rules and use of node identifiers is described in more detail below.

The matches or is_in operator deserves special mention, since it is the key operator in cADL. This operator can be understood mathematically as set membership. When it occurs between an identifier and a block delimited by braces, the meaning is: the set of values allowed for the entity referred to by the name (either an object, or parts of an object - attributes) is specified between the braces. What appears between any matching pair of braces can be thought of as a specification for a set of values. Since blocks can be nested, this approach to specifying values can be understood in terms of nested sets, or in terms of a value space for instances of a type. Thus, in the following example, the matches operator links the name of an entity to a linear value space (i.e. a list), consisting of all words ending in 'ion'.

The following example links the name of a type XXX with a hierarchical value space.

The meaning of the syntax above is: data matching the constraints conssists of an instance of type XXX , or any subtype allowed by the underlying information model, for which the value of attribute aaa is of type YYY , or any subtype allowed by the underlying information model, and so on, recursively until leaf level constraints are reached.

Occasionally the matches operator needs to be used in the negative, usually at a leaf block. Any of the following can be used to constrain the value space of the attribute aaa to any number except 5:

The choice of whether to use matches or is_in is a matter of taste and background; those with a mathematical background will probably prefer is_in , while those with a data processing background may prefer matches .

cADL is completely independent of all natural languages. The only potential exception is where constraints include literal values from some language, and this is easily and routinely avoided by the use of separate language and terminology definitions, as used in ADL archetypes. However, for the purposes of readability, comments in English have been included in this document to aid the reader. In real cADL documents, comments are generated from the archetype terminology in the language of the locale.

In any information model, attributes are either single-valued or multiply-valued, i.e. of a generic container type such as List<Contact> . Both have existence , while multiply-valued attributes also have cardinality.

A single-valued attribute is an attribute whose type as declared in the underlying class model is of a single object type rather than a container type such as a list or set. Single-valued attributes can be constrained with a single object constraint as shown in the following example.

Multiple alternative object constraints can also be defined, using a number of sibling blocks, as shown in the following example. Each block defines an alternative constraint, only one of which needs to be matched by the data.

Here the occurrences of both DV_QUANTITY constraints is not stated, leading to the result that only one DV_QUANTITY instance can appear in runtime data, matching either one of the constraints.

There are two cases where it is useful to state a completely open, or 'any', constraint. The first is when it is desired to override the existence or cardinality of a property, such as in the following:

In the above, no further matches {} part is required in the statement, since no more constraints are to be stated.

The second use of "any" as a constraint value is for types, such as in the following:

The meaning of this constraint is that in the data at runtime, the value property of ELEMENT must be of type DV_QUANTITY , but can have any value internally. This is most useful for constraining objects to be of a certain type, without further constraining value, and is especially useful where the information model contains subtyping, and there is a need to restrict data to be of certain subtypes in certain contexts.

All cADL object constraints state a type name from an underlying reference model. Lexically speaking, this may be an abstract class name, a concrete class name or a generic type name, if the RM in question supports generic (template) types. In the latter case, the type name is constructed from RM class names, according to the standard generic type name syntax used in UML and mainstream languages such as C++, Java, C# and so on, i.e. using the characters <>, , and space(s). Additionally, matching of type names is case-insensitive, and whitespace is ignored. Thus, "SECTION" in the archetype is assumed to match a data instance whose type is SECTION or Section; "Interval<Quantity>" in the archetype is assumed to match a data instance whose RM type is INTERVAL <QUANTITY>.

In semantic terms, the data item conforming to the archetype constraint can be of any concrete type from the reference model (i.e. class name or derived generic type as above) that conforms to the type mentioned in the constraint, i.e. the same type if it is concrete, or any subtype. Correctly evaluating data/archetype conformance is up to tools to implement, and requires access to a formal description of the reference model.

The precise specification of RM type matching is given in the section Rm_type_name and reference model type matching of the AOM2 specification.

It is possible to define a constraint structure at a certain point to be the same as a structure defined elsewhere in the archetype, rather than copying the desired structure. This is achieved using a proxy constraint object, using the following syntax:

This statement defines a node of type TYPE, whose definition is the same as the one found at path archetype_path. The type mentioned in the use_node reference must always be the same type as the referenced type.

The path must not be in the parent path of the proxy object itself, but may be a sibling of the proxy object. The sibling case is a special case, and the meaning of the proxy constraint is that the target object’s children should be re-used, but not the target itself (since that would illegally create two siblings with the same identifier). The general case is that the proxy object and target object locations are different, and the meaning is that the proxy object is logically replaced by a deep copy of the target object. (In theory the sibling case could be banned, and proxies defined one level further down with targets of the children of the originally intended target, but this creates inconvenience for the archetype author, and can easily be dealt with in tools).

Occurrences from the target are also assumed, or may be explicitly overridden:

Proxy objects provide an internal reuse mechanism. Specialised archetypes may redefine structures on such nodes as if they had been defined inline. This is described in more detail in [Internal Reference (Proxy Object) Redefinition].

The following example shows the definitions of the ADDRESS nodes for phone, fax and email for a home CONTACT being reused for a work CONTACT .

The following example shows the occurrences being overridden in the referring node, to enable the specification for 'phone' to be re-used, but with a different occurrences constraint.

Another kind of reference in an archetype is to another archetype. There are two ways this can be done: using a direct reference, and using an archetype 'slot'. The first is used when the need is to refer to one specific archetype (or to a template from another template), while the second is a constraint that allows for various archetypes matching specified criteria to be used. The slot concept is described in the next section.

Direct references, or external references as they will be denoted here occur for two main reasons: re-use and templating. In the first case, an archetype has originally been built using inline constraints when it is discovered that another archetype contains the same or very similar inline constraints at a similar point. As would be normal in software design, a refactoring exercise is conducted that results in the common part being created as its own, new archetype, and both original archetypes 'referring' to it. They do this using an external reference, which has syntax of the form:

In the above, the archetype_id is included with the usual archetype node identifier (id-code). The usual occurrence constraints can be applied at the end.

The following example shows sections of two parent archetypes both referring to the same child archetype. The first section is from an openEHR INSTRUCTION archetype to do with a medication order.

This section is from an openEHR ACTION archetype defining medication administration actions.

Each of these archetypes refers to the openEHR ITEM_TREE archetype openEHR-EHR-ITEM_TREE.medication.v1 , which is a normal archetype describing medication.

Following the standard object-oriented semantics of type substitutability, and also the ontological subsumption notion, specialisations of the referenced archetype (including templates) are also valid substitutions at design or runtime. At design time, this takes the form of a redefinition, e.g.:

where the 'vaccine' archetype is a specialisation of the 'medication' archetype. Redefinitions of this kind are described in more detail in [External Reference Redefinition].

External references can of course also be defined under container attributes.

The second use of external references is typically in templates, to specify an archetype or sub-template of a template for an attribute where no slot has been defined. This use is described in [Unconstrained Attributes].

At any point in a cADL definition, a constraint can be defined that allows other archetypes to be used, rather than defining the desired constraints inline. This is known as an archetype 'slot', i.e. a connection point whose allowable 'fillers' are constrained by a set of statements, written in the {openehr_rules}[openEHR rules language].

An archetype slot is introduced with the keyword allow_archetype and defined in terms of two lists of assertion statements defining which archetypes are allowed and/or which are excluded from filling that slot, introduced with the keywords include and exclude , respectively. The following example illustrates the general form of an archetype slot.

A slot constraint evaluates to a set of archetype identifiers from whatever is considered in the current model environment to be the total available set of archetypes.

The simplest possible slot has no includes or excludes, and effectively imposes no constraint. However, it is allowed in order to enable authoring tools to create a slot whose actual constraint definition will be defined at a later point in time.

A slot is designed to be 'filled', i.e. to have one of the allowed archetypes chosen for use. This is done in a child archetype, almost always a template. A slot can also be 'closed', meaning no further fillers can be added.

The actual specification of slot fillers, and also the 'closing' of slots is done in specialised archetypes, and is described in [Slot Filling and Redefinition], in the chapter on specialisation.

Four types of structure representing constraints on reference model objects have been presented so far:

Under any given attribute node, any combination of these object constraint types can co-exist, as in the following example:

Here we have a constraint on an attribute called items (of cardinality 0..*), expressed as a series of possible constraints on objects of type ENTRY. The 1st, 4th and 7th are described inline; the 3rd, 5th and 6th are expressed in terms of internal references to other nodes earlier in the archetype, while the 2nd is an archetype slot, whose constraints are expressed in other archetypes matching the include/exclude constraints appearing between the braces of this node. Note also that the ordered keyword on the enclosing items node has been used to indicate that the list order is intended to be significant.

In realistic data, it is not uncommon to need to need to constrain multiple object properties that covary in a specific way. A simple example is the need to state range constraints on a temperature, represented as an openEHR DV_QUANTITY type, for both Centigrade and Fahrenheit scales. The default way to do this in ADL is as follows (the DV_QUANTITY class has property, units and magnitude attributes):

However, this is verbose, and does not clearly convey the dependence of units and magnitude on each other. What we logically want to do is to state a single constraint on a DV_QUANTITY that sets the magnitude range constraint dependent on the units constraint.

The covarying requirement could be met using assertions like the following in the rules section:

However, this seems obscure for what is logically a very simple kind of constraint.

A generic solution that can be used in the main definition section involves treating covarying properties formally as tuples, and providing syntax to express constraints on tuples. The following syntax achieves this:

The above defines constraints on units and magnitude together, as tuples such as [{"deg F"}, {|32.0..212.0|}] .

The brackets surrounding each leaf level constraint are needed because although such constraints are typically atomic, as above, they may also take other standard ADL forms such as a list of strings, list of integers etc. In the latter case, the ',' characters from such lists will be conflated with the ',' separator of the distinct constraints in the tuple. Use of {} is also logically justified: each such entity is indeed a constraint in the ADL sense, and all ADL constraints are delimited by {}.

The tuple form has the advantage of expressing the additional constraint that only corresponding units and magnitude leaf level constraints can occur together, while other combinations like "deg F" and |0.0..100.0| would be illegal.

Another way to attempt to represent the effect of covarying constraints might be as follows, using lists of primitive values as shown below. However, there is nothing in these constraints that forces the correct associations between the units and magnitude constraints, preventing wrong combinations.

This same syntax will work for tuples of 3 or more co-varying properties. It does involve some extra work for compiler implementers, but this only needs to be performed once to support any use of tuple constraints, regardless of Reference Model type.

A constraint on the openEHR DV_ORDINAL type provides another example of the utility of ADL tuples. First, a typical ordinal constraint (a scale of +, ++, +++) with standard ADL:

By the use of tuple constraint, almost the same thing can be chieved much more efficiently. We can write:

Within a container attribute, any number of object constraints may be defined. The cardinality and occurrences constraints described above show how to control respectively, the overall container contents, and the occurrence of any particular object constraint within data. However, sometimes finer control is needed on repetition and grouping of members within the container. This can be achieved by the group construct, which provides an interior block where a subset of the overall container can be treated as a sub-group. The following example shows a typical used of the group construct.

In the above, the group is used to state a logical choice of methodology representations, each defined by one of the three constraints within the group. The group construct includes both cardinality and occurrences qualifier constraints. The former indicates the size and ordering of the group, in the same way as a cardinality constraint does for the overall contents of a container attribute. The latter defines the repeatability of the group. If the group occurrences upper limit is above 1, it means that the sub group may repeat, with each repetition respecting the order and size defined by the group cardinality.

The use of group cardinality and occurrences constraints, coupled with the occurrences constraints on each group member provide a means of specifying a number of logical constraint types found in other formalisms, including XML, as follows.

Group blocks can be nested, enabling subsets of subsets to be defined, as illustrated below.

For nested groups, the individual object nodes of the sub-group count individually towards the super-group’s cardinality, i.e. the group itself is not counted as a node. Thus, in the following example, any three nodes can be chosen from nodes id6 - id11, with one or two of those nodes being from nodes id9 - id11.

At the leaf nodes in a cADL text, constraints can be expressed on the following primitive types:

Since primitive objects constitute the terminal nodes in an archetype, constraints may constrain type, occurrences (rare), and value.

While constraints on complex types follow the rules described so far, constraints on attributes of primitive types in cADL may be expressed in a shorter form, without type names, and omitting one level of braces, as follows:

rather than:

This is possible because the syntax patterns of all primitive type constraints are mutually distinguishable, i.e. the type can always be inferred from the syntax alone. Since all leaf attributes of all object models are of primitive types, or lists or sets of them, cADL archetypes using the brief form for primitive types are significantly less verbose overall, as well as being more directly comprehensible to human readers. Because the brief form omits an id-code, the id-code for primitive object nodes is automatically set to a fixed value, defined in the AOM specification as Primitive_node_id.

Although for the majority of primitive type constraints, the shortened form is the most convenient, there is one circumstance in which the regular syntax form is needed, which is when only the type is to be constrained, but not the value. This leads to a constraint of the following form:

This may occur because the attribute some_attr in the reference model is of a more general type, e.g. Any. The constraint may thus be to simply require a String, Terminology_code or other primitive type. In the regular form a valid id-code must be supplied; this may be either a standard id-code (e.g. id9) or the Primitive_node_id value. If the former is used, any specialised archetype that adds a value constraint must use the regular form, as in the following example.

If the Primitive_node_id is used, a specialisation may use the brief form, as in the following.

In an archetype containing optional data elements, an ability to define 'assumed' values is useful. For example, an archetype for 'blood pressure measurement' might include an optional data element describing the patient position, with choices 'lying', 'sitting' and 'standing'. Since this element is optional, data could be created according to the archetype that does not contain it. However, a blood pressure cannot be taken without the patient in some position, so clearly there is an implied value.

The archetype allows this 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 on any primitive type, and are expressed after the constraint expression, by a semi-colon (';') followed by a value of the same type as that implied by the preceding part of the constraint. Example constraints containing assumed values are shown in the sections below.

If no assumed value is stated, no reliable assumption can be made by the receiver of the archetyped data about what the values of removed optional parts might be, from inspecting the archetype. However, this usually corresponds to a situation where the assumed value does not even need to be stated - the same value will be assumed by all users of this data, if its value is not transmitted. In most cases, if an element specified as optional in the archetype, data users only care about the value if it is actually present. The 'assumed value' concept is therefore not likely to be needed in most cases.

Boolean runtime values can be constrained to be True, False, or either, as follows:

Attribute values of type Character can be constrained in two ways: using a list of characters, and using a regular expression.

The value of an attribute of type String is constrained using a list of one or more Strings, each of which may be a fixed String, or a regular expression. In both cases, comparison to the constraint values is case-sensitive.

Although any mixture of fixed Strings and regular expressions may be used, the most common possibilities are a list of fixed Strings and a single regular expression.

Of the primitive types defined in the openEHR Foundation Types, some inherit (at least notionally) from the abstract type Ordered, including Integer, Real, and the Date/Time types. Constraints on all these types follow a constraint type of List<Interval<T:Ordered>>, i.e. a List of Intervals. Since the Interval<T> type in openEHR includes a descendant Point_interval<T> that can represent a degenerate interval of the form {N..N}, i.e. effectively a single value, this constraint type can represent many patterns of constraint, including:

Additional 'pattern' constraints are available on the Date/Time types.

The value of an attribute of type Integer is constrained using a list of one or more integer values or intervals. The most common possibilities are a list of single integers, and a single interval, but multiple intervals and or single values are possible as well.

Constraints on attributes of type Real follow the same syntax as for Integers, in both list and interval forms. The only difference is that the real number values used in the constraints are indicated by the use of the decimal point and at least one succeeding digit, which may be 0. Typical examples are:

Attributes of type Date, Time, Date_time and Duration (or of differently-named primitive types with the same meaning) may all be constrained in either of two ways:

The first method allows temporal values to be constrained to actual date, time etc values, while the second allows values to be constrained on the basis of which parts of the date, time etc are present or missing, regardless of value. The pattern method is described first, since patterns can also be used in lists and intervals.

Terminology constraints deal with a special category of data values known as 'coded terms' or 'terminology'. Coded data values are both textual (e.g. "diastolic blood pressure") and semantic (may have relationships to each other). The idea is that instead of using text, the possible values are represented in structured vocabularies, terminologies or ontologies that define both the possible text (including translations) and also the relationships, if any, between the terms (sometimes known as 'concepts'). In health, typical examples include 'terminology' resources such as WHO ICDx and SNOMED CT terminologies and drug databases.

Coded terms are treated as a primitive type in ADL in order to enable the formalism and tools to work with terminology constraints. Unlike other primitive constraints, terminology constraints may be complex, because they can refer to external resources, either directly or via 'bindings' defined elsewhere in the archeype. This section describes just the syntax representations and relationships between these.

The full description, including binding and resolution is provided in [Terminology Integration]. This section describes only the syntax for term constraint in the definition section of an archetype.

Syntactically, there are two types of terminology constraint expressible in 'source form' ADL, i.e. authored archetypes and templates. The first is expressed with an ac-code which refers to a value set which is either defined in the archetype terminology or externally. The second, for convenience, uses a single at-code, in order to express a single term value without requiring a value-set. For the first case, an assumed value in the form of an at-code can also be stated, and has the same sense as the assumed values of other primitive types already described.

The possibilities are illustrated below.

In the above, the constraint at the path items[id11]/name[id8] is on a DV_CODED_TEXT.defining_code representing the name of the ELEMENT. It is constrained to a single at-code value representing 'Substance' (assume this is the preferred name of the institution that created this archetype). The at-code is defined in the terminology part of the archetype, and may have bindings defined there as well. These are described in later sections.

The second variant uses the code ac1, which refers to a value set. This is by definition: all ac-codes in ADL refer only to value sets. This is the most common form of terminology constraint - defining possible codes for a codeable value in the model. The code and any bindings are also defined in the terminology section.

The last variant shows a second value set, this time with an assumed code, where at23 must be in the value set referred to by ac2.

A further syntax possibility exists, for use at the point of operational template generation. As described in [From Constraints to Concrete Codes in Data], the choice may be made that a specific operational template (OPT) should use external codes from the archetype bindings (such as from SNOMED CT, ICD10, etc) as the values of some or all coded nodes, rather than using the internal at-codes.

To express this choice, the OPT’s definition section contains a modified version of the usual syntax [at1] or [ac1] in those nodes where an external term from the bindings is to be used. This takes the form [acN@ttttt] or [atN@ttttt] where ttttt is the namespace identifier of a binding in the terminology section of the archetype.

Specifying which codable nodes (including 'all' and 'none' options) should have their values substituted by the external codes is assumed to be part of the OPT generator tool. Different terminology bindings may be specified on different nodes of the same archetype, or none at all, allowing for a mixture of external term substitional depending on node.

The following example shows the result in an operational template fragment.

See [Terminology Integration] for fuller picture of how this works.

In some cases, the type in the information model of an attribute to be constrained is a list or set of primitive types, i.e. List<Integer>, Set<String> etc. Here, the types List<T> and Set<T> are understood in the standard way in computer science, i.e. as linear containers with respectively, ordering and unique membership.

Any constraint described above for single-valued attributes, which is commensurate with the type of the attribute in question, may be used for this purpose as well. However, for values of type List<T>, Set<T> etc, the meaning is now that every item in the value list is constrained to be any one of the values specified by the constraint expression. For example:

constrains each value in the list corresponding to the value of the attribute speed_limits (of type List<Integer> ), to be any one of the values 50, 60, 70 etc.

A third variation on primitive types is that of Intervals of Ordered primitive types, i.e. where the attribute type is Interval<Integer>, Interval<Duration> etc. The type Interval<T:Ordered> is understood as defined in the openEHR Foundation Types, and corresponds to a similar type in most programming language libraries.

Values of these types may be constrained with the same constraint expressions as for atomic values of the same type, with the most usual pattern being one or more Intervals, e.g.:

The meaning of such constraints is interpreted differently for Interval-valued attributes compared to single-valued attributes. Here, each Interval in the constraint is understood as a possible (Interval) value for the constrained attribute, not as providing a range of possble values. The example above thus allows 5 different Interval values for the attribute speed_range.

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

In ADL, constraints on enumerated types are represented by constraints on the underlying primitive values. The following example shows 2 constraints on an attribute of the type PROPORTION_KIND from the openEHR Reference Model.

PROPORTION_KIND is defined as {pk_ratio = 0; pk_unitary = 1; pk_percent = 2; pk_fraction = 3; pk_integer_fraction = 4} in its reference model. Modelling tools are relied on to visualise enumeration constraints in a suitable way, by inferring the type based on inspection of the reference model on which the archetype is based.