Modeling:

If we want to switch to ADL 2, we need some kind of transition period. Some CDRs will not support ADL 2 yet, some might. We could take one of two possible modeling approaches:

• Model in ADL/OPT 1.4, convert to 2

• Model in ADL 2/OPT 2, convert to 1.4

There are several tools available that can convert from ADL 1.4/OPT 1.4 to ADL 2 already. At some point it is likely we want to switch modelling to ADL 2 natively. For that, we would need at least, during the transition period:

Adl 2 -> 1.4 converter
Opt 2 -> opt 1.4 converter

Modeling tool upgrades

CKM Upgrade: it can now only store ADL 1.4, but it has a feature to export ADL 2 at the moment

Graceful degradation for unsupported features possible? Potentially tricky things:

• binding strength

• namespaces

• groups (not yet supported in Archie)

• annotations (some possible in OPT!)

• value terminology bindings?

• ?

Specialisations can be converted without problems. ADL 2 handles the validation, and valid specialisation can be converted.

The impact is mainly for tooling development. The specification may need to address how graceful degradation in conversion from ADL 2 to ADL 1.4 works.

Thing to check: do we actually need to ADL 2 to ADL 1.4 converter, or just the OPT converter?

Upgrading the archetypes in the CKM

 At some point we will need to upgrade the source of archetypes. Possible strategies:

• Convert all archetypes in the CKM to ADL 2 at once

• A hybrid/gradual strategy, be able to switch to ADL on a per archetype basis

Other open questions:

• What to do with the history of archetypes

CDR

Blockers:

• id/ac/at instead of atxxxx-codes

• at0001 will become id2 (node id), or ac2 (value set), or at2 (value code)

• templates are specialisations, so .1 syntax of codes in ADL 2

• namespace makes inheritance tricky in CDR

• Template ids are now archetype ids, before they were a different syntax

• more blockers present?

Possible solutions for ID/AT-codes problem

• Convert the ADL2 to OPT 2 with at000x-syntax

• Migrate to new numbers for new archetypes, keep using the at000x-style numbers for old archetypes

• Change ADL 2 to use at000x style codes

• Change ADL 2 to use id/ac/at-codes, but use id0 as first code instead of id1

• Define a way so that both old and new queries work at both data formats

Convert the ADL 2 to OPT 2 with at000x syntax

• define OPT 2 with at codes

• autogenerated from archetypes

• Convert Idx codes to at000x-style codes

• for specializations introduced in templates, remove the .1. This likely should be configurable

• need check: possible to always remove the specialisation from template codes? Sibling nodes with same at-codes possible in OPT 1.4?

• Benefits

  • No change needed to ADL 1.4 CDRs in the short term

  • no change needed to ADL 2 CDRs ever

• Drawbacks

  • some systems will have different codes than others. Interoperability will become more complicated

    • conversion could solve this

  • Migration remains hard for ADL 1.4 CDRs

Change ADL 2 to use id/ac/at-codes, but use id0 as first code instead of id1

• Define a new ADL version, and a way to indicate in ADL which system is used (machine recognizable!). ADL 3?

• Write converters for the current ADL 2 archetypes

• Adapt existing modeling tools to work with the new codes

• Nedap will need to do some kind of migration to be standards compliant again (same migration as the others would need to do)

• benefits

  • interoperability is easier without conversion

  • less work to migrate ADL 1.4 CDRs

• drawbacks

  • work to migrate ADL 2 CDRs

• Blocking issues:

  • id0.1 is both the root node for a specialised archetype, AND a newly added non-root node in a specialised archetype

    • tricky to solve - specific root node syntax? keep it at at0000 or id0000?

Change ADL 2 to use at000x style codes

Create a new ADL version that is ADL 2, but with at000x style codes

This keeps the full code syntax of ADL 1.4. The specialisation syntax that is currently underspecified in ADL 1.4 will need to be specified much better.

Benefits:

• ADL 1.4 CDRs require no change

• interoperability/data requires no change

Drawbacks:

• ADL 2 CDRs require a full migration

• All modeling tools and libraries supporting ADL 2 will need change

• slightly incoherent code system

Migrate to new numbers for new archetypes, keep using the at000x-style numbers for old archetypes

benefits:

• no migration of data for ADL 1.4 CDRs

drawbacks

• ADL 2 CDRs will require a migration, or suffer reduced interoperability

  • conversion can solve this

• ADL 1.4 CDRs will require a change

Define a way so that both old and new queries work at both data formats

impact: to be checked

Interoperability:

• convert RM data, basics done in Archie proof of concept

• accept .1 data (templates!) For ADL 1.4 templates? Or just convert those as well? Slightly more complicated, but possible: you need the path to inheritance root of archetypes for that

Result still two dataformats: with id codes or with at codes, with template specialisation or not.

• define profiles for in between steps?

• define the wanted long term situation - what to migrate towards

AQL, inheritance and specialized codes (templates!):

An AQL query requesting at0053 now does not in all CDRs query for at0053.1 or at0053.0.1

This does solve real problems in disambiguating nodes in templates. But the AQL implementation in CDRs does not work this way.

Steps to take:

• Define how this should work in the AQL engine (Thomas will create issue)

• Make impact analysis for this change – how can we migrate existing queries, what will break, etc.

• Check if we need to add some kind of migration strategy

Inheritance/namespaces:

• add full path to root of inheritance tree to every archetype used in OPT 2 (specialization/inheritance lineage):

• this archetypes parent is x. Its parent is y. Y has no parent.

Other solution:

Ians archetype id syntax convention (todo: ask Ian about his syntax so we can add it here

ADL2 - Analysis by Ian McN and Sebastian Garde

The headings are taken from a list produced by Thomas as the key developments in ADL2. Most of the ‘challenges’ are already captured above but this analysis also includes the benefits - these are primarily to modellers but e.g. coded name/value overrides in templates are also useful to CDR builders

1. Making specialisation work - by differential specialisation + inheritance flattening

Benefits

• Handling specialisation diffs is more logical in tooling and easier to manage changes to upstream artefacts

• Ultimately ‘less code’

• Specialisation by slot-filling is now a preferred pattern v.s simple inheritance. ADL2 supports this more cleanly

Challenges:

• Issues of legacy conversion

• Ultimately the correct flattened version needs to be created/recreated in tooling such as CKM - on the fly or cached??

• Reviews need to be based on a specific flattened version -

• Ongoing issues of version dependency management - need better semver use ? package.json or embedded semvers.

• If semver is the answer, do we put the dependencies inside artefacts or outside e.g package.json

• Is the natural primary artefact actually a bundle inside a zip container? with a minimum of a package.json manifest

• Does this change AQL behaviour?

• Do we differentiate compound, specialised archetypes (slot-fills) from templates (really constrained profiles)

2.Templates as archetypes and overlays, solving all the existing redefinition, template id, versioning and language problems

Benefits

• Cleaner implementation (no .oet), archetypes and templates are almost identical

• proper multi-language support

• coded node name overrides

• Proper support for

• Enhanced design-time artefacts - e.g template-level descriptions, hide-on-form, RM attribute visbility etc mostly supported by 1.4 /1.5 but not well by .oet

Challenges:

• Not clear how this affects querying - existing templates are profiles on composition not specialisation of composition - does the aQL path change?

• CKM would need .oet->Adl2 convertor (as per AD) - still some conversion issues in AD. Needs to be a community effort

• Issues for historical CKM reviews

• Moving from MD5 hashes to semver

• How to handle legacy template Ids. Need for fully-defined concept names as well as formal templateId and root template node rename.

3. Tuples to replace irregular special constructs for C_DV_QUANTITY, C_DV_ORDINAL and C_CODE_PHRASE

TOOLING: minor benefit. Streamlining ? add to 1.5

4. ADL enhancements

• default values on any node

• node ordering - before and after keywords

• direct archetype inclusion for re-use - supported by C_ARCHETYPE_ROOT and use_archetype

• make cardinality and existence constraints optional: mandatory ‘existence’ was the #1 complaint for a long while!

• plus a lot of properly defined semantics for node-level conformance, congruence, flattening

5. Regular internal code system / Greatly improved modelling of terminology constraint

Benefits

• tidies up name vs. value codes but was that ever a real problem

• more consistent numbering (“less code”)

• approach is closer to FHIR Valuesets but lacks e.g nested values, multi- terminology valueset, mapping constraints

Challenges

• complex and risky to convert atCodes to iDcodes

• Terminology handling feels very messy to me. Argument for using FHIR Valuesets and Codesystem as baseline then enhance?

6. Name-spaced archetype ids: allowing archetypes from different institutions with the same concept name to be distinguished (e.g. NHS bp_measurement and Norway bp_measurement)

Benefits

• Will become significant as complex systems evolve

Challenges

• Current approach is tricky for CDRs as it did not seem possible to carry the full specialisation linegae with in the archetype Id as we do in ADL1.4 usingf the - character to denote aspecialisaiton

• In ADL2 therefore, the full specialisation lineage has to be carried either in the patient data or in some external index (- the NEDAP approach) especially when the parent and child namespaces differ

Examples of a possible solution

When Thomas, Sebastian, Heather and I looked at this originally it did not seem possible to cleanly embed namespaces in a single string.

However we had another go at this recently…

Single domain, not specialised

org.openehr::OPENEHR-EHR-OBSERVATION.blood_pressure.v2

Single domain specialisation (specialisation namespace defaults to parent)

org.openehr::OPENEHR-EHR-OBSERVATION.blood_pressure.v2-variant.v1

Mixed domain specialisation

This is the apperta.org uk Variant.v1 specialisation of the openehr.org blood pressure archetype

uk.org.apperta::OPENEHR-EHR-OBSERVATION.org.openehr::blood_pressure.v2-ukvariant.v1

an alternative might be

uk.org.apperta::org.openehr::OPENEHR-EHR-OBSERVATION.blood_pressure.v2-ukvariant.v1

i.e chain the namespaces at the start and each segment corresponds to each specialisation level in reverse

So if Catalunya then specialises the same archetype, we get

es.catalunya::uk.org.apperta::org.openehr::OPENEHR-EHR-OBSERVATION.blood_pressure.v2-ukvariant.v1-my_catalan_variant.v1

If CDR vendors are happy to handle the specialisation lineages in a different way , that's fine - we are not particularly arguing for the use of this syntactical approach.