Proposal for a coding system for ADL 3:

The root node has its own node id prefix, rn. This makes a root node of a top level archetype always rn0. A root node of a specialised archetype will have .1 added for every level of specialisation. For example, specialised once it will be rn0.1, specialised twice rn0.1.1
specialised root node: rn0000.1, rn0000.1.1.1

nodes at root level:

at0001, at0002, at0003, etc

for value codes, value set codes and node codes

specialised nodes:

at0001.1, at0001.2, at0001.3, etc

new nodes in specialised archetype:

at0.1, at0.2, etc

Changes between ADL 1.4 and version X left in RM

OPT is a specialisation

specialised codes

OPT is a specialisation. Any changes in nodes will result in a specialised node id. So, if you have an archetype with a eye acuity:

and you want to change something in this ELEMENT in a template, you get a new node id:

This has benefits:

• it is now possible to address specific nodes in a template. When a user is editing data, it is easy to link the data to the definition, because the node id contains all necessary information

• translations in OPT are now possible

Migration

• With OPT1.4 additional attribute changes are required in order to bind to a specific node - most common is a name constraint, for example:

  Open

  

• Paths then need to use syntax with /data[at0001]/items[at0009, ‘Initial Reaction Event’] or /data[at0001]/items[at0009, ‘Longterm Reaction Event’] in order to match the first or the second occurence. Archetype designer though already keeps a separate code when modelling so it’s only the export to 1.4 OPT that removes this distinction.

• TODO: We need to decide how to migrate this

• Possible strategies:

  • With no data migration

    • accept existing data as is (it will not be queryable with specialised codes)

    • keep new data in the new format (it will be queryable with existing AQLs - provided we apply AQL rule where /items[at0009] matches as at0009.* and names of specialised nodes match)

  • With data migration

    • This might not be always possible (not all historic templates might be available) - but would involve identifying templates with such specializations and conversion of RM data based on combination of node id and name

    • After migration existing and new data will be queryable with old style or new style AQLs

Archetype ids: namespaces as a part of an id, full semantic versioning

Namespaces

In ADL 1.4, namespaces can be added in metadata. However, they have no formal meaning. In ADL 2 this changes: namespaces are part of an archetype id. For example, the following to archetype ids refer to different archetypes:

These namespaces will appear in the RM data when archetypes are referenced. Also an archetype can specialise an archetype from a different namespace:

For example com.some.company::openEHR-EHR-COMPOSITION.blood_pressure.v1.0.1 can be a specialisation of org.openehr::openEHR-EHR-COMPOSITION.blood_pressure.v1.0.1. This means the current way of how CDRs handle inheritance may need changes.

proposed change in OPT 2: for every archetype or template mentioned in an OPT 2, its full inheritance lineage must be included, up to its top level archetype. That way, CDRs can determine the inheritance of any archetype, or any archetype id, for use in AQL queries

Proposed migration solution: Do not use namespaces until CDRs support it.

Semantic versioning of archetype ids

Archetype ids are always fully semantically versioned in ADL 2. For example, in ADL 1.4 the following is a valid archetype id: openEHR-EHR-COMPOSITION.blood_pressure.v1 . in ADL 2, this would be openEHR-EHR-COMPOSITION.blood_pressure.v1.0.1 . ADL 1.4 does store the version information in the metadata, and it is converted accurately.

References to archetypes in the reference model however, can now also contain this semantic versioning. Note that references can be still in the old form, meaning ‘the latest version matching this archetype id’. So, a reference to the archetype above can be either openEHR-EHR-COMPOSITION.blood_pressure.v1

, openEHR-EHR-COMPOSITION.blood_pressure.v1.0 or openEHR-EHR-COMPOSITION.blood_pressure.v1.0.1

Proposed Solution: data should be allowed to contain a reference to an archetype, not just the full id, which can be one of the three forms mentioned above. to check: is this already possible?

Template ids are now archetype ids

A template id is now an archetype id. Where in ADL 1.4, an OPT/template id can be, for example ‘family space history’. in ADL 2, it will then be:

usually this will also be stored in the RM. This makes the data a bit different.

Migration strategies:

• define a standardized way to convert ADL 1.4/OPT template ids to ADL 2

• Define a way to recognize from an archetype id that it refers to a template? @Joost Holslag (Deactivated) could you check if this is in the spec already (_t)?

Issue:

• template id is now in data, and queries work on template ids. How can we handle this?

Changes that do not require changes in the RM data

Cardinality, occurrences and existence have different rules in ADL 2. They will be filled with the default value from the RM if omitted. In ADL 1.4, they had a simple default value, instead of the RM being used. This means they can much more often be omitted when editing ADL. When specialising an archetype, they are inherited from the parent archetype

The benefits of these attributes appearing less often in ADL are simpler hand editing, plus less problems in specialisation - you can just change the parent archetype and the specialised archeytpe will automatically change as well.

During OPT 2 generation, these will be added again, making the cardinality, existing and occurrences mandatory in OPT 2 again.

ADL 1.4

ADL 2

OPT 2

There can be some errors during conversion of ADL 1.4 archetypes, because ADL 2 now validates this. This can mean a new version of the ADL 1.4 archetype to make it valid against the reference model again. But the data in the CDR should not change because of this, because it is again added during the generation of the OPT. making the impact of this change in CDRs low.

The algorithm to determine effective occurrences, for in the OPT or in modeling tools, is specified in https://specifications.openehr.org/releases/AM/Release-2.2.0/AOM2.html#_occurrences_inferencing_rules . The default cardinality and existence are taken directly from the RM.

Required changes in ADL 2

OPT 2 should contain a lineage from all the used archetypes all the way back to the top level archetypes, to retain specialization lineage in the OPT. Especially with namespaces.

archetype_node_id and archetype_details: what should be stored in them in case of archetype roots?