Appendix

Acknowledgements

Primary Author

  • Thomas Beale, Ocean Informatics UK; openEHR Foundation Management Board

Contributors

This specification and its sibling Archetype Definition Language specification have benefited from wide formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people and institutions.

  • Seref Arikan, MEcon, Ocean Informatics UK, Centre for Health Informatics and Multi-professional Education (CHIME), UCL, UK

  • John Arnett, NHS Connecting for Health, UK

  • Koray Atalag PhD, University of Auckland, NZ

  • Tony Austin PhD, Centre for Health Informatics and Multi-professional Education (CHIME), UCL, UK

  • Eric Browne PhD, HealthBase Australia

  • Rong Chen MD, PhD, Cambio Heath Systems, Sweden

  • Adam Flinton, NHS Connecting for Health, UK

  • Matias Forss MSc, Institute of Technology at Linköping University

  • Sebastian Garde, PhD, Ocean Informatics

  • Andrew Goodchild PhD, Distributed Systems Technology Centre, Australia

  • Peter Gummer MSc, Ocean Informatics

  • Sam Heard MD, Ocean Informatics

  • Jose Alberto Maldondo PhD, Universitat Politècnica de València, Spain

  • David Moner PhD, Universitat Politècnica de València, Spain

  • Isabel Román Martínez PhD, Universitat de Sevilla, Spain

  • Ian McNicoll MD, MSc, Ocean Informatics UK

  • Andrew Patterson PhD, LLM, Federation Health Software, Australia

  • Ognian Pishev PhD, Australia, Ocean Informatics

  • Rahil Qamar Siddiqui PhD, NHS Health & Social Care Information Centre, UK

  • Prof Alan Rector MD, PhD, University of Manchester, UK

  • Harold Solbrig PhD, Mayo Clinic, Rochester, USA

  • Alessandro Torrisi, Code24, Netherlands

  • Zar Zar Tun, Distributed Systems Technology Centre, Australia

Thanks to Sebastian Garde, Central Qld University, Australia, for German translations.

Trademarks

  • 'Microsoft' and '.Net' are registered trademarks of the Microsoft Corporation.

  • 'Java' is a registered trademark of Oracle Corporation

  • 'Linux' is a registered trademark of Linus Torvalds.

  • 'openEHR' is a registered trademark of The openEHR Foundation

  • 'SNOMED CT' is a registered trademark of IHTSDO

Supporters

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

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

  • Ocean Informatics.

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

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

Changes from Previous Versions

For existing users of ADL or archetype development tools, the following provides a guide to the changes in the syntax.

dADL (ODIN)

The object syntax used to represent the description, terminology and annotations sections of an ADL archetype has been historically known as 'dADL' (i.e. 'data ADL'). Since this syntax is completely generic and has no specific dependency on either ADL or openEHR, it has been separated out into its own specification known as Object Data Instance Notation (ODIN).

ADL 2.0

Changes

The changes in version 2.0 are designed to make archetypes more computable with respect to terminology. The changes with respect to 1.x versions include:

  • the internal node identification system has been changed so that at-codes are no longer used to identify nodes; instead, 'id-codes' are used for that purpose;

  • all nodes now require an id-code;

  • rules for the construction of node identifier codes in specialised archetypes;

  • the ontology section has been renamed `terminology;

  • value sets are now declared in their own subsection of the terminology section rather than inline in the definition section;

Backward Compatibility

In its current form, the changes to the internal coding system and value set representation in ADL 2.x and the AOM with respect to ADL/AOM 1.5 constitute syntactically breaking changes, and therefore require conversion of ADL 1.4 archetypes to ADL 2 form. The changes have been carefully designed to allow this conversion to be implementable, and are implemented in the ADL Workbench tool. ADL 1.4 style paths are generatable from ADL 2 archetypes, so that AQL queries can be built for use with ADL 1.4 based data.

ADL 1.5

Changes

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

The changes for ADL 1.5 include:

  • optional generated marker in the archetype first line;

  • the semantics of reference model subtype matching are now described;

  • a differential expression form allows specialised archetypes to be expressed efficiently and ensures they are maintainable;

  • new keywords for defining the order of specialised object nodes within container attributes;

  • an explanation of how to use the negated match operator (~matches, or ∈) to define value set exclusions in specialised archetypes;

  • a description of the semantics of 'inheritance-flattened' archetypes;

  • optional annotations section added to archetypes;

  • declarations and invariants sections merged into rules section;

  • In the ADL grammar, the language section is now mandatory;

  • .adls files are introduced as the standard file extension for differential ADL files (.adl files are retained for standalone, inheritance-flattened, or 'flat', archetype).

Nearly all the changes occur in the section [cADL - Constraint ADL] or the new section [Specialisation].

ADL 1.4

A number of small changes were made in this version, along with significant tightening up of the explanatory text and examples.

ISO 8601 Date/Time Conformance

All ISO 8601 date, time, date/time and duration values in dADL are now conformant (previously the usage of the 'T' separator was not correct). Constraint patterns in cADL for dates, times and date/times are also corrected, with a new constraint pattern for ISO 8601 durations being added. The latter allows a deviation from the standard to include the 'W' specifier, since durations with a mixture of weeks, days etc is often used in medicine.

Non-inclusive Two-sided Intervals

It is now possible to define an interval of any ordered amount (integer, real, date, time, date/time, duration) where one or both of the limits is not included, for example:

    |0..<1000|    -- 0 >= x < 1000
    |>0.5..4.0|   -- 0.5 > x <= 4.0
    |>P2d..<P10d| -- 2 days > x < 10 days

Occurrences for 'use_node' References

Occurrences can now be stated for use_node references, overriding the occurrences of the target node. If no occurrences is stated, the target node occurrences value is used.

Quoting Rules

The old quoting rules based on XML/ISO mnemonic patterns (&ohmgr; etc) are replaced by specifying ADL to be UTF-8 based, and any exceptions to this requiring ASCII encoding should use the \Uhhhh style of quoting unicode used in various programming languages.

ADL 1.3

The specific changes made in version 1.3 of ADL are as follows.

Query syntax replaced by URI data type

In version 1.2 of ADL, it was possible to include an external query, using syntax of the form:

    attr_name = <query("some_service", "some_query_string")>

This is now replaced by the use of URIs, which can express queries, for example:

    attr_name = <http://some.service.org?some%20query%20etc>

No assumption is made about the URI; it need not be in the form of a query - it may be any kind of URI.

Top-level Invariant Section

In this version, invariants can only be defined in a top level block, in a way similar to object-oriented class definitions, rather than on every block in the definition section, as is the case in version 1.2 of ADL. This simplifies ADL and the Archetype Object Model, and makes an archetype more comprehensible as a type definition.

ADL 1.2

ADL Version

The ADL version is now optionally (for the moment) included in the first line of the archetype, as follows.

    archetype (adl_version=1.2)

It is strongly recommended that all tool implementors include this information when archetypes are saved, enabling archetypes to gradually become imprinted with their correct version, for more reliable later processing. The adl_version indicator is likely to become mandatory in future versions of ADL.

dADL (ODIN) Syntax Changes

The dADL (now ODIN) syntax for container attributes has been altered to allow paths and typing to be expressed more clearly, as part of enabling the use of Xpath-style paths. ADL 1.1 dADL had the following appearance:

	school_schedule = <
		locations(1) = <...>
		locations(2) = <...>
		locations(3) = <...>
		subjects("philosophy:plato") = <...>
		subjects("philosophy:kant") = <...>
		subjects("art") = <...>
	>

This has been changed to look like the following:

	school_schedule = <
		locations = <
			[1] = <...>
			[2] = <...>
			[3] = <...>
		>
		subjects = <
			["philosophy:plato"] = <...>
			["philosophy:kant"] = <...>
			["art"] = <...>
		>
	>

The new appearance both corresponds more directly to the actual object structure of container types, and has the property that paths can be constructed by directly reading identifiers down the backbone of any subtree in the structure. It also allows the optional addition of typing information anywhere in the structure, as shown in the following example:

	school_schedule = SCHEDULE <
		locations = LOCATION <
			[1] = <...>
			[2] = <...>
			[3] = ARTS_PAVILLION <...>
		>
		subjects = <
			["philosophy:plato"] = ELECTIVE_SUBJECT <...>
			["philosophy:kant"] = ELECTIVE_SUBJECT <...>
			["art"] = MANDATORY_SUBJECT <...>
		>
	>

These changes will affect the parsing of container structures and keys in the description and terminology parts of the archetype.

Revision History Section

Revision history is now recorded in a separate section of the archetype, both to logically separate it from the archetype descriptive details, and to facilitate automatic processing by version control systems in which archtypes may be stored. This section is included at the end of the archetype because it is in general a monotonically growing section.

Primary_language and Languages_available Sections

An attribute previously called primary_language was required in the ontology section of an ADL 1.1 archetype. This is renamed to original_language and is now moved to a new top level section in the archetype called language. Its value is still expressed as a dADL String attribute. The languages_available attribute previously required in the ontology section of the archetype is renamed to translations, no longer includes the original languages, and is also moved to this new top level section.

Amendment Record

Issue Details Raiser, Implementer Completed

2.0.5

Rewrite Terminology Integration section. Add template section.

T Beale

13 Jan 2016

Upgrade specification to ADL 2.x level. Reduce overview text.

openEHR

12 Nov 2014

Change use_archetype syntax to include id-code.

T Beale,
P Langford

17 July 2014

Corrections on semantics of node id redefinition in Specialisation section; correct further typos.

H Solbrig

25 June 2014

Add support for constraints on enumeration types.

T Beale,
CIMI

20 June 2014

Move terminology value set constraints to terminology section;
SPECAM-28. Add IHTSDO standard terminology URIs to ADL and AOM.

T Beale,
H Solbrig

17 May 2014

2.0.0

New format term codes & mandatory node ids.

T Beale

7 Jan 2014

Convert 'placeholder' (ac-code) constraint to primitive terminology type constraint.

H Solbrig

Add archetype id namespacing.

T Beale,
I McNicoll

24 Nov 2014

Add tuple construct.

T Beale

20 Aug 2013

Remove dADL syntax description to new ODIN specification.

T Beale

22 Apr 2013

SPECAM-20: Allow cardinality keyword on its own to indicate container attributes, even if no other constraints required.

D Moner

21 Mar 2012

SPECAM-8: Add specialisation semantics to ADL and AOM.
Improve explanation of node identifiers.
Correct typographical errors.
Make concept optional.
Refine slot include/exclude rules.
Review of text & validity rules.

S Heard
O Pishev
T Beale

Deprecate terminologies_available statement in terminology section.

T Beale

Add fractional seconds to dADL grammar.

S Arikan

SPECAM-7. Make existence, occurrences and cardinality optional in AOM.

S Garde
S Heard

SPECAM-5. Archetype slot regular expressions should cover whole identifier. Added C_STRING.is_pattern.

A Flinton

R E L E A S E     1.0.2

1.4.1

SPEC-268: Correct missing parentheses in dADL type identifiers. dADL grammar and cADL scanner rules updated.

R Chen

12 Dec 2008

SPEC-284: Correct inconsistencies in naming of term_definitions, constraint_definitions, term_bindings, constraint_bindings attributes in XML-schema and specifications.
Improved explanatory text for composite identifiers, including statement on case-sensitivity. Warning on .v1draft non-conformance

A Torrisi

SPEC-260: Correct the regex published for the ARCHETYPE_ID type. Update ADL grammar ARCHEYTPE_ID definition.

P Gummer,
J Arnett,
E Browne

R E L E A S E     1.0.1

1.4.0

SPEC-203: Release 1.0 explanatory text improvements. Improve Archetype slot explanation.

T Beale

13 Mar 2007

SPEC-208: Improve ADL grammar for assertion expressions.

T Beale

SPEC-160: Duration constraints. Added ISO 8601 patterns for duration in cADL.

S Heard

SPEC-213: Correct ADL grammar for date/times to be properly ISO8601-compliant. Include 'T' in cADL patterns and dADL and cADL Date/time, Time and Duration values.

T Beale

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

S Heard

SPEC-200: Correct Release 1.0 typographical errors.

A Patterson
R Chen
S Garde
T Beale

SPEC-225: Allow generic type names in ADL.

M Forss

SPEC-226: Rename C_CODED_TEXT to C_CODE_PHRASE

T Beale

SPEC-233: Define semantics for occurrences on ARCHETYPE_INTERNAL_REF.

K Atalag

SPEC-241: Correct cADL grammar for archeype slot match expressions

S Heard

SPEC-223: Clarify quoting rules in ADL

A Patterson

SPEC-242: Allow non-inclusive two-sided ranges in ADL.

S Heard

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

S Heard

R E L E A S E     1.0

1.3.1

SPEC-136. Add validity rules to ADL document.

T Beale

18 Jan 2006

SPEC-171. Add validity check for cardinality & occurrences

A Maldondo

1.3.0

SPEC-141. Allow point intervals in ADL. Updated atomic types part of cADL section and dADL grammar section.

S Heard

18 Jun 2005

SPEC-142. Update dADL grammar to support assumed values.
SPEC-143. Add partial date/time values to dADL syntax.
SPEC-149. Add URIs to dADL and remove query() syntax.
SPEC-153. Synchronise ADL and AOM for language attributes
SPEC-156. Update documentation of container types.
SPEC-138. Archetype-level assertions.

T Beale

R E L E A S E     0.95

1.2.1

SPEC-125. C_QUANTITY example in ADL manual uses old dADL syntax.
SPEC-115. Correct "/[xxx]" path grammar error in ADL.
Create new section describing ADL path syntax.
SPEC-127. Restructure archetype specifications. Remove clinical constraint types section of document.

T Beale

11 Feb 2005

1.2

SPEC-110. Update ADL document and create AOM document.

T Beale

15 Nov 2004

Added explanatory material; added domain type support; rewrote of most dADL sections. Added section on assumed values, "controlled" flag, nested container structures. Change language handling.
Rewrote OWL section based on input from: University of Manchester, UK; University Seville, Spain.

A Rector
R Qamar
I Román Martínez

Various changes to assertions due to input from the DSTC.

A Goodchild
Z Z Tun

Detailed review from Clinical Information Project, Australia.

E Browne

Remove UML models to "Archetype Object Model" document.

T Beale

Detailed review from CHIME, UCL.

T Austin

SPEC-103. Redevelop archetype UML model, add new keywords: allow_archetype, include, exclude.

T Beale

SPEC-104. Fix ordering bug when use_node used. Required parser rules for identifiers to make class and attribute identifiers distinct.

K Atalag

Added grammars for all parts of ADL, as well as new UML diagrams.

T Beale

R E L E A S E     0.9

1.1

SPEC-79. Change interval syntax in ADL.

T Beale

24 Jan 2004

1.0

SPEC-77. Add cADL date/time pattern constraints.
SPEC-78. Add predefined clinical types. Better explanation of cardinality, occurrences and existence.

S Heard,
T Beale

14 Jan 2004

0.9.9

SPEC-73. Allow lists of Reals and Integers in cADL.
SPEC-75. Add predefined clinical types library to ADL.
Added cADL and dADL object models.

T Beale,
S Heard

28 Dec 2003

0.9.8

SPEC-70. Create Archetype System Description. Moved Archetype Identification Section to new Archetype System document. Copyright Assgined by Ocean Informatics P/L Australia to The openEHR Foundation.

T Beale,
S Heard

29 Nov 2003

0.9.7

Added simple value list continuation (",…​"). Changed path syntax so that trailing '/' required for object paths.
Remove ranges with excluded limits.
Added terms and term lists to dADL leaf types.

T Beale

01 Nov 2003

0.9.6

Additions during HL7 WGM Memphis Sept 2003

T Beale

09 Sep 2003

0.9.5

Added comparison to other formalisms. Renamed CDL to cADL and dDL to dADL. Changed path syntax to conform (nearly) to Xpath. Numerous small changes.

T Beale

03 Sep 2003

0.9

Rewritten with sections on cADL and dDL.

T Beale

28 July 2003

0.8.1

Added basic type constraints, re-arranged sections.

T Beale

15 July 2003

0.8

Initial Writing

T Beale

10 July 2003