Archetype Definition Language 2 (ADL2)

Acknowledgements

Primary Author

  • Thomas Beale, Ars Semantica, UK; openEHR International Board.

Contributors

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

  • 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

  • Silje Ljosland Bakke, RN, Nasjonal IKT HF, Norway

  • Pieter Bos, Software Engineer, Nedap, Netherlands

  • Eric Browne PhD, HealthBase Australia

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

  • Joey Coyle MD, PhD, Intermountain Healthcare, New York

  • Borut Fabjan, Program Manager, Better d.o.o., Slovenia

  • Adam Flinton, NHS Connecting for Health, UK

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

  • Sebastian Garde, PhD, Ocean Informatics, Germany

  • Andrew Goodchild PhD, Distributed Systems Technology Centre, Australia

  • Peter Gummer MSc, Ocean Informatics

  • Sam Heard MD, Ocean Informatics

  • Mark Kramer, Division Chief Engineer, Health Technology Center, The Mitre Corporation, USA

  • Patrick Langford, NeuronSong LLC

  • 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

  • Claude Nanjo MA African Studies, M Public Health, Cognitive Medical Systems Inc., California

  • 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 MSc, Mayo Clinic, Rochester, USA

  • Alessandro Torrisi, Code24, Netherlands

  • Zar Zar Tun, Distributed Systems Technology Centre, Australia

  • Bert Verhees, ROSA Software, The Netherlands.

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:

  • the openEHR Industry Partners;

  • Ars Semantica, UK;

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

  • Ocean Informatics, Australia.

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).

Preface

Purpose

This document describes the design basis and syntax of the Archetype Definition Language (ADL) 2.x, a new major version of ADL, containing structural changes with respect to the ADL 1.x versions.

It is intended for software developers, technically-oriented domain specialists and subject matter experts (SMEs). ADL is designed as an abstract human-readable and computer-processable syntax. ADL archetypes can be hand-edited using a normal text editor.

The intended audience includes:

  • Standards bodies producing health informatics standards;

  • Research groups using openEHR, ISO 13606, and other EHR or EHR exchange architectures;

  • The open source healthcare community;

  • EHR solution vendors;

  • Medical informaticians and clinicians interested in health information.

Related Documents

Prerequisite documents for reading this document include:

Related documents include:

Nomenclature

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

We also use the word 'archetype' in a broad sense to designate what are commonly understood to be 'archetypes' (specifications of clinical data groups / data constraints) and 'templates' (data sets based on archetypes, since at a technical level, an ADL/AOM 2 template is in fact just an archetype. Accordingly, statements about 'archetypes' in this specification can be always understood to also apply to templates, unless otherwise indicated.

Status

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

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

TBD: (example To Be Determined paragraph)

Feedback

Feedback may be provided on the openEHR ADL forum.

Issues may be raised on the specifications Problem Report tracker.

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

Conformance

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

Tools

Various tools exist for creating and processing archetypes. The ADL Workbench is a reference compiler, visualiser and editor. The openEHR ADL/AOM 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;

  • the revision_history section is removed, since the AOM2 uses the openEHR Base Types version of the Resource package.

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 definition, 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 [cADL - Constraint ADL] or [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 archetypes 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

AM Release 2.3.0

2.3.0

SPECAM-75. Improve specification of constraint patterns (addresses problem SPECPR-374). Modified [date_time_constraint_patterns] to include timezone constraints.

P Pazos,
T Beale

20 Dec 2022

SPECAM-76. Correct VSONCO rule for redefinition of nodes with multiple occurrences; improve text in [Redefinition Concepts] and [Occurrences Redefinition] (addresses problem SPECPR-374).

P Bos,
S Garde,
I McNicoll,
P Pazos,
J Holslag,
T Beale

05 Aug 2022

SPECAM-74. Replace reference to VCOC with reference to VACMCU, VACMCO validity rules.

P Pazos,
T Beale

15 Aug 2021

SPECAM-69. Support negative durations (see also SPECRM-96); add examples in [_duration_constraints].

P Bos,
S Garde

09 Sep 2020

SPECAM-68. Add flexible constraint_status indicator to C_TERMINOLOGY_CODE; add related keywords to terminology constraints; see sections [_soft_terminology_constraint] and [_terminology_constraint_redefinition].

B Fabjan,
I McNicoll,
S Garde,
P Bos

07 Sep 2020

SPECAM-66: Improve specification of default values, including support for other syntaxes.

P Bos,
T Beale

20 May 2020

SPECPUB-7: Convert citations to bibtex form.

T Beale

15 Dec 2019

AM Release 2.2.0

2.2.0

SPECAM-63. Add rm_overlay top-level section with rm_visibility sub-section to state hide/show and RM attribute aliasing.

I McNicoll,
S L Bakke,
B Fabjan,
T Beale

17 Apr 2019

SPECAM-61. Remove revision_history from ADL2 specification.

D Bosca,
P Bos,
T Beale

04 Apr 2019

SPECAM-60. Improve documentation for constraints on lists and intervals.

B Fabjan,
M Pipan,
T Beale

21 Jan 2019

SPECAM-58. Correct errors and improve examples - S Garde review Nov 2018.

S Garde

18 Nov 2018

Update link for ARCHETYPE_ID syntax from ADL2 spec to link directly to BASE. (Fixes SPECPR-267).

S Garde

03 Nov 2018

Correct node identifier typos in section 9.5.1.

M Kramer

28 Oct 2018

AM Release 2.1.0

2.1.0

SPECAM-56. Correct ordering in flattening example in section 9.

P Bos

24 Aug 2018

SPECAM-53. Remove statement requiring node-id redefinition in case of occurrences redefinition (corrects SPECPR-269)

P Bos

26 May 2018

SPECAM-50. Improve documentation of ADL2 templates (section 10).

T Beale

31 Jan 2018

SPECAM-47. Allow regularly structured primitive objects.

J Coyle,
T Beale

07 Jan 2018

SPECAM-45. Correct specification details to do with sibling_order anchor node id. (Corrects SPECPR-245)

P Bos,
T Beale

21 Nov 2017

Fix types in identifiers in redefinition example (section 9.5.5). (SPECPR-238);
Minor inconsistencies in ADL2 spec specialisation section (section 9.2.5, 9.3.1, 9.3.2)(SPECPR-239).

P Bos

04 Oct 2017

AM Release 2.0.6

2.0.6

Correct ambiguity between ADL and AOM specs concerning duration fractional seconds - add comment in 'Duration Constraints' section to cover fractional seconds. (SPECPR-188).

B Verhees

10 Jun 2016

Fix typos in ADL grammar: meta_data_tag_is_controlled value corrected to 'controlled' and meta_data_tag_is_generated corrected to 'generated'; adjust meta_data_item rule slightly for clarity.
Add reference in section `Reference Model Type Matching' to more precise specification of type matching in AOM2 spec.

C Nanjo

08 Jun 2016

Rename archetype rule in grammar to authored_archetype to match AOM2 class (SPECPR-190).

B Verhees

18 May 2016

Change Rules section to document re-use of new openEHR Expression Language.
Re-order sub-sections under 9.5 to be more logical;
Add a new sub-section in the Specialisation section 'Single and Multiple Specialisation - When does Cloning Occur?';
Improve explanation of cloning.

T Beale

11 May 2016

2.0.5

Re-order Specialisation section subsections 10.2 and 10.3 (examples and concepts);
Correct C_TEMPORAL.pattern_constraint to optional. (SPECPR-175);
Correct multiplicity on constraint to 0..* except for C_INTEGER and C_REAL.

T Beale

21 Mar 2016

Rewrite Terminology Integration section. Add template section.

T Beale

10 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

Release 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

Release 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 ISO 8601-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 ISO 8601 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

Release 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

Release 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

Release 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

Sections