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?
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
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?
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
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
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
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)
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
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.
TOOLING: minor benefit. Streamlining ? add to 1.5
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
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
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?
Will become significant as complex systems evolve
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.