ADL2 Evolution

This page is to document ideas on the evolution of ADL2 past release 2.3.0..

Needs

Various needs have been identified, including:

• replace ODIN with JSON, YAML, etc, or possibly a choice between such formats

• allow free naming of node codes rather than the numeric idNNN codes (atNNN and acNNN codes would remain numeric). This makes id-codes more like ontology entity names, which is they role they have.

• allow more meta-data within terminology definitions and bindings

• more powerful annotations to support application form building

• more powerful / better defined rules

• tuple constraints for non-primitive structures

• a constraint type for links / references that would allow stating of the type and possibly archetype of the target

• better way to manage translations

• probably others.

Strategy

The approach to realising changes is to describe a detailed Change Request for each requirement above (i.e. as we typically do for any change), and determine if it is breaking or not. The idea is to prioritise all the non-breaking changes within further ADL2.x versions. If there are any breaking changes, we’ll record them against a notional ADL3 version. Within the ADL2 versions, the changes would be ordered so as to maximise value and manage impact.

Impact will potentially occur in various places:

• specifications

• authoring tools

• SDK & form builders

• CKM and other management and dissemination repositories

• operational CDRs

• CDR data

• archetype-based querying

• REST APIs

The changes are described below.

Key Codes

Description

This feature would add synonyms of the current id-codes (and possibly at-codes and ac-codes) in the form of freely named codes, known as keys, such as ‘systolic_pressure’ and ‘date_first_recognized’.

These codes can be thought of as similar to variable names in source code files, i.e. human-comprehensible names for entities that in the executable form are identified by meaningless numbers or addresses.

The keys can be used in various generated artefacts such as:

• JSON flat 'templates' (aka web templates) of the form in wide use in the openEHR community;

• Template Data Schemas (TDSs) in XML or JSON schema form;

• Template Data Objects (TDOs) i.e. generate micro-API objects with properties / methods named using the keys, e.g. ‘set_systolic_pressure ()’ etc;

• A more human-readable form of AQL paths.

TBD more

Benefits

This change would:

• enable human-readable paths to be standardised within archetypes, rather than relying on generator algorithms in disparate tools to generate keys and paths.

Impact Analysis

Advanced Form

In a more advanced environment, the keys could be used as the principle codes instead of the id-codes. This would remove the ability to infer subsumption based on the dotted code system in use since ADL1.4, e.g. id4.0.3 is a specialization of id4 (at top level), introduced 2 specialization levels down. With freely-named codes, the IS-A relationships have to be asserted within the archetype terminology. This is a breaking change, and would only be possible by moving to a new major version of ADL, nominally 'ADL3'.

The value of doing this is primarily to reduce the fragility of archetypes with the dotted code system for refactoring the specialisation hierarchy, in particular inserting a new archetype between two others in a specialisation relationship. Today, this breaks the codes of the lower archetype(s) because the dotted codes are specific to specialisation level. Pushing an archetype down a level means that that codes introduced by it (not inherited) must all have another dotted segment. Example: the code id2.1 would become id2.0.1.

Powerful refactoring tools could of course perform such changes automatically, with some subsequent manual fixing (as in typical programming refactoring tools), but paths in queries and forms would break as well, and would require conversion to the new paths.

Replace ODIN

Description

Motivation: ODIN is a custom openEHR serialisation format not used elsewhere in industry. Parsing and serialising to it requires custom software.

Alternatives:

• JSON is the most obvious and most programming languages have a way of serialising an in-memory object to JSON

  • however, JSON schema support may be needed to deal with polymorphic type substitutions

• YAML is more readable and also widely supported, although there appears to be some variability in implementations of some of the more complex YAML semantics

• JSON5 is more readable than JSON and better supports large blocks of multi-line text, and has bidirectional converters in and out of JSON

More than one of these could potentially be supported, although sticking with just one is likely to make everyone’s lives simpler.

Another factor to consider is whether we want to use the ‘compact’ formats described here to represent near-leaf level objects as single parsable strings.

Benefits

This change would:

• simplify ADL / AOM based software by allowing 3rd party and built-in libraries for data representation (JSON, YAML etc) to be used instead of maintaining the custom ODIN code currently in use

• JSON/JSON5/YAML

Impact Analysis

Link / Reference Constraint

Description

The requirement here is to support a kind of constraint that works something like a slot, except for objects that carry references to other objects, e.g. openEHR LINK, DV_EHR_URI and so on.

Discourse discussions:

• Archetyping links and references

Benefits

TBD

Impact Analysis

Non-Primitive Tuple Constraint

Description

The need is to be able to represent tuples whose elements are non-primitive archetype nodes, i.e. C_COMPLEX_OBJECTs in AOM terms. Primitive tuples are already solved, as shown in this archetype.

Non-primitive tuples are needed to solve openEHR ACTION archetypes and also Graphite lab analyte archetypes.

This archetype shows how the former would look, with a tuple of ACTION.data/description and transition tuples.

Benefits

TBD

Impact Analysis

Better Terminology and Binding Meta-data

Description

TBD

Benefits

TBD

Impact Analysis

More Powerful Annotations

Description

xxx

Benefits

TBD

Impact Analysis

Separate Translation Files

Description

Currently one archetype contains all its translations. Some archetypes with numerous translations are very large text files. Size isn’t a serious problem for tools or parsers, but the ongoing changes and additions to translated content mean that the archetype is constantly being re-versioned when no semantic changes are being made.

A better approach may be to separate the core archetype file with meta-data in one language (typically English, but doesn’t have to be) and put each translation of the meta-data & terminology in its own file, which would be separately versioned.

We would retain the hash map structure of meta-data (i.e. keyed by language) such that today’s many-language archetype could be reconstituted from the separate files.

In a similar way, an ADL2 OPT could be generated from the separate files to contain just specific languages, e.g. for deployments that need multiple languages at runtime.

Benefits

TBD

Impact Analysis

More Powerful Rules

Description

xxx

Benefits

TBD