ADL2 backward compatible code system

Owned by Thomas Beale
Last updated: 20-Mar-2020 by Pieter Bos
3 min read

ADL2 introduced a new kind of code, the id-code, and also more consistent rules on codes, as follows:

  • codes used to identify nodes are id-codes, not at-codes - only id-codes can appear in paths
  • at-codes cannot be used for both identification and value set members
  • at the top level, the 0-filled 4 digit pattern is gone, and all codes are always of the form xxNZZ, where N is a natural (non-zero) number, and Z is an integer. There is no longer any zero-filling, so now all codes obey the same rules throughout the archetype.
  • the archetype root code for a top level archetype is now 'id1', and those of child archetypes are 'id1.1', 'id1.1.1' etc. The removes the anomaly that any code could start with a zero, other than dotted codes introduced at lower levels.

See here for the original work on this.

These rules have the effect that the codes of an ADL1.4 archetype are upgraded on the fly during conversion, as follows:

  • change any at code used as a node identified from atNNNN to idN+1 (at0000 → id1; at0013 → id14 etc). The addition of 1 is to account for upgrading the at0000 root code.
  • add 1 to each at-code and remove zero-filling, e.g. at0026 → at27
  • add 1 to each ac-code and remove zero-filling, e.g. ac0020 → ac21
  • these rules apply to the root part of specialised codes of the form xxZZZZ.Z.Z; the part of such codes after the first decimal point are unchanged.
  • synthesise id-codes for nodes that don't have them

This code transform can be made reversible from an ADL2 archetype to the ADL1.4 form, for purposes such as:

  • saving the archetype in ADL 1.4. form, e.g. for older tools
  • generating the ADL 1.4. path-set for use with AQL queries written based on the ADL 1.4 form of the archetype.

To achieve round-tripping of the code transform, the following rule must be observed in the creation of any new ADL2 authored archetype:

  • generate the numeric part of the top-level of any code (i.e. the part before any decimal point) in a single ascending numeric series, e.g. id1, id2, at3, id4, id5, id6, ac7, at8, at9, at10, id11, and so on. This ensures that the id- and at-codes from the ADL2 code set can be merged into a single series of at-codes for the ADL 1.4 form.

For the most pedantic form of down-conversion of ADL2 codes, id-codes on nodes that don't need them in ADL 1.4 should be removed (rather than converted down to at-codes).

Synthesizing codes

Synthesizing new codes for constraints that did not have a code in ADL 1.4 presents a small problem. Once the ADL 1.4 gets edited, the new codes added in the ADL 1.4 edit should not conflict with the converted ADL 2. So, it should be done as follows:

  • Generate the numeric part of the top level of any codes from a single range, starting at 9000, so id9000, at9001, ac9002, etc
  • If adding a new code at a specialization level, also start from that range, so id0.9000, at0.9001, ac0.9002

Editing ADL 1.4: keeping the ADL 2 conversion backwards compatible

To keep the ADL 2 conversion backwards compatible after the ADL 1.4 form of the archetype has been edited, the same codes should be generated at the same path at subsequent conversions. To do this, the Archie project created a separate conversion log, to be stored together with the ADL 2 archetype. It is not specified and standardized yet, but its implementation can be found at https://github.com/openEHR/archie/tree/master/aom/src/main/java/com/nedap/archie/adl14/log