Archetype Definition Language

2.5 Tools

A validating ADL parser is freely available from http://www.openEHR.org. It has been wrapped for use in Java and Microsoft .Net, and standard C/C++ environments. See the website for the latest status.

Date of Issue: 13 Mar 2007 Page 20 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 File Encoding and Character Quoting Rev 1.4.0

File Encoding and Character Quoting

3.1 File Encoding

Because ADL files are inherently likely to contain multiple languages due to internationalised authoring and translation, they must be capable of accommodating characters from any language. ADL files do not explicitly indicate an encoding because they are assumed to be in UTF-8 encoding of unicode. For ideographic and script-oriented languuages, this is a necessity.

There are three places in ADL files where non-ASCII characters can occur:

• in string values, demarcated by double quotes, e.g. “xxxx”;
• in regular expression patterns, demarcated by either // or ^^;
• in character values, demarcated by single quotes, e.g. ‘x’;

Note that URIs (a data type in dADL) are not problematic, since all characters outside the ‘unreserved set’ defined by RFC 3986¹ are already ‘percent-encoded’. The unreserved set is:

unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"In actual fact, ADL files encoded in latin 1 (ISO-8859-1) or another variant of ISO-8859 - both containing accented characters with unicode codes outside the ASCII 0-127 range - may work perfectly well, for various reasons:

• the contain nothing but ASCII, i.e. unicode code-points 0 - 127; this will be the case in English-language authored archetypes containing no foreign words;
• some layer of the operating system is smart enough to do an on-the-fly conversion of characters above 127 into UTF-8, even if the archetype tool being used is designed for pure UTF-8 only;
• the archetype tool (or the string-processing libraries it uses) might support UTF-8 and ISO8859 variants.

For situations where binary UTF-8 (and presumably other UTF-* encodings) cannot be supported, ASCII encoding of unicode characters above code-point 127 should only be done using the system supported by many programming languages today, namely \u escaped UTF-16. In this system, unicode codepoints are mapped to either:

• \uHHHH - 4 hex digits which will be the same (possibly 0-filled on the left) as the unicode code-point number expressed in hexadecimal; this applies to unicode codepoints in the range U+0000 - U+FFFF (the ‘base multi-lingual plane’, BMP);
• \uHHHHHHHH - 8 hex digits to encode unicode code-points in the range U+10000 through U+10FFFF (non-BMP planes); the algorithm is described in IETF RFC 2781².

It is not expected that the above approach will be commonly needed, and it may not be needed at all; it is preferable to find ways to ensure that native UTF-8 can be supported, since this reduces the burden for ADL parser and tool implementers. The above guidance is therefore provided only to ensure a standard approach is used for ASCII-encoded unicode, if it becomes unavoidable.

Thus, while the only officially designated encoding for ADL and its constituent syntaxes is UTF8, real software systems may be more tolerant. This document therefore specifies that any tool

1. Uniform Resource Identifier (URI): Generic Syntax, Internet proposed standard, January 2005; see http://www.ietf.org/rfc/rfc3986.txt

2. see http://tools.ietf.org/html/rfc2781.

Editors:{T Beale, S Heard} Page 21 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

File Encoding and Character Quoting Archetype Definition Language ADL 1.4 Rev 1.4.0

designed to process ADL files need only support UTF-8; supporting other encodings is an optional extra. This could change in the future, if required by the ADL or openEHR user community.

3.2 Special Character Sequences

In strings and characters, characters not in the lower ASCII (0-127) range should be UTF-8 encoded, with the exception of quoted single- and double quotes, and some non-printing characters, for which the following customary quoted forms are allowed (but not required):

• \r - carriage return
• \n - linefeed
• \t - tab
• \\ - backslash
• \” - literal double quote
• \’ - literal single quote

Any other character combination starting with a backslash is illiegal; to get the effect of a literal backslash, the \\ sequence should always be used.

Typically in a normal string, including multi-line paragraphs as used in dADL, only \\ and \” are likely to be necessary, since all of the others can be accommodated in their literal forms; the same goes for single characters - only \\ and \’ are likely to commonly occur. However, some authors may prefer to use \n and \t to make intended formatting clearer, or to allow for text editors that do not react properly to such characters. Parsers should therefore support the above list.

In regular expressions (only used in cADL string constraints), there will typically be backslash-escaped characters from the above list as well as other patterns like \s (whitspace) and \d (decimal digit), according to the PERL regular expression specification¹. These should not be treated as anything other than literal strings, since they are processed by a regular expression parser.

1. http://www.perldoc.com/perl5.6/pod/perlre.html

Date of Issue: 13 Mar 2007 Page 22 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

dADL - Data ADL

4.1 Overview

The dADL syntax provides a formal means of expressing instance data based on an underlying information model, which is readable both by humans and machines. The general appearance is exemplified by the following:

person = (List<PERSON>)< [01234] = <

name = < -- person’s name forenames = <"Sherlock"> family_name = <"Holmes"> salutation = <"Mr">

>

address = < -- person’s address habitation_number = <"221B"> street_name = <“Baker St”> city = <“London”> country = <“England”>

> > [01235] = <

-- etc

> > In the above the attribute names person, name, address etc, and the type List<PERSON> are all assumed to come from an information model. The [01234] and [01235] tags identify container items.

The basic design principle of dADL is to be able to represent data in a way that is both machineprocessible and human readable, while making the fewest assumptions possible about the information model to which the data conforms. To this end, type names are optional; often, only attribute names and values are explicitly shown. No syntactical assumptions are made about whether the underlying model is relational, object-oriented or what it actually looks like. More than one information model can be compatible with the same dADL-expressed data. The UML semantics of composition/aggregation and association are expressible, as are shared objects. Literal leaf values are only of ‘standard’ widely recognised types, i.e. Integer, Real, Boolean, String, Character and a range of Date/time types. In standard dADL, all complex types are expressed structurally.

A common question about dADL is why it is needed, when there is already XML? To start with, this question highlights the widespread misconception about XML, namely that because it can be read by a text editor, it is intended for humans. In fact, XML is designed for machine processing, and is textual to guarantee its interoperability. Realistic examples of XML (e.g. XML-schema instance, OWLRDF ontologies) are generally unreadable for humans. dADL is on the other hand designed as a human-writable and readable formalism that is also machine processable; it may be thought of as an abstract syntax for object-oriented data. dADL also differs from XML by:

• providing a more comprehensive set of leaf data types, including intervals of numerics and date/time types, and lists of all primitive types;
• adhering to object-oriented semantics, particularly for container types, which XML schema languages generally do not;

Editors:{T Beale, S Heard} Page 23 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

• not using the confusing XML notion of ‘attributes’ and ‘elements’ to represent what are essentially object properties;
• requiring half the space of the equivalent XML.

Of course, this does not prevent XML exchange syntaxes being used for dADL, and indeed the conversion to XML instance is rather straighforward. Details on the XML expression of dADL and use of Xpath expressions is described in section 4.7 on page 36 .

The dADL syntax as described above has a number of useful characteristics that enable the extensive use of paths to navigate it, and express references. These include:

• each <> block corresponds to an object (i.e. an instance of some type in an information model);
• the name before an ‘=’ is always an attribute name or else a container element key, which attaches to the attribute of the enclosing block;
• paths can be formed by navigating down a tree branch and concatenating attribute name, container keys (where they are encountered) and ‘/’ characters;
• every node is reachable by a path;
• shared objects can be referred to by path references.

4.2 Basics

4.2.1 Scope of a dADL Document

A dADL document may contain one or more objects from the same object model.

4.2.2 Keywords

dADL has no keywords of its own: all identifiers are assumed to come from an information model.

4.2.3 Reserved Characters

In dADL, a small number of characters are reserved and have the following meanings:

‘<’: open an object block;

‘>’: close an object block;

‘=’: indicate attribute value = object block;

‘(’, ‘)’: type name or plug-in syntax type delimiters;

‘<#’: open an object block expressed in a plug-in syntax;

‘#>’: close an object block expressed in a plug-in syntax. Within <> delimiters, various characters are used as follows to indicate primitive values:

‘”’: double quote characters are used to delimit string values;

‘’’: single quote characters are used to delimit single character values;

‘|’: bar characters are used to delimit intervals;

[]: brackets are used to delimit coded terms.

Date of Issue: 13 Mar 2007 Page 24 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

4.2.4 Comments

In a dADL text, comments satisfy the following rule:

comments are indicated by the characters “--”. Multi-line comments are achieved using the “--” leader on each line where the comment continues. In this document, comments are shown in brown.

4.2.5 Information Model Identifiers

Two types of identifiers from information models are used in dADL: type names and attribute names.

A type name is any identifier with an initial upper case letter, followed by any combination of letters, digits and underscores. A generic type name (including nested forms) additionally may include commas and angle brackets, but no spaces, and must be syntactically correct as per the UML. An attribute name is any identifier with an initial lower case letter, followed by any combination of letters, digits and underscores. Any convention that obeys this rule is allowed.

At least two well-known conventions that are ubiquitous in information models obey the above rule. One of these is the following convention:

• type names are in all uppercase, e.g. PERSON, except for ‘built-in’ types, such as primitive types (Integer, String, Boolean, Real, Double) and assumed container types (List<T>, Set<T>, Hash<T, U>), which are in mixed case, in order to provide easy differentiation of built-in types from constructed types defined in the reference model. Built-in types are the same types assumed by UML, OCL, IDL and other similar object-oriented formalisms.
• attribute names are shown in all lowercase, e.g. home_address.
• in both type names and attribute names, underscores are used to represent word breaks. This convention is used to maximise the readability of this document.

Other conventions may be used, such as the common programmer’s mixed-case or “camel case” convention exemplified by Person and homeAddress, as long as they obey the rule above. The convention chosen for any particular dADL document should be based on the convention used in the underlying information model. Identifiers are shown in green in this document.

4.2.6 Semi-colons

Semi-colons can be used to separate dADL blocks, for example when it is preferable to include multiple attribute/value pairs on one line. Semi-colons make no semantic difference at all, and are included only as a matter of taste. The following examples are equivalent:

term = <text = <"plan">; description = <"The clinician's advice">>

term = <text = <"plan"> description = <"The clinician's advice">>

term = < text = <"plan"> description = <"The clinician's advice">

>

Semi-colons are completely optional in dADL.

4.3 Paths

Because dADL data is hierarchical, and all nodes are uniquely identified, a reliable path can be determined for every node in a dADL text. The syntax of paths in dADL is the standard ADL path syntax,

Editors:{T Beale, S Heard} Page 25 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

described in detail in section 7 on page 25. Paths are directly convertible to XPath expressions for use in XML-encoded data.

A typical ADL path used to refer to a node in a dADL text is as follows.

/term_definitions[“en”]/items[“at0001”]/text

In the following sections, paths are shown for all the dADL data examples.

4.4 Structure

4.4.1 General Form

A dADL document expresses serialised instances of one or more complex objects. Each such instance is a hierarchy of attribute names and object values. In its simplest form, a dADL text consists of repetitions of the following pattern:

attribute_name = <value>

In the most basic form of dADL, each attribute name is the name of an attribute in an implied or actual object or relational model. Each “value” is either a literal value of a primitive type (see Primi tive Types on page 32 ) or a further nesting of attribute names and values, terminating in leaf nodes of primitive type values. Where sibling attribute nodes occur, the attribute identifiers must be unique, just as in a standard object or relational model.

Sibling attribute names must be unique.

The following shows a typical structure.

attr_1 = <

attr_2 = <

attr_3 = <leaf_value>

attr_4 = <leaf_value>

>

attr_5 = <

attr_3 = <

attr_6 = <leaf_value>

>

attr_7 = <leaf_value>

>

>

attr_8 = <>

In the above structure, each “<>” encloses an instance of some type. The hierarchical structure corresponds to the part-of relationship between objects, otherwise known as composition and aggregation relationships in object-oriented formalisms such as UML (the difference between the two is usually described as being “sub-objects related by aggregation can exist on their own, whereas sub-objects related by composition are always destroyed with the parent”; dADL does not differentiate between the two, since it is the business of a model, not the data, to express such semantics). Associations between instances in dADL are also representable by references, and are described in section 4.4.6 on page 31.

4.4.1.1 Outer Delimiters

To be completely regular, an outer level of delimiters should be used, because the totality of a dADL text is an object, not a collection of disembodied attribute/object pairs. However, the outermost delim-

Date of Issue: 13 Mar 2007 Page 26 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

iters can be left out in order to improve readability, and without complicating the parsing process. The completely regular form would appear as follows:

< attr_1 = < > attr_8 = <>

>

Outer ‘<>’ delimiters in a dADL text are optional.

4.4.1.2 Paths

The complete set of paths for the above example is as follows.

/attr_1 /attr_1/attr_2 /attr_1/attr_2/attr_3 -- path to a leaf value /attr_1/attr_2/attr_4 -- path to a leaf value /attr_1/attr_5 /attr_1/attr_5/attr_3 /attr_1/attr_5/attr_3/attr_6 -- path to a leaf value /attr_1/attr_5/attr_7 -- path to a leaf value /attr_8

4.4.2 Empty Sections

Empty sections are allowed at both internal and leaf node levels, enabling the author to express the fact that there is in some particular instance, no data for an attribute, while still showing that the attribute itself is expected to exist in the underlying information model. An empty section looks as follows:

address = <> -- person’s address

Nested empty sections can be used.

Note: within this document, empty sections are shown in many places to represent fully populated data, which would of course require much more space.

Empty sections can appear anywhere.

4.4.3 Container Objects

The syntax described so far allows an instance of an arbitrarily large object to be expressed, but does not yet allow for attributes of container types such as lists, sets and hash tables, i.e. items whose type in an underlying reference model is something like attr:List<Type>, attr:Set<Type> or attr: Hash<ValueType, KeyType>. There are two ways instance data of such container objects can be expressed in dADL. The first is to use a list style literal value, where the “list nature” of the data is expressed within the manifest value itself, as in the following examples.

fruits = <“pear”, “cumquat”, “peach”> some_primes = <1, 2, 3, 5>

See Lists of Built-in Types on page 35 for the complete description of list leaf types. This approach is fine for leaf data. However for containers holding non-primitive values, including more container objects, a different syntax is needed. Consider by way of example that an instance of the container List<Person> could be expressed as follows.

-- WARNING: THIS IS NOT VALID dADL

Editors:{T Beale, S Heard} Page 27 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

people = < <name = <> date_of_birth = <> sex = <> interests = <>> <name = <> date_of_birth = <> sex = <> interests = <>> -- etc

>

Here, “anonymous” blocks of data are repeated inside the outer block. However, this makes the data hard to read, and does not provide an easy way of constructing paths to the contained items. A better syntax becomes more obvious when we consider that members of container objects in their computable form are nearly always accessed by a method such as member(i), item[i] or just plain [i], in the case of array access in the C-based languages. dADL opts for the array-style syntax, known in dADL as container member keys . No attribute name is explicitly given (see Syntax Alternatives on page 46 for further discussion of this choice); any primitive comparable value is allowed as the key, rather than just integers used in C-style array access. Further, if integers are used, it is not assumed that they dictate ordinal indexing, i.e. it is possible to use a series of keys [2], [4], [8] etc. The following example shows one version of the above container in valid dADL:

people = <

[1] = <name = <> birth_date = <> interests = <>>

[2] = <name = <> birth_date = <> interests = <>>

[3] = <name = <> birth_date = <> interests = <>> >

Strings and dates may also be used. Keys are coloured blue in the this specification in order to distinguish the run-time status of key values from the design-time status of class and attribute names. The following example shows the use of string values as keys for the contained items.

people = <[“akmal:1975-04-22”] = <name = <> birth_date = <> interests = <>> [“akmal:1962-02-11”] = <name = <> birth_date = <> interests = <>> [“gianni:1978-11-30”] = <name = <> birth_date = <> interests = <>>

>

The syntax for primitive values used as keys follows exactly the same syntax described below for data of primitive types. It is convenient in some cases to construct key values from one or more of the values of the contained items, in the same way as relational database keys are constructed from sufficient field values to guarantee uniqueness. However, they need not be - they may be independent of the contained data, as in the case of hash tables, where the keys are part of the hash table structure, or equally, they may simply be integer index values, as in the ‘locations’ attribute in the ‘school_schedule’ structure shown below.

Container structures can appear anywhere in an overall instance structure, allowing complex data such as the following to be expressed in a readable way.

school_schedule = < lesson_times = <08:30:00, 09:30:00, 10:30:00, ...>

locations = <

[1] = <“under the big plane tree”>

[2] = <“under the north arch”>

[3] = <“in a garden”> >

subjects = <

[“philosophy:plato”] = < -- note construction of key name = <“philosophy”> teacher = <“plato”> topics = <“meta-physics”, “natural science”>

Date of Issue: 13 Mar 2007 Page 28 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

weighting = <76%> > [“philosophy:kant”] = <

name = <“philosophy”> teacher = <“kant”> topics = <“meaning and reason”, “meta-physics”, “ethics”> weighting = <80%>

>

[“art”] = < name = <“art”> teacher = <“goya”> topics = <“technique”, “portraiture”, “satire”> weighting = <78%>

> >

Container instances are expressed using repetitions of a block introduced by a key, in the form of a primitive value in brackets i.e. ‘[]’.

The example above conforms directly to the object-oriented type specification (given in a pascal-like syntax):

class SCHEDULE lesson_times: List<Time> locations: List<String> subjects: List<SUBJECT> -- or it could be Hash<SUBJECT>

end

class SUBJECT name: String teacher: String topics: List<String> weighting: Real

end

Other class specifications corresponding to the same data are possible, but will all be isomorphic to the above.

How key values relate to a particular object structure depends on the class model of objects being created due to a dADL parsing process. It is possible to write a parser which makes reasonable inferences from a class model whose instances are represented as dADL text; it is also possible to include explicit typing information in the dADL itself (see Adding Type Information below).

4.4.3.1 Paths

Paths through container objects are formed in the same way as paths in other structured data, with the addition of the key, to ensure uniqueness. The key is included syntactically enclosed in brackets, in a similar way to how keys are included in Xpath expressions. Paths through containers in the above example include the following:

/school_schedule/locations[1] -- path to “under the big...” /school_schedule/subjects[“philosophy:kant”] -- path to “kant”

4.4.4 Nested Container Objects

In some cases the data of interest are instances of nested container types, such as List<List<Message>> (a list of Message lists) or Hash<List<Integer>, String> (a hash of integer lists keyed by strings). The dADL syntax for such structures follows directly from the syntax for a single container

Editors:{T Beale, S Heard} Page 29 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

object. The following example shows an instance of the type List<List<String>> expressed in dADL syntax.

list_of_string_lists = <

[1] = <

[1] = <“first string in first list”>

[2]

= <“second string in first list”> >

[2]

= <

[1] = <“first string in second list”>

[2] = <“second string in second list”>

[3]

= <“third string in second list”> >

[3]

= <

[1] = <“only string in third list”>

> >

4.4.4.1 Paths

The paths of the above example are as follows:

/list_of_string_lists[1]/[1] /list_of_string_lists[1]/[2] /list_of_string_lists[2]/[1]

etc

4.4.5 Adding Type Information

In many cases, dADL data is of a simple structure, very regular, and highly repetitive, such as the expression of simple demographic data. In such cases, it is preferable to express as little as possible about the implied reference model of the data (i.e. the object or relational model to which it conforms), since various software components want to use the data, and use it in different ways. However, there are also cases where the data is highly complex, and more model information is needed to help software parse it,. Examples include large design databases such as for aircraft, and health records. Typing information is added to instance data using a syntactical addition inspired by the (type) casting operator of the C language, whose meaning is approximately: force the type of the result of the following expression to be type. In dADL typing is therefore done by including the type name in parentheses after the ‘=’ sign, as in the following example.

destinations = <

[“seville”] = (TOURIST_DESTINATION)< profile = (DESTINATION_PROFILE) <> hotels = <

[“gran sevilla”] = (HISTORIC_HOTEL) <> [“sofitel”] = (LUXURY_HOTEL) <> [“hotel real”] = (PENSION) <> >

attractions = < [“la corrida”] = (ATTRACTION) <> [“Alcázar”] = (HISTORIC_SITE) <>

> > >

Note that in the above, no type identifiers are included after the “hotels” and “attractions” attributes, and it is up to the processing software to infer the correct types (usually easy - it will be pre-determined by an information model). However, the complete typing information can be included, as follows.

Date of Issue: 13 Mar 2007 Page 30 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

hotels = (List<HOTEL>) <

[“gran sevilla”] = (HISTORIC_HOTEL) <> >

This illustrates the use of generic, or “template” type identifiers, expressed in the standard UML syntax, using angle brackets. Any number of template arguments and any level of nesting is allowed, as in the UML. There is a small risk of visual confusion between the template type delimiters and the standard dADL block delimiters, but technically there can never be any confusion, because only type names (first letter capitalised) may appear inside template delimiters, while only attribute names (first letter lower case) can appear after a dADL block delimiter.

Type identifiers can also include namespace information, which is necessary when same-named types appear in different packages of a model. Namespaces are included by prepending package names, separated by the ‘.’ character, in the same way as in most programming languages, as in the qualified type names org.openehr.rm.ehr.content.ENTRY and Core.Abstractions.Relationships.Relationship.

Type Information can be included optionally on any node immediately before the opening ‘<‘ of any block, in the form of a UML-style type identifier in parentheses. Dot-separated namespace identifiers and template parameters may be used.

4.4.6 Associations and Shared Objects

All of the facilities described so far allow any object-oriented data to be faithfully expressed in a formal, systematic way which is both machine- and human-readable, and allow any node in the data to be addressed using an Xpath-style path. The availability of reliable paths allows not only the representation of single ‘business objects’, which are the equivalent of UML aggregation (and composition) hierarchies, but also the representation of associations between objects, and by extension, shared objects.

Consider that in the example above, ‘hotel’ objects may be shared objects, referred to by assocation. This can be expressed as follows.

destinations = < [“seville”] = <

hotels = < [“gran sevilla”] = </hotels[“gran sevilla”]> [“sofitel”] = </hotels[“sofitel”]> [“hotel real”] = </hotels[“hotel real”]>

> > >

bookings = <

[“seville:0134”] = < customer_id = <“0134”> period = <...> hotel = </hotels[“sofitel”]>

> >

hotels = <

[“gran sevilla”] = (HISTORIC_HOTEL) <> [“sofitel”] = (LUXURY_HOTEL) <> [“hotel real”] = (PENSION) <>

>

Editors:{T Beale, S Heard} Page 31 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

Associations are expressed via the use of fully qualified paths as the data for a attribute. In this example, there are references from a list of destinations, and from a booking list, to the same hotel object. If type information is included, it should go in the declarations of the relevant objects; type declarations can also be used before path references, which might be useful if the association type is an ancestor type (i.e. more general type) of the type of the actual object being referred to.

Data in other dADL documents can be referred to using the URI syntax to locate the document, with the internal path included as described above.

Shared objects are referenced using paths. Objects in other dADL documents can be referred to using normal URIs whose path section conforms to dADL path syntax.

4.4.6.1 Paths

The path set from the above example is as follows:

/destinations[“seville”]/hotels[“gran sevilla”] /destinations[“seville”]/hotels[“sofitel”] /destinations[“seville”]/hotels[“hotel real”]

/bookings[“seville:0134”]/customer_id /bookings[“seville:0134”]/period /bookings[“seville:0134”]/hotel

/hotels[“sofitel”] /hotels[“hotel real”] /hotels[“gran sevilla”]

4.5 Leaf Data - Built-in Types

All dADL data eventually devolve to instances of the primitive types String, Integer, Real, Double, String, Character, various date/time types, lists or intervals of these types, and a few special types. dADL does not use type or attribute names for instances of primitive types, only manifest values, making it possible to assume as little as possible about type names and structures of the primitive types. In all the following examples, the manifest data values are assumed to appear immediately inside a leaf pair of angle brackets, i.e.

some_attribute = <manifest value here>

4.5.1 Primitive Types

4.5.1.1 Character Data

Characters are shown in a number of ways. In the literal form, a character is shown in single quotes, as follows:

‘a’

Characters outside the low ASCII (0-127) range must be UTF-8 encoded, with a small number of backslash-quoted ASCII characters allowed, as described in File Encoding and Character Quoting on page 21.

4.5.1.2 String Data

All strings are enclosed in double quotes, as follows:

“this is a string”

Quotes are encoded using ISO/IEC 10646 codes, e.g. :

“this is a much longer string, what one might call a &quot;phrase&quot;.”

Date of Issue: 13 Mar 2007 Page 32 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

Line extension of strings is done simply by including returns in the string. The exact contents of the string are computed as being the characters between the double quote characters, with the removal of white space leaders up to the left-most character of the first line of the string. This has the effect of allowing the inclusion of multi-line strings in dADL texts, in their most natural human-readable form, e.g.:

text = <“And now the STORM-BLAST came, and he Was tyrannous and strong : He struck with his o'ertaking wings, And chased us south along.”>

String data can be used to contain almost any other kind of data, which is intended to be parsed as some other formalism. Characters outside the low ASCII (0-127) range must be UTF-8 encoded, with a small number of backslash-quoted ASCII characters allowed, as described in File Encoding and Character Quoting on page 21 .

4.5.1.3 Integer Data

Integers are represented simply as numbers, e.g.:

25 300000 29e6

Commas or periods for breaking long numbers are not allowed, since they confuse the use of commas used to denote list items (see section 4.5.4 below).

4.5.1.4 Real Data

Real numbers are assumed whenever a decimal is detected in a number, e.g.:

25.0 3.1415926 6.023e23

Commas or periods for breaking long numbers are not allowed. Only periods may be used to separate the decimal part of a number; unfortunately, the European use of the comma for this purpose conflicts with the use of the comma to distinguish list items (see section 4.5.4 below).

4.5.1.5 Boolean Data

Boolean values can be indicated by the following values (case-insensitive):

True False

4.5.1.6 Dates and Times

Complete Date/Times

In dADL, full and partial dates, times and durations can be expressed. All full dates, times and durations are expressed using a subset of ISO8601. The Support IM provides a full explanation of the ISO8601 semantics supported in openEHR.

In dADL, the use of ISO 8601 allows extended form only (i.e. ‘:’ and ‘-’ must be used). The ISO 8601 method of representing partial dates consisting of a single year number, and partial times consisting of hours only are not supported, since they are ambiguous. See below for partial forms.

Patterns for complete dates and times in dADL include the following:

yyyy-MM-dd -- a date hh:mm:ss[,sss][Z|+/-hhmm] -- a time with optional seconds yyyy-MM-ddThh:mm:ss[,sss][Z] -- a date/time

Editors:{T Beale, S Heard} Page 33 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

where:

yyyy = four-digit year MM = month in year dd = day in month hh = hour in 24 hour clock mm = minutes ss,sss = seconds, incuding fractional partZ = the timezone in the form of a ‘+’ or ‘-’ followed by 4 digits

indicating the hour offset, e.g. +0930, or else the literal ‘Z’indicating +0000 (the Greenwich meridian).

Durations are expressed using a string which starts with ‘P’, and is followed by a list of periods, each appended by a single letter designator: ‘Y’ for years, “M’ for months, ‘W’ for weeks, ‘D’ for days, ‘H’ for hours, ‘M’ for minutes, and ‘S’ for seconds. The literal ‘T’ separates the YMWD part from the HMS part, ensuring that months and minutes can be distinguished. Examples of date/time data include:

1919-01-23 -- birthdate of Django Reinhardt 16:35:04,5 -- rise of Venus in Sydney on 24 Jul 2003 2001-05-12T07:35:20+1000 -- timestamp on an email received from Australia P22D4TH15M0S -- period of 22 days, 4 hours, 15 minutes

Partial Date/Times

Two ways of expressing partial (i.e. incomplete) date/times are supported in dADL. The ISO 8601 incomplete formats are supported in extended form only (i.e. with ‘-’ and ‘:’ separators) for all patterns that are unambiguous on their own. Dates consisting of only the year, and times consisting of only the hour are not supported, since both of these syntactically look like integers. The supported ISO 8601 patterns are as follows:

yyyy-MM -- a date with no days hh:mm -- a time with no seconds yyyy-MM-ddThh:mm -- a date/time with no seconds yyyy-MM-ddThh -- a date/time, no minutes or seconds

To deal with the limitations of ISO 8601 partial patterns in a context-free parsing environment, a second form of pattern is supported in dADL, based on ISO 8601. In this form, ‘?’ characters are substituted for missing digits. Valid partial dates follow the patterns:

yyyy-MM-?? -- date with unknown day in month yyyy-??-?? -- date with unknown month and day

Valid partial times follow the patterns:

hh:mm:?? -- time with unknown seconds hh:??:?? -- time with unknown minutes and seconds

Valid date/times follow the patterns:

yyyy-MM-ddThh:mm:?? -- date/time with unknown seconds yyyy-MM-ddThh:??:?? -- date/time with unknown minutes and seconds yyyy-MM-ddT??:??:?? -- date/time with unknown time yyyy-MM-??T??:??:?? -- date/time with unknown day and time yyyy-??-??T??:??:?? -- date/time with unknown month, day and time

4.5.2 Intervals of Ordered Primitive Types

Intervals of any ordered primitive type, i.e., Integer, Real, Date, Time, Date_time and Duration, can be stated using the following uniform syntax, where N, M are instances of any of the ordered types:

|N..M| the two-sided range N >= x <= M;

Date of Issue: 13 Mar 2007 Page 34 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

|N>..M| the two-sided range N > x <= M;

|N..<M| the two-sided range N >= x <M;

|N>..<M| the two-sided range N > x <M;

|<N| the one-sided range x < N; |>N| the one-sided range x > N; |>=N| the one-sided range x >= N; |<=N| the one-sided range x <= N; |N +/-M| interval of N ± M.

The allowable values for N and M include any value in the range of the relevant type, as well as:

infinity

-infinity

* equivalent to infinity

Examples of this syntax include:

|0..5| -- integer interval |0.0..1000.0| -- real interval |0.0..<1000.0| -- real interval 0.0 >= x < 1000.0 |08:02..09:10| -- interval of time |>= 1939-02-01| -- open-ended interval of dates |5.0 +/-0.5| -- 4.5 - 5.5 |>=0| -- >= 0 |0..infinity| -- 0 - infinity (i.e. >= 0)

4.5.3 Other Built-in Types

4.5.3.1 URIs

URI can be expressed as dADL data in the usual way found on the web, and follow the standard syntax from http://www.ietf.org/rfc/rfc3986.txt. Examples of URIs in dADL:

http://archetypes.are.us/home.htmlftp://get.this.file.com#section_5http://www.mozilla.org/products/firefox/upgrade/?application=thunderbird

Encoding of special characters in URIs follows the IETF RFC 3986, as described under File Encod ing and Character Quoting on page 21 .

4.5.3.2 Coded Terms

Coded terms are ubiquitous in medical and clinical information, and are likely to become so in most other industries, as ontologically-based information systems and the ‘semantic web’ emerge. The logical structure of a coded term is simple: it consists of an identifier of a terminology, and an identifier of a code within that terminology. The dADL string representation is as follows:

[terminology_id::code]

Typical examples from clinical data:

[icd10AM::F60.1] -- from ICD10AM [snomed-ct::2004950] -- from snomed-ct [snomed-ct(3.1)::2004950] -- from snomed-ct v 3.1

4.5.4 Lists of Built-in Types

Data of any primitive type can occur singly or in lists, which are shown as comma-separated lists of item, all of the same type, such as in the following examples:

Editors:{T Beale, S Heard} Page 35 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

“cyan”, “magenta”, “yellow”, “black” -- printer’s colours

1, 1, 2, 3, 5 -- first 5 fibonacci numbers

08:02, 08:35, 09:10 -- set of train times

No assumption is made in the syntax about whether a list represents a set, a list or some other kind of sequence - such semantics must be taken from an underlying information model.

Lists which happen to have only one datum are indicated by using a comma followed by a list continuation marker of three dots, i.e. “...”, e.g.:

“en”, ... -- languages

“icd10”, ... -- terminologies

[at0200], ...

White space may be freely used or avoided in lists, i.e. the following two lists are identical:

1,1,2,3

1, 1, 2,3

4.6 Plug-in Syntaxes

Using the dADL syntax, any object structure can be serialised. In some cases, the requirement is to express some part of the structure in an abstract syntax, rather than in the more literal seriliased object form of dADL. dADL provides for this possibility by allowing the value of any object (i.e. what appears between any matching pair of <> delimiters) to be expressed in some other syntax, known as a “plug-in” syntax. Plug-in syntaxes are indicated in dADL in a similar way as typed objects, i.e. by the use of the syntax type in parentheses preceding the <> block. For a plug-in section, the <> delimiters are modified to <# #>, to allow for easier parser design, and easier recognition of such blocks by human readers. The general form is as follows:

attr_name = (syntax) <#

...

#>

The following example illustrates a cADL plug-in section in an archetype, which it itself a dADL document:

definition = (cadl) <# ENTRY[at0000] ∈ { -- blood pressure measurement name ∈ { -- any synonym of BP CODED_TEXT ∈ { code ∈ { CODE_PHRASE ∈ {[ac0001]} } } } } #>

Clearly, many plug-in syntaxes might one day be used within dADL data; there is no guarantee that every dADL parser will support them. The general approach to parsing should be to use plug-in parsers, i.e. to obtain a parser for a plug-in syntax that can be built into the existing parser framework.

4.7 Expression of dADL in XML

The dADL syntax maps quite easily to XML instance. It is important to realise that people using XML often develop different mappings for object-oriented data, due to the fact that XML does not have systematic object-oriented semantics. This is particularly the case where containers such as lists and sets such as ‘employees: List<Person>’ are mapped to XML; many implementors have to invent

Date of Issue: 13 Mar 2007 Page 36 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

additional tags such as ‘employee’ to make the mapping appear visually correct. The particular mapping chosen here is designed to be a faithful reflection of the semantics of the object-oriented data, and does not try take into account visual aesthetics of the XML. The result is that Xpath expressions are the same for dADL and XML, and also correspond to what one would expect based on an underlying object model.

The main elements of the mapping are as follows.

Single Attributes

Single attribute nodes map to tagged nodes of the same name.

Container Attributes

Container attribute nodes map to a series of tagged nodes of the same name, each with the XML attribute ‘id’ set to the dADL key. For example, the dADL:

subjects = < [“philosophy:plato”] = <

name = <“philosophy”> > [“philosophy:kant”] = <

name = <“philosophy”> >

>

maps to the XML:

<subjects id=“philosophy:plato”> <name> philosophy

</name> </subjects> <subjects id=“philosophy:kant”>

<name> philosophy </name> </subjects>

This guarantees that the path subjects[@id=“philosophy:plato”]/name navigates to the same element in both dADL and the XML.

Nested Container Attributes

Nested container attribute nodes map to a series of tagged nodes of the same name, each with the XML attribute ‘id’ set to the dADL key. For example, consider an object structure defined by the signature countries:Hash<Hash<Hotel,String>,String>. An instance of this in dADL looks as follows:

countries = <

[“spain”] = < [“hotels”] = <...> [“attractions”] = <...>

>

[“egypt”] = < [“hotels”] = <...> [“attractions”] = <...>

> >

Editors:{T Beale, S Heard} Page 37 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

can be mapped to the XML in which the synthesised element tag “_items” and the attribute “key” are used:

<countries key=“spain”> <_items key=“hotels”>

... </_items> <_items key=“attractions”>

...

</_items> <countries> </countries key=“eqypt”>

<_items id=“hotels”>

... </_items> <_items key=“attractions”>

... </_items> </countries>

In this case, the dADL path countries[“spain”]/[“hotels”] will be transformed to the Xpath countries[@key=“spain”]/_items[@key=“hotels”] in order to navigate to the same element.

Type Names

Type names map to XML ‘type’ attributes e.g. the dADL:

destinations = <

[“seville”] = (TOURIST_DESTINATION)< profile = (DESTINATION_PROFILE) <> hotels = <

[“gran sevilla”] = (HISTORIC_HOTEL) <> > > >

maps to:

<destinations id=“seville” adl:type=”TOURIST_DESTINATION”> <profile adl:type=”DESTINATION_PROFILE”>

... </profile><hotels id=“gran sevilla” adl:type=”HISTORIC_HOTEL”>

... </hotels> > >

4.8 Syntax Specification

The grammar and lexical specification for the standard dADL syntax is shown below. This grammar is implemented using lex (.l file) and yacc (.y file) specifications for in the Eiffel programming environment. The current release of these files is available at

http://svn.openehr.org/ref_impl_eiffel/TRUNK/libraries/common_libs/src/struc tures/syntax/dadl/parser/ . The .l and .y files can easily be converted for use in another yacc/lexbased programming environment. The dADL production rules is available as an HTML document .

Date of Issue: 13 Mar 2007 Page 38 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4		dADL - Data ADL
		Rev 1.4.0
4.8.1	Grammar

The following provides the dADL parser production rules (yacc specification) as of revision 166 of the Eiffel reference implementation repository (http://svn.openehr.org/ref_impl_eiffel ).

input:

attr_vals | complex_object_block| error

attr_vals:

attr_val | attr_vals attr_val| attr_vals ; attr_val

attr_val: attr_id SYM_EQ object_block

attr_id: V_ATTRIBUTE_IDENTIFIER | V_ATTRIBUTE_IDENTIFIER error

object_block:

complex_object_block| primitive_object_block| plugin_object_block

plugin_object_block: V_PLUGIN_SYNTAX_TYPE V_PLUGIN_BLOCK

complex_object_block: single_attr_object_block| multiple_attr_object_block

multiple_attr_object_block: untyped_multiple_attr_object_block| type_identifier untyped_multiple_attr_object_block

untyped_multiple_attr_object_block: multiple_attr_object_block_head keyed_objects SYM_END_DBLOCK

multiple_attr_object_block_head: SYM_START_DBLOCK

keyed_objects: keyed_object| keyed_objects keyed_object

keyed_object: object_key SYM_EQ object_block

object_key: [ simple_value ]

single_attr_object_block: untyped_single_attr_object_block| type_identifier untyped_single_attr_object_block

Editors:{T Beale, S Heard} Page 39 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

untyped_single_attr_object_block: single_attr_object_complex_head SYM_END_DBLOCK | single_attr_object_complex_head attr_vals SYM_END_DBLOCK

single_attr_object_complex_head: SYM_START_DBLOCK

primitive_object_block: untyped_primitive_object_block | type_identifier untyped_primitive_object_block

untyped_primitive_object_block: SYM_START_DBLOCK primitive_object_value SYM_END_DBLOCK

primitive_object_value:

simple_value | simple_list_value | simple_interval_value | term_code | term_code_list_value

simple_value:

string_value | integer_value | real_value | boolean_value | character_value | date_value | time_value | date_time_value | duration_value | uri_value

simple_list_value:

string_list_value | integer_list_value | real_list_value | boolean_list_value | character_list_value | date_list_value | time_list_value | date_time_list_value | duration_list_value

simple_interval_value:

integer_interval_value | real_interval_value | date_interval_value | time_interval_value | date_time_interval_value | duration_interval_value

type_identifier:

V_TYPE_IDENTIFIER | V_GENERIC_TYPE_IDENTIFIER

string_value:

Date of Issue: 13 Mar 2007 Page 40 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

V_STRING

string_list_value:

V_STRING , V_STRING| string_list_value , V_STRING| V_STRING , SYM_LIST_CONTINUE

integer_value: V_INTEGER | + V_INTEGER | - V_INTEGER

integer_list_value:

integer_value , integer_value| integer_list_value , integer_value| integer_value , SYM_LIST_CONTINUE

integer_interval_value: SYM_INTERVAL_DELIM integer_value SYM_ELLIPSIS integer_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT integer_value SYM_ELLIPSIS integer_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM integer_value SYM_ELLIPSIS SYM_LT integer_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT integer_value SYM_ELLIPSIS SYM_LT integer_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT integer_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_LE integer_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GT integer_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GE integer_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM integer_value SYM_INTERVAL_DELIM

real_value: V_REAL | + V_REAL | - V_REAL

real_list_value:

real_value , real_value| real_list_value , real_value| real_value , SYM_LIST_CONTINUE

real_interval_value: SYM_INTERVAL_DELIM real_value SYM_ELLIPSIS real_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT real_value SYM_ELLIPSIS real_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM real_value SYM_ELLIPSIS SYM_LT real_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT real_value SYM_ELLIPSIS SYM_LT real_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT real_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_LE real_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GT real_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GE real_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM real_value SYM_INTERVAL_DELIM

boolean_value: SYM_TRUE | SYM_FALSE

Editors:{T Beale, S Heard} Page 41 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

boolean_list_value:

boolean_value , boolean_value | boolean_list_value , boolean_value | boolean_value , SYM_LIST_CONTINUE

character_value: V_CHARACTER

character_list_value:

character_value , character_value | character_list_value , character_value | character_value , SYM_LIST_CONTINUE

date_value: V_ISO8601_EXTENDED_DATE

date_list_value:

date_value , date_value | date_list_value , date_value | date_value , SYM_LIST_CONTINUE

date_interval_value: SYM_INTERVAL_DELIM date_value SYM_ELLIPSIS date_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT date_value SYM_ELLIPSIS date_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM date_value SYM_ELLIPSIS SYM_LT date_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT date_value SYM_ELLIPSIS SYM_LT date_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT date_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LE date_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT date_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GE date_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM date_value SYM_INTERVAL_DELIM

time_value: V_ISO8601_EXTENDED_TIME

time_list_value:

time_value , time_value | time_list_value , time_value | time_value , SYM_LIST_CONTINUE

time_interval_value: SYM_INTERVAL_DELIM time_value SYM_ELLIPSIS time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT time_value SYM_ELLIPSIS time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM time_value SYM_ELLIPSIS SYM_LT time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT time_value SYM_ELLIPSIS SYM_LT time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LE time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GE time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM time_value SYM_INTERVAL_DELIM

date_time_value:

Date of Issue: 13 Mar 2007 Page 42 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

V_ISO8601_EXTENDED_DATE_TIME

date_time_list_value:

date_time_value , date_time_value| date_time_list_value , date_time_value| date_time_value , SYM_LIST_CONTINUE

date_time_interval_value: SYM_INTERVAL_DELIM date_time_value SYM_ELLIPSIS date_time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT date_time_value SYM_ELLIPSIS date_time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM date_time_value SYM_ELLIPSIS SYM_LT date_time_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT date_time_value SYM_ELLIPSIS SYM_LT

date_time_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT date_time_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_LE date_time_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GT date_time_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GE date_time_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM date_time_value SYM_INTERVAL_DELIM

duration_value: V_ISO8601_DURATION

duration_list_value:

duration_value , duration_value| duration_list_value , duration_value| duration_value , SYM_LIST_CONTINUE

duration_interval_value: SYM_INTERVAL_DELIM duration_value SYM_ELLIPSIS duration_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT duration_value SYM_ELLIPSIS duration_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM duration_value SYM_ELLIPSIS SYM_LT duration_value

SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_GT duration_value SYM_ELLIPSIS SYM_LT

duration_value SYM_INTERVAL_DELIM | SYM_INTERVAL_DELIM SYM_LT duration_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_LE duration_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GT duration_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM SYM_GE duration_value SYM_INTERVAL_DELIM| SYM_INTERVAL_DELIM duration_value SYM_INTERVAL_DELIM

term_code: V_QUALIFIED_TERM_CODE_REF

term_code_list_value:

term_code , term_code| term_code_list_value , term_code| term_code , SYM_LIST_CONTINUE

uri_value: V_URI

Editors:{T Beale, S Heard} Page 43 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

4.8.2 Symbols

The following provides the dADL lexical analyser production rules (lex specification) as of revision 36 of the Eiffel reference implementation repository (http://svn.openehr.org/ref_impl_eiffel ):

----------/* definitions */ ----------------------------------------------

ALPHANUM [a-zA-Z0-9]

IDCHAR [a-zA-Z0-9_]

NAMECHAR [a-zA-Z0-9._\-]

NAMECHAR_SPACE [a-zA-Z0-9._\- ]

NAMECHAR_PAREN [a-zA-Z0-9._\-()]

UTF8CHAR (([\xC2-\xDF][\x80-\xBF])|(\xE0[\xA0-\xBF][\x80-\xBF])|([\xE1

\xEF][\x80-\xBF][\x80-\xBF])|(\xF0[\x90-\xBF][\x80-\xBF][\x80-\xBF])|([\xF1

\xF7][\x80-\xBF][\x80-\xBF][\x80-\xBF]))

----------/** Separators **/--------------------------------------------

[ \t\r]+ -- Ignore separators

\n+ -- (increment line count)

----------/** comments **/----------------------------------------------

"--".* -- Ignore comments

"--".*\n[ \t\r]* -- (increment line count)

----------/* symbols */ ------------------------------------------------

"-" -- -> Minus_code

"+" -- -> Plus_code

"*" -- -> Star_code

"/" -- -> Slash_code

"^" -- -> Caret_code

"." -- -> Dot_code

";" -- -> Semicolon_code

"," -- -> Comma_code

":" -- -> Colon_code

"!" -- -> Exclamation_code

"(" -- -> Left_parenthesis_code

")" -- -> Right_parenthesis_code

"$" -- -> Dollar_code

"??" -- -> SYM_DT_UNKNOWN

"?" -- -> Question_mark_code

"|" -- -> SYM_INTERVAL_DELIM

"[" -- -> Left_bracket_code

"]" -- -> Right_bracket_code

"=" -- -> SYM_EQ

">=" -- -> SYM_GE

"<=" -- -> SYM_LE

"<" -- -> SYM_LT or SYM_START_DBLOCK ">" -- -> SYM_GT or SYM_END_DBLOCK

Date of Issue: 13 Mar 2007 Page 44 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

".." -- -> SYM_ELLIPSIS

"..." -- -> SYM_LIST_CONTINUE

----------/* keywords */ --------------------------------------------

[Tt][Rr][Uu][Ee] -- -> SYM_TRUE

[Ff][Aa][Ll][Ss][Ee] -- -> SYM_FALSE

[Ii][Nn][Ff][Ii][Nn][Ii][Tt][Yy] -- -> SYM_INFINITY

----------/* V_URI */ ------------------------------------------------

[a-z]+:\/\/[^<>|\\{}^~"\[\] ]*

----------/* V_QUALIFIED_TERM_CODE_REF form [ICD10AM(1998)::F23] */ ----

\[{NAMECHAR_PAREN}+::{NAMECHAR}+\]

----------/* ERR_V_QUALIFIED_TERM_CODE_REF */ ----

\[{NAMECHAR_PAREN}+::{NAMECHAR_SPACE}+\]

----------/* V_LOCAL_TERM_CODE_REF */ --------------------------------

\[{ALPHANUM}{NAMECHAR}*\]

----------/* V_LOCAL_CODE */ -----------------------------------------

a[ct][0-9.]+

----------/* V_ISO8601_EXTENDED_DATE_TIME YYYY-MM-DDThh:mm:ss[,sss][Z|+/

nnnn] */ --

[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-6][0-9]:[0-6][0-9](,[0-9]+)?(Z|[+-][0-9]{4})? |

[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-6][0-9](Z|[+-][0-9]{4})? |

[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9](Z|[+-][0-9]{4})?

----------/* V_ISO8601_EXTENDED_TIME hh:mm:ss[,sss][Z|+/-nnnn] */ -------

[0-2][0-9]:[0-6][0-9]:[0-6][0-9](,[0-9]+)?(Z|[+-][0-9]{4})? |

[0-2][0-9]:[0-6][0-9](Z|[+-][0-9]{4})?

----------/* V_ISO8601_EXTENDED_DATE YYYY-MM-DD */ -----------------------

[0-9]{4}-[0-1][0-9]-[0-3][0-9] |

[0-9]{4}-[0-1][0-9]

----------/* V_ISO8601_DURATION PnYnMnWnDTnnHnnMnnS */ -------------- here we allow a deviation from the standard to allow weeks to be -- mixed in with the rest since this commonly occurs in medicine

P([0-9]+[yY])?([0-9]+[mM])?([0-9]+[wW])?([0-9]+[dD])?T([0-9]+[hH])?([0-9]+[mM])?([0-9]+[sS])? |

P([0-9]+[yY])?([0-9]+[mM])?([0-9]+[wW])?([0-9]+[dD])?

----------/* V_TYPE_IDENTIFIER */ --------------------------------------

[A-Z]{IDCHAR}*

----------/* V_GENERIC_TYPE_IDENTIFIER */ ------------------------------

[A-Z]{IDCHAR}*<[a-zA-Z0-9,_<>]+>

----------/* V_ATTRIBUTE_IDENTIFIER */ ---------------------------------

[a-z]{IDCHAR}*

----------/* CADL Blocks */ ------------------------------------------

Editors:{T Beale, S Heard} Page 45 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

\{[^{}]* -- beginning of CADL block <IN_CADL_BLOCK>\{[^{}]* -- got an open brace <IN_CADL_BLOCK>[^{}]*\} -- got a close brace

----------/* V_INTEGER */ ---------------------------------------------

[0-9]+ | [0-9]+[eE][+-]?[0-9]+

----------/* V_REAL */ ------------------------------------------------

[0-9]+\.[0-9]+| [0-9]+\.[0-9]+[eE][+-]?[0-9]+

----------/* V_STRING */ ----------------------------------------------

\"[^\\\n"]*\"

\"[^\\\n"]*{ -- beginning of a multi-line string

<IN_STR> {\\\\ -- match escaped backslash, i.e. \\ -> \ \\\" -- match escaped double quote, i.e. \” -> “ {UTF8CHAR}+ -- match UTF8 chars [^\\\n"]+ -- match any other characters \\\n[ \t\r]* -- match LF in line [^\\\n"]*\" -- match final end of string

.|\n | <<EOF>> -- unclosed String -> ERR_STRING }

----------/* V_CHARACTER */ -------------------------------------------\'[^\\\n']\' -- normal character in 0-127 \'\\n\ -- \n \'\\r\ -- \r \'\\t\ -- \t \'\\'\ -- \’ \'\\\\ -- \\ \'{UTF8CHAR}\' -- UTF8 char \'.{1,2} |\'\\[0-9]+(\/)? -- invalid character -> ERR_CHARACTER

4.9 Syntax Alternatives

WARNING:the syntax in this section is not part of dADL

4.9.1 Container Attributes

A reasonable alternative to the syntax described above for nested container objects would have been to use an arbitrary member attribute name, such as “items”, or perhaps “_items” (in order to indicate to a parser that the attribute name cannot be assumed to correspond to a real property in an object model), as well as the key for each container member, giving syntax like the following:

people = < _items[1] = <name = <> birth_date = <> interests = <>> _items[2] = <name = <> birth_date = <> interests = <>> _items[3] = <name = <> birth_date = <> interests = <>>

>

Additionally, with this alternative, it becomes more obvious how to include the values of other properties of container types, such as ordering, maximum size and so on, e.g.:

Date of Issue: 13 Mar 2007 Page 46 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 dADL - Data ADL Rev 1.4.0

people = < _items[1] = <name = <> birth_date = <> interests = <>> _items[2] = <name = <> birth_date = <> interests = <>> _items[3] = <name = <> birth_date = <> interests = <>> _is_ordered = <True> _upper = <200>

>

Again, since the names of such properties in any given object technology cannot be assumed, the special underscore form of attribute names is used.

However, we are now led to somewhat clumsy paths, where “_items” will occur very frequently, due to the ubiquity of containers in real data:

/people/_items[1]/ /people/_items[2]/ /people/_items[3]/ /people/_is_ordered/ /people/_upper/

A compromise which satisfies the need for correct representation of all attributes of container types and the need for brevity and comprehensibility of paths would be to make optional the “_items”, but retain other container pseudo-attributes (likely to be much more rarely used), thus:

people = <

[1] = <name = <> birth_date = <> interests = <>>

[2] = <name = <> birth_date = <> interests = <>>

[3] = <name = <> birth_date = <> interests = <>> _is_ordered = <True> _upper = <200>

>

The above form leads to the following paths:

/people[1]/ /people[2]/ /people[3]/ /people/_is_ordered/ /people/_upper/

The alternative syntax in this subsection is not currently part of dADL, but could be included in the future, if there was a need to support more precise modelling of container types in dADL. If such support were to be added, it is recommended that the names of the pseudo-attributes (“_item”, “_is_ordered” etc) be based on names of appopriate container types from a recognised standard such as OMG UML, OCL or IDL.

Editors:{T Beale, S Heard} Page 47 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

dADL - Data ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

Date of Issue: 13 Mar 2007 Page 48 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

cADL - Constraint ADL

5.1 Overview

cADL is a syntax which enables constraints on data defined by object-oriented information models to be expressed in archetypes or other knowledge definition formalisms. It is most useful for defining the specific allowable constructions of data whose instances conform to very general object models. cADL is used both at “design time”, by authors and/or tools, and at runtime, by computational systems which validate data by comparing it to the appropriate sections of cADL in an archetype. The general appearance of cADL is illustrated by the following example:

PERSON[at0000] matches { -- constraint on PERSON instance

name matches { -- constraint on PERSON.name

TEXT matches {/.+/} -- any non-empty string

}

addresses cardinality matches {0..*} matches { -- constraint on

ADDRESS matches { -- PERSON.addresses -- etc -} } }

Some of the textual keywords in this example can be more efficiently rendered using common mathematical logic symbols. In the following example, the matches, exists and implies keywords have been replaced by appropriate symbols:

PERSON[at0000] ∈ { -- constraint on PERSON instance

name ∈ { -- constraint on PERSON.name

TEXT ∈ {/..*/} -- any non-empty string

}

addresses cardinality ∈ {0..*} ∈ { -- constraint on

ADDRESS ∈ { -- PERSON.addresses

-- etc -

}}}

The full set of equivalences appears below. Raw cADL is stored in the text-based form, to remove any difficulties with representation of symbols, to avoid difficulties of authoring cADL text in normal text editors which do not supply such symbols, and to aid reading in English. However, the symbolic form might be more widely used due to the use of tools, and formatting in HTML and other documentary formats, and may be more comfortable for non-English speakers and those with formal mathematical backgrounds. This document uses both conventions. The use of symbols or text is completely a matter of taste, and no meaning whatsoever is lost by completely ignoring one or other format according to one’s personal preference.

In the standard cADL documented in this section, literal leaf values (such as the regular expression /..*/ in the above example) are always constraints on a set of ‘standard’ widely-accepted primitive types, as described in the dADL section. Other more sophisticated constraint syntax types are described in cADL - Constraint ADL on page 49 .

Editors:{T Beale, S Heard} Page 49 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

5.2 Basics

5.2.1 Keywords

The following keywords are recognised in cADL:

• matches, ~matches, is_in, ~is_in • occurrences, existence, cardinality • ordered, unordered, unique
• infinity
• use_node, allow_archetype¹
• include, exclude

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

Textual Rendering	Symbolic Rendering	Meaning
matches, is_in	∈	Set membership, “p is in P”
not, ~	∼	Negation, “not p”

Keywords are shown in blue in this document.

The matches or is_in operator deserves special mention, since it is a key operator in cADL. This operator can be understood mathematically as set membership. When it occurs between a name 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 objects of a set of defined types. 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”.

aaa matches {/.*ion[^\s\n\t]/}-- the set of english words ending in ‘ion’

The following example links the name of a type XXX with a complex multi-dimensional value space.

XXX matches {

aaa matches { -

YYY matches {0..3} -

} -- the value space of the

bbb matches { -- and instance of XXX

ZZZ matches {>1992-12-01} -

} -}

The meaning of the constraint structure above is: in data matching the constraints, there is an instance of type XXX whose attribute values recursively match the inner constraints named after those attributes, and so on, to the leaf level.

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:

aaa ~matches {5}

1. was ‘use_archetype’, which is now deprecated

Date of Issue: 13 Mar 2007 Page 50 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4	cADL - Constraint ADL
	Rev 1.4.0
aaa ~is_in {5} aaa ∉{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.

5.2.2 Comments

In a cADL text, comments satisfy the following rule:

comments are indicated by the characters “--”. Multi-line comments are achieved using the “--” leader on each line where the comment continues. In this document, comments are shown in brown.

5.2.3 Information Model Identifiers

As with dADL, identifiers from the underlying information model are used for all cADL nodes. Identifiers obey the same rules as in dADL: type names commence with an upper case letter, while attribute and function names commence with a lower case letter. In cADL, type names and any property (i.e. attribute or function) name can be used, whereas in dADL, only type names and attribute names appear.

A type name is any identifier with an initial upper case letter, followed by any combination of letters, digits and underscores. A generic type name (including nested forms) additionally may include commas and angle brackets, but no spaces, and must be syntactically correct as per the UML. An attribute name is any identifier with an initial lower case letter, followed by any combination of letters, digits and underscores. Any convention that obeys this rule is allowed.

Type identifiers are shown in this document in all uppercase, e.g. PERSON, while attribute identifiers are shown in all lowercase, e.g. home_address. In both cases, underscores are used to represent word breaks. This convention is used to improve the readability of this document, and other conventions may be used, such as the common programmer’s mixed-case convention exemplified by Person and homeAddress. The convention chosen for any particular cADL document should be based on that used in the underlying information model. Identifiers are shown in green in this document.

5.2.4 Node Identifiers

In cADL, an entity in brackets e.g. [xxxx] is used to identify “object nodes”, i.e. nodes expressing constraints on instances of some type. Object nodes always commence with a type name. Any string may appear within the brackets, depending on how it is used. However, in this document, all node identifiers are of the form of an archetype term identifier, i.e. [atNNNN], e.g. [at0042]. Node identifiers are shown in magenta in this document.

5.2.5 Natural Language

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 ontology in the local language.

Editors:{T Beale, S Heard} Page 51 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

5.3 Structure

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 meaning “non-empty string”):

PERSON[at0001] ∈ { name ∈ {

PERSON_NAME[at0002] ∈ { forenames cardinality ∈ {1..*} ∈ {/.+/} family_name ∈ {/.+/} title ∈ {“Dr”, “Miss”, “Mrs”, “Mr”, ...}

} } addresses cardinality ∈ {1..*} ∈ {

LOCATION_ADDRESS[at0003] ∈ { street_number existence ∈ {0..1} ∈ {/.+/} street_name ∈ {/.+/} locality ∈ {/.+/} post_code ∈ {/.+/} state ∈ {/.+/} country ∈ {/.+/}

} } }

In the above, any identifier (shown in green) 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 come under the start of the line at the beginning of 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 properties (of that type), followed by types (being the types of the attribute under which it appears) until leaf nodes are reached.

We use the term “object” block or node to refer to any block introduced by a type name (in this document, in all upper case), while an “attribute” block or node is any block introduced by an attribute identifier (in all lower case in this document), as illustrated below.

FIGURE 4 Object and Attribute Blocks in cADL

5.3.1 Complex Objects

It may by now be clear that the identifiers in the above could correspond to entities in an object-ori ented information model. A UML model compatible with the example above is shown in FIGURE 5. Note that there can easily be more than one model compatible with a given fragment of cADL syntax,

Date of Issue: 13 Mar 2007 Page 52 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

1

PERSON_NAME PERSON

name

forenames[1..*]: String family_name[1]: String title[0..1]: String

ADDRESS

street_number[0..1]: String

*

street_name[1]: String

addresses

locality[1]: String post_code[1]: String state[1]: String country[1]: String

FIGURE 5 UML Model of PERSON

and in particular, there may be 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 which are useful or meaningful to constrain.

Constraints expressed in cADL cannot be stronger than those from the information model. For example, the PERSON.family_name attribute is mandatory in the model in FIGURE 5, 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. An example showing how to express a constraint on the value property of an ELEMENT class to be a QUANTITY with a suitable range for expressing blood pressure is as follows:

ELEMENT[at0010] matches { -- diastolic blood pressure value matches {

QUANTITY matches { magnitude matches {|0..1000|} property matches {"pressure"} units matches {"mm[Hg]"}

} } }

5.3.2 Attribute Constraints

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

5.3.2.1 Existence

The only constraint that applies to all attributes is to do with existence. Existence constraints say whether an attribute value must exist, and are indicated by “0..1” or “1” markers at line ends in UML diagrams (and often mistakenly referred to as a “cardinality of 1..1”). It is the absence or presence of

Editors:{T Beale, S Heard} Page 53 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

the cardinality constraint in cADL which indicates that the attribute being constrained is single-valued or a container attribute respectively. Existence constraints are expressed in cADL as follows:

QUANTITY matches { units existence matches {0..1} matches {“mm[Hg]”} }

The meaning of an existence constraint is to indicate whether a value - i.e. an object - is mandatory or optional (i.e. obligatory or not) in runtime data for the attribute in question. The above example indicates that a value for the ‘units’ attribute is optional. The same logic applies whether the attribute is of single or multiple cardinality, i.e. whether it is a container or not. For container attributes, the existence constraint indicates whether the whole container (usually a list or set) is mandatory or not; a further cardinality constraint (described below) indicates how many members in the container are allowed.

An existence constraint may be used directly after any attribute identifier, and indicates whether the object to which the attribute refers is mandatory or optional in the data.

Existence is shown using the same constraint language as the rest of the archetype definition. Existence constraints can take the values {0}, {0..0}, {0..1}, {1}, or {1..1}. The first two of these constraints may not seem initially obvious, but may be reasonable in some cases: they say that an attribute must not be present in the particular situation modelled by the archetype. The default existence constraint, if none is shown, is {1..1}.

5.3.3 Single-valued Attributes

Repeated blocks of object constraints of the same class (or its subtypes) can have two possible meanings in cADL, depending on whether the cardinality is present or not in the containing attribute block. With no cardinality, the meaning is that each child object constraint of the attribute in question is a possible alternative for the value of the attribute in the data, as shown in the following example:

ELEMENT[at0004] matches { -- speed limit

value matches {

QUANTITY matches {

magnitude matches {|0..55|}

property matches {"velocity"}

units matches {"mph"} -- miles per hour }

QUANTITY matches {

magnitude matches {|0..100|}

property matches {"velocity"}

units matches {"km/h"} -- km per hour

}}}Here, the cardinality of the value attribute is 1..1 (the default), while the occurrences of both QUANTITY constraints is optional, leading to the result that only one QUANTITY instance can appear in runtime data, and it can match either of the constraints.

Two or more object blocks introduced by type names appearing after an attribute which is not a container (i.e. for which there is no cardinality constraint) are taken to be alternative constraints, only one of which needs to be matched by the data.

Note that there is a more efficient way to express the above example, using domain type extensions See Customising ADL on page 105 for examples.

Date of Issue: 13 Mar 2007 Page 54 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

5.3.4 Container Attributes

5.3.4.1 Cardinality

Container attributes are indicated in cADL with the cardinality constraint. Cardinalities indicate limits on the number of members of instances of container types such as lists and sets. Consider the following example:

HISTORY occurrences ∈ {1} ∈ { periodic ∈ {False}

events cardinality ∈ {*} ∈ {

EVENT[at0002] occurrences ∈ {0..1} ∈ {} -- 1 min sample EVENT[at0003] occurrences ∈ {0..1} ∈ {} -- 2 min sample EVENT[at0004] occurrences ∈ {0..1} ∈ {} -- 3 min sample

} }

The keyword cardinality indicates firstly that the property events must be of a container type, such as List<T>, Set<T>, Bag<T>. The integer range indicates the valid membership of the container; a single ‘*’ means the range 0..*, i.e. ‘0 to many’. The type of the container is not explicitly indicated, since it is usually defined by the information model. However, the semantics of a logical set (unique membership, ordering not significant), a logical list (ordered, non-unique membership) or a bag (unordered, non-unqique membership) can be constrained using the additional keywords ordered, unordered, unique and non-unique within the cardinality constraint, as per the following examples:

events cardinality ∈ {*; ordered} ∈ { -- logical list events cardinality ∈ {*; unordered; unique} ∈ { -- logical set events cardinality ∈ {*; unordered} ∈ { -- logical bag

In theory, none of these constraints can be stronger than the semantics of the corresponding container in the relevant part of the reference model. However, in practice, developers often use lists to facilitate integration, when the actual semantics are intended to be of a set; in such cases, they typically ensure set-like semantics in their own code rather than by using an Set<T> type. How such constraints are evaluated in practice may depend somewhat on knowledge of the software system.

A cardinality constraint may be used after any attribute name (or after its existence constraint, if there is one) in order to indicate that the attribute refers to a container type, what number of member items it must have in the data, and optionally, whether it has “list”, “set”, or “bag” semantics, via the use of the keywords ordered, unordered, unique and non-unique.

The numeric part of the cardinality contraint can take the values {0}, {0..0}, {0..n}, {m..n}, {0..*}, or {*}. The first two of these constraints are unlikely to be useful, but there is no reason to prevent them. There is no default cardinality, since if none is shown, the relevant attribute is assumed to be single-valued (in the interests of uniformity in archetypes, this holds even for smarter parsers that can access the reference model and determine that the attribute is in fact a container.

Cardinality and existence constraints can co-occur, in order to indicate various combinations on a container type property, e.g. that it is optional, but if present, is a container that may be empty, as in the following:

events existence ∈ {0..1} cardinality ∈ {0..*} ∈ {-- etc --}

5.3.4.2 Occurrences

A constraint on occurrences is used only with cADL object nodes (not attribute nodes), to indicate how many times in runtime data an instance of a given class conforming to a particular constraint can occur. It only has significance for objects which are children of a container attribute, since by definition, the occurrences of an object which is the value of a single-valued attribute can only be 0..1 or

Editors:{T Beale, S Heard} Page 55 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

1..1, and this is already defined by the attribute existence. However, it is not illegal. In the example below, three EVENT constraints are shown; the first one (“1 minute sample”) is shown as mandatory, while the other two are optional.

events cardinality ∈ {*} ∈ {EVENT[at0002] occurrences ∈ {1..1} ∈ {} -- 1 min sampleEVENT[at0003] occurrences ∈ {0..1} ∈ {} -- 2 min sampleEVENT[at0004] occurrences ∈ {0..1} ∈ {} -- 3 min sample

}Another contrived example below expresses a constraint on instances of GROUP such that for GROUPs representing tribes, clubs and families, there can only be one “head”, but there may be many members.

GROUP[at0103] ∈ { kind ∈ {/tribe|family|club/} members cardinality ∈ {*} ∈ {

PERSON[at0104] occurrences ∈ {1} ∈ { title ∈ {“head”} -- etc -

}

PERSON[at0105] occurrences ∈ {0..*} ∈ { title ∈ {“member”} -- etc -

}}}The first occurrences constraint indicates that a PERSON with the title “head” is mandatory in the GROUP, while the second indicates that at runtime, instances of PERSON with the title “member” can number from none to many. Occurrences may take the value of any range including {0..*}, meaning that any number of instances of the given class may appear in data, each conforming to the one constraint block in the archetype. A single positive integer, or the infinity indicator, may also be used on its own, thus: {2}, {*}. A range of {0..0} or {0} indicates that no occurrences of this object are allowed in this archetype. The default occurrences, if none is mentioned, is {1..1}.

An occurrences constraint may appear directly after any type name, in order to indicate how many times data objects conforming to the block introduced by the type name may occur in the data.

Where cardinality constraints are used (remembering that occurrences is always there by default, if not explicitly specified), cardinality and occurrences must always be compatible. The validity rule is:

VCOC: cardinality/occurrences validity: the interval represented by: (the sum of all occurrences minimum values) .. (the sum of all occurrences maximum values) must be inside the interval of the cardinality.

5.3.5 “Any” Constraints

There are two cases where it is useful to state a completely open, or “any”, constraint. The “any” constraint is shown by a single asterisk (*) in braces. The first is when it is desired to show explicitly that some property can have any value, such as in the following:

PERSON[at0001] matches { name existence matches {0..1} matches {*} -- etc -

}

Date of Issue: 13 Mar 2007 Page 56 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

The “any” constraint on name means that any value permitted by the underlying information model is also permitted by the archetype; however, it also provides an opportunity to specify an existence constraint which might be narrower than that in the information model. If the existence constraint is the same, an “any” constraint on a property is equivalent to no constraint being stated at all for that property in the cADL.

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

ELEMENT[at0004] matches { -- speed limit value matches {QUANTITY matches {*}}}The meaning of this constraint is that in the data at runtime, the value property of ELEMENT must be of type 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.

5.3.6 Object Node Identification and Paths

In many of the examples above, some of the object node typenames are followed by a node identifier, shown in brackets.

Node identifiers are required for any object node which is intended to be addressable elsewhere in the cADL text, or in the runtime system and which would otherwise be ambiguous i.e. has sibling nodes.

In the following example, the PERSON type does not require an identifier, since no sibling node exists at the same level, and unambigous paths can be formed:

members cardinality ∈ {*} ∈ { PERSON ∈ { title ∈ {“head”} } }

The path to the title attribute is

members/title

However, where there are more than one sibling node, node identifiers must be used to ensure distinct paths:

members cardinality ∈ {*} ∈ { PERSON[at0104] ∈ {

title ∈ {“head”} } PERSON[at0105] matches {

title ∈ {“member”} } }

The paths to the respective title attributes are now:

members[at0104]/title members[at0105]/title

Logically, all non-unique parent nodes of an identified node must also be identified back to the root node. The primary function of node identifiers is in forming paths, enabling cADL nodes to be unambiguously referred to. The node identifier can also perform a second function, that of giving a design-

Editors:{T Beale, S Heard} Page 57 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

time meaning to the node, by equating the node identifier to some description. Thus, in the example shown in section 5.3.1, the ELEMENT node is identified by the code [at0010], which can be designated elsewhere in an archetype as meaning “diastolic blood pressure”.

Node ids are required only where it is necessary to create paths, for example in “use” statements. However, the underlying reference model might have stronger requirements. The openEHR EHR information models [17] for example require that all node types which inherit from the class LOCATABLE have both a archetype_node_id and a runtime name attribute. Only data types (such as QUANTITY, CODED_TEXT) and their constituent types are exempt.

Paths are used in cADL to refer to cADL nodes, and are expressed in the ADL path syntax, described in detail in section 7 on page 25. ADL paths have the same alternating object/attribute structure implied in the general hierarchical structure of cADL, obeying the pattern TYPE/attribute/TYPE/attribute/... .

Paths in cADL always refer to object nodes, and can only be constructed through nodes having node ids, or nodes which are the only child object of a single-cardinality attribute.

Unusually for a path syntax, a trailing object identifier can be required, even if the attribute corresponds to a single relationship (as might be expected with the “name” property of an object) because in cADL, it is legal to define multiple alternative object constraints - each identified by a unique node id - for a relationship node which has single cardinality.

Consider the following cADL example:

HISTORY occurrences ∈ {1} ∈ { periodic ∈ {False} events cardinality ∈ {*} ∈ {

EVENT[at0002] occurrences ∈ {0..1} ∈ {} -- 1 min sampleEVENT[at0003] occurrences ∈ {0..1} ∈ {} -- 2 min sampleEVENT[at0004] occurrences ∈ {0..1} ∈ {} -- 3 min sample

} }

The following paths can be constructed:

/ -- the HISTORY object /periodic -- the HISTORY.periodic attribute /events[at0002] -- the 1 minute event object /events[at0003] -- the 2 minute event object /events[at0004] -- the 3 minute event object

It is valid to add attribute references to the end of a path, if the underlying information model permits it, as in the following example.

/events/count -- count attribute of the items property

These examples are physical paths because they refer to object nodes using codes. Physical paths can be converted to logical paths using descriptive meanings for node identifiers, if defined. Thus, the following two paths might be equivalent:

/events[at0004] -- the 3 minute event object /events[3 minute event] -- the 3 minute event object

None of the paths shown here have any validity outside the cADL block in which they occur, since they do not include an identifier of the enclosing document, normally an archetype. To reference a cADL node in a document from elsewhere (e.g. another archetype of a template) requires that the identifier of the document itself be prefixed to the path, as in the following archetype example:

[openehr-ehr-entry.apgar-result.v1]/events[at0002]

Date of Issue: 13 Mar 2007 Page 58 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

This kind of path expression is necessary to form the larger paths which occur when archetypes are composed to form larger structures.

5.3.7 Internal References

It occurs reasonably often that one needs to include a constraint which is a repeat of an earlier complex constraint, but within a different block. This is achieved using an archetype internal reference, according to the following rule:

An archetype internal reference is introduced with the use_node keyword, in a line

of the following form:

use_node TYPE object_path

This statement says: use the node of type TYPE, found at (the existing) path object_path. The following example shows the definitions of the ADDRESSnodes for phone, fax and email for a home CON-

use_node ADDRESS /contacts[at0004]/addresses[at0005] -- phone

TACT being reused for a work CONTACT.
PERSON ∈ {identities ∈ {-- etc -
}contacts cardinality ∈ {0..*} ∈ {CONTACT [at0002] ∈ { purpose ∈ {-- etc --} addresses ∈ {-- etc --} }CONTACT [at0003] ∈ { purpose ∈ {-- etc --} addresses ∈ {-- etc --} }CONTACT [at0004] ∈ { purpose ∈ {-- etc --} addresses cardinality ∈ {0..*} ∈ {ADDRESS [at0005] ∈ {type ∈ {-- etc --}details ∈ {-- etc --} }ADDRESS [at0006] ∈ {type ∈ {-- etc --}details ∈ {-- etc --} }ADDRESS [at0007] ∈ {type ∈ {-- etc --}details ∈ {-- etc --} }}}CONTACT [at0008] ∈ { purpose ∈ {-- etc --} addresses cardinality ∈ {0..*} ∈ {	-- home address -- postal address -- home contact -- phone -- fax -- email -- work contact

use_node ADDRESS /contacts[at0004]/addresses[at0006] -- fax use_node ADDRESS /contacts[at0004]/addresses[at0007] -- email

}}}

Editors:{T Beale, S Heard} Page 59 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

The type mentioned in the use_node reference must always be the same type as, or a super-type of the referenced type. In most cases, it will be the same. In some cases, an archetype section might use a subtype of the type required by the reference model (e.g. in the above example, a type such as POSTAL_ADDRESS); a use_node reference to such a node can legally mention the parent type (ADDRESS, in the example). Whether this possibility has practical utility remains to be seen.

VUNT: use_node type: the type mentioned in a use_node must be the same as or a super-type (according to the reference model) of the reference model type of the node referred to.

Like any other object node, a node defined using an internal reference has occurrences. Unlike other node types, if no occurrences is mentioned, the value of the occurrences is set to that of the referenced node (which if not explicitly mentioned will be the default occurrences). However, the occurrences can be overridden in the referring node as well, as in the following example which enables the specification for ‘phone’ to be re-used, but with a different occurrences constraint.

PERSON ∈ {contacts cardinality ∈ {0..*} ∈ {CONTACT [at0004] ∈ { -- home contact addresses cardinality ∈ {0..*} ∈ {ADDRESS [at0005] occurrences ∈ {1} ∈ {...}-- phone

}}CONTACT [at0008] ∈ { -- work contact

addresses cardinality ∈ {0..*} ∈ {use_node ADDRESS occurrences ∈ {0..*}/contacts[at0004]/addresses[at0005] -- phone }}}

5.3.8 Archetype Slots

At any point in a cADL definition, a constraint can be defined which allows other archetypes to be used, rather than defining the desired constraints inline. This is known as an archetype “slot”, or “chaining point”, i.e. a connection point whose allowable fillers are constrained by a set of state ments, written in the ADL assertion language (defined in section 5 on page 23).

An archetype slot is defined in terms of two lists of assertions statements defining which archetypes are allowed and/or which are excluded from filling that slot.

An archetype slot is introduced with the keyword allow_archetype, and is expressed using two lists of assertions, introduced with the keywords include and exclude, respectively.

Since archetype slots are typed, the (possibly abstract) type of the allowed archetypes is already constrained. Otherwise, any assertion about a filler archetype can be made. The assertions do not constrain data in the way that other archetype statements do, instead they constrain archetypes. Two kinds of reference may be used in a slot assertion. The first is a reference to an object-oriented property of the filler archetype itself, where the property names are defined by the ARCHETYPE class in the Archetype Object Model. Examples include:

archetype_id parent_archetype_id short_concept_name

This kind of reference is usually used to constrain the allowable archetypes based on archetype_id or some other meta-data item (e.g. archetypes written in the same organisation). The second kind of ref-

Date of Issue: 13 Mar 2007 Page 60 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

erence is to absolute paths in the definition section of the filler archetype (i.e. ‘archetype paths’ as used throughout this section of the specification). Both kinds of reference take the form of an Xpathstyle path, with the distinction that paths referring to ARCHETYPE attributes not in the definition section do not start with a slash (this allows parsers to easily distinguish the two types of reference).

Defining Slots on the basis of Archetype Identifiers and Concepts

A basic kind of assertion is on the identifier of archetypes allowed in the slot. This is achieved with statements like the following in the include and exclude lists:

archetype_id ∈ {/.*\.SECTION\..*\..*/} -- match any SECTION archetype

It is possible to limit valid slot-fillers to a single archetype simply by stating a full archetype identifier with no wildcards; this has the effect that the choice of archetype in that slot is predetermined by the archetype and cannot be changed later. In general, however, the intention of archetypes is to provide highly re-usable models of real world content with local constraining left to templates, in which case a ‘wide’ slot definition is used (i.e. matches many possible archetypes).

The following example shows how the “Objective” SECTION in a problem/SOAP headings archetype defines two slots, indicating which OBSERVATION and SECTION archetypes are allowed and excluded under the items property.

SECTION [at2000] occurrences ∈ {0..1} ∈ { -- objective

items cardinality ∈ {0..*} ∈ {

allow_archetype OBSERVATION occurrences ∈ {0..1} ∈ {

include

short_concept_name ∈ {/.+/}}allow_archetype SECTION occurrences ∈ {0..*} ∈ {

include

archetype_id ∈ {/.*\.iso-ehr\.SECTION\..*\..*/}

exclude

archetype_id ∈ {/.*\.iso-ehr\.SECTION\.patient_details\..*/}}}}Here, every constraint inside the block starting on an allow_archetype line contains constraints that must be met by archetypes in order to fill the slot. In the examples above, the constraints are in the form of regular expression syntax. In cADL, the PERL version of this is assumed.

Using Other Constraints in Slots

Other constraints are possible as well, including that the allowed archetype must contain a certain keyword, or a certain path. The latter allows archetypes to be linked together on the basis of content. For example, under a “genetic relatives” heading in a Family History Organiser archetype, the following slot constraint might be used:

allow_archetype EVALUATION occurrences ∈ {0..*} matches {

include

short_concept_name ∈ {“risk_family_history”} ∧∃ /subject/relationship/defining_code

→ ∼

/subject/relationship/defining_code/code_list.has([openehr::0]) -- “self”

}This says that the slot allows archetypes on the EVALUATION class, which either have as their concept “risk_family_history” or, if there is a constraint on the subject relationship, then it may not include the code [openehr::0] (the openEHR term for “self”) - i.e. it must be an archetype designed for family members rather than the subject of care herself.

Editors:{T Beale, S Heard} Page 61 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

Formal Semantics of include and exclude Lists

To Be Continued: rules for precedence of exclusions over inclusions.

5.3.9 Placeholder Constraints

Not all constraints can be defined easily within an archetype. One common category of constraint that should be defined externally, and referenced from the archetype is the ‘value set’ for a coded attribute. The need within the archetype in this case is to limit an attribute value to a particular set of codes, i.e. value set, from a terminology.

The value set could be simply enumerated within the archetype, for example using the C_CODE_PHRASE type defined in the openEHR Archetype Profile; this will work perfectly well, but has at least two limitations. Firstly, the intended set of values allowed for the attribute may change over time (e.g. as has happened with ‘types of hepatitis’ since 1980), requiring the archetype to be updated. With a large repository of archetypes, each containing coded term constraints, this approach is likely to be unsustainable and error-prone. Secondly, the best means of defining the value set is in general not likely to be via enumeration of the individual terms, but in the form of a semantic expression that can be evaluated against the terminology. This is because the value set is typically logically specified in terms of inclusions, exclusions, conjunctions and disjunctions of general categories.

Consider for example the value set logically defined as “any bacterial infection of the lung”. The possible values would be codes from a target terminology, corresponding to numerous strains of pneumococcus, staphlycoccus and so on, but not including species that are never found in the lung. Rather than enumerate the list of codes corresponding to this value set (which is likely to be quite large), the archetype author is more likely to rely on semantic links within the terminology to express the set; a query such as ‘is-a bacteria and has-site lung’ might be definable against the terminology (such as SNOMED-CT or the WHO ICD10 terminology).

In a similar way, other value sets, including for quantitative values, are likely to be specified by queries or formal expressions, and evaluated by an external knowledge service. Examples include “any unit of pressure” and “normal range values for serum sodium”.

In all such cases, expressing the constraint could be done by including the query or other formal expression within the archetype itself. However, experience shows that this is problematic in various ways. Firstly, there is little if any standardisation in such formal value set expressions or queries for use with knowledge services; two archetype authors could easily create competing syntactical expressions for the same logical constraint. A second problem is that errors might be made in the query expression itself, or the expression may be correct at the time of authoring, but need subsequent adjustment as the relevant knowledge resource grows and changes. The consequence of this is the same as for a value set enumerated inline - it is unlikely to be sustainable for large numbers of archetyes. These problems are not accidental: a query with respect to a terminological, ontological or other knowledge resource is most likely to be authored correctly by maintainers or experts of the knowledge resource, rather than archetype authors; it may well be altered over time due to improvements in the query formalism itself.

The solution adopted in ADL is to store only identifiers of query expressions which when evaluated return a required value set, while query expressions are assumed to be stored in a query repository, or some part of the relevant knowedge service. Rather than store external identifiers inline in a cADL text, the ADL approach is to store a ‘placeholder’ internal code of the form [acNNNN], e.g. [ac0012]. Codes of this form are defined in the archetype ontology section, and can be mapped to query identifiers for one or more knowledge resources. This approach would allow a single ‘ac’ code to be defined for the value set.

Date of Issue: 13 Mar 2007 Page 62 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

5.3.10 Mixed Structures

Three types of structure representing constraints on complex objects have been presented so far:

• complex object structures: any node introduced by a type name and followed by {} containing constraints on attributes;
• internal references: any node introduced by the keyword use_node, followed by a type name; such nodes indicate re-use of a complex object constraint that has already been expressed elsewhere in the archetype;
• archetype slots: any node introduced by the keyword allow_archetype, followed by a type name; such nodes indicate a complex object constraint which is expressed in some other archetype.

At any given node, all three types can co-exist, as in the following example:

SECTION[at2000] ∈ {

items cardinality ∈ {0..*; ordered} ∈ { ENTRY[at2001] ∈ {-- etc --} allow_archetype ENTRY ∈ {-- etc --} use_node ENTRY [at0001]/some_path[at0004]/ ENTRY[at2002] ∈ {-- etc --} use_node ENTRY /[at1002]/some_path[at1012]/ use_node ENTRY /[at1005]/some_path[at1052]/ ENTRY[at2003] ∈ {-- etc --}

} }

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 ‘in place’ (the details are removed here, for brevity); 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 (again, avoided for the sake of brevity). Note also that the ordered keyword has been used to indicate that the list order is intended to be significant.

5.4 Constraints on Primitive Types

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

some_attr matches {some_pattern}

rather than:

some_attr matches { PRIMITIVE_TYPE matches {

some_pattern

} }

This is made 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. Currently the cADL grammar only supports the brief form used in this specifica

Editors:{T Beale, S Heard} Page 63 of 115 Date of Issue: 13 Mar 2007

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

cADL - Constraint ADL Archetype Definition Language ADL 1.4 Rev 1.4.0

tion since no practical reason has been identified for supporting the more verbose version. Theoretically however, there is nothing to prevent it being used in the future, or in some specialist application.

5.4.1 Constraints on String

Strings can be constrained in two ways: using a list of fixed strings, and using using a regular expression. All constraints on strings are case-sensitive.

5.4.1.1 List of Strings

A String-valued attribute can be constrained by a list of strings (using the dADL syntax for string lists), including the simple case of a single string. Examples are as follows:

species ∈ {“platypus”}

species ∈ {“platypus”, “kangaroo”}

species ∈ {“platypus”, “kangaroo”, “wombat”}

The first example constraints the runtime value of the species attribute of some object to take the value “platypus”; the second constrains it be either “platypus” or “kangaroo”, and so on. In almost all cases, this kind of string constraint should be avoided, since it usually renders the body of the archetype language-dependent. Exceptions are proper names (e.g. “NHS”, “Apgar”), product trade-names (but note even these are typically different in different language locales, even if the different names are not literally translations of each other). The preferred way of constraining string attributes in a language independent way is with local [ac] codes. See Local Constraint Codes on page 28.

5.4.1.2 Regular Expression

The second way of constraining strings is with regular expressions, a widely used syntax for expressing patterns for matching strings. The regular expression syntax used in cADL is a proper subset of that used in the Perl language (see [18] for a full specification of the regular expression language of Perl). Three uses of it are accepted in cADL:

string_attr matches {/regular expression/}

string_attr matches {=~ /regular expression/}

string_attr matches {!~ /regular expression/}

The first two are identical, indicating that the attribute value must match the supplied regular expression. The last indicates that the value must not match the expression. If the delimiter character is required in the pattern, it must be quoted with the backslash (‘\’) character, or else alternative delimiters can be used, enabling more comprehensible patterns. A typical example is regular expressions including units. The following two patterns are equivalent:

units ∈ {/km\/h|mi\/h/}

units ∈ {^km/h|mi/h^}

The rules for including special characters within strings are described in File Encoding and Character Quoting on page 21 .

The regular expression patterns supported in cADL are as follows.

Atomic Items

. match any single character. E.g. / ... / matches any 3 characters which occur with a space before and after;

[xyz] match any of the characters in the set xyz (case sensitive). E.g. /[0-9]/ matches any string containing a single decimal digit;

[a-m] match any of the characters in the set of characters formed by the continuous range from a to m (case sensitive). E.g. /[0-9]/ matches any single character string containing a single decimal digit, /[S-Z]/ matches any single character in the range S -Z;

Date of Issue: 13 Mar 2007 Page 64 of 115 Editors:{T Beale, S Heard}

© 2003-2007 The openEHR Foundation. email: info@openEHR.org web: http://www.openEHR.org

Archetype Definition Language ADL 1.4 cADL - Constraint ADL Rev 1.4.0

[^a-m] match any character except those in the set of characters formed by the continuous range from a to m. E.g. /[^0-9]/ matches any single character string as long as it does not contain a single decimal digit;

Grouping

(pattern)parentheses are used to group items; any pattern appearing within parentheses is treated as an atomic item for the purposes of the occurrences operators. E.g. /([0-9][09])/ matches any 2-digit number.

Occurrences

* match 0 or more of the preceding atomic item. E.g. /.*/ matches any string; /[a-z]*/ matches any non-empty lower-case alphabetic string;

+ match 1 or more occurrences of the preceding atomic item. E.g. /a.+/ matches any string starting with ‘a’, followed by at least one further character;

? match 0 or 1 occurrences of the preceding atomic item. E.g. /ab?/ matches the strings “a” and “ab”;

{m,n} match m to n occurrences of the preceding atomic item. E.g. /ab{1,3}/ matches the strings “ab” and “abb” and “abbb”; /[a-z]{1,3}/ matches all lower-case alphabetic strings of one to three characters in length;

{m,} match at least m occurrences of the preceding atomic item;

{,n} match at most n occurrences of the preceding atomic item;

{m} match exactly m occurrences of the preceding atomic item;

Special Character Classes

\d, \D match a decimal digit character; match a non-digit character;

\s, \S match a whitespace character; match a non-whitespace character;

Alternatives

pattern1|pattern2 match either pattern1 or pattern2. E.g. /lying|sitting|standing/ matches any of the words “lying”, “sitting” and “standing”.

A similar warning should be noted for the use of regular expressions to constrain strings: they should be limited to non-linguistically dependent patterns, such as proper and scientific names. The use of regular expressions for constraints on normal words will render an archetype linguistically dependent, and potentially unusable by others.

5.4.2 Constraints on Integer

Integers can be constrained using a list of integer values, and using an integer interval.

5.4.2.1 List of Integers