Change specialise archetype to include (full) release_version
Description
relates to
Activity
Thomas Beale April 7, 2025 at 6:10 PM(edited)
The specialisation parent of an archetype is specified in the parent_archetype_id of the class ARCHETYPE (see AOM2 spec). The documentation of that property is:
It would have been better if that property had been called ‘parent_archetype_ref' or similar, but the documentation is correct, and the tools all do the right thing today. So, practically, you can write any of the following as the specialisation reference of an archetype:
openEHR-EHR-CLUSTER.clinical_topic.v1 → resolve the latest (minor) version within major version v1. E.g. resolves to v1.18.0 in environment A, and 1.62.0 in (probably research) environment B
openEHR-EHR-CLUSTER.clinical_topic.v1.5 → resolve the latest (patch) version within minor version v1.5, e.g. v1.5.0, v1.5.22.
openEHR-EHR-CLUSTER.clinical_topic.v15.2 → resolve to exactly this version.
IMPORTANT:
an archetype ref can resolve to different artifacts in different environments, if they don’t both have the same release of archetypes present
an archetype ref will resolve to a different artifact if you create a new version of the referenced archetype in your own repo and you recompile. Usually this is intended. ADL Workbench and Archie both do this. I would think AD does as well, but have not tested it.
However, if you create an OPT, what should be stored as the specialisation parent is what was actually matched.
So, no changes are needed to the specs, or AFAIK, the existing tools.
Joost Holslag April 6, 2025 at 8:43 AM
Some relevant discussion:
Joost Holslag March 20, 2025 at 6:31 AM
Querying is a different issue. Though I strongly suspect specifying a minor (and patch) version will be useful as well. Let’s create the issue and discuss there.
Joost Holslag March 20, 2025 at 6:29 AM
Yes that’s what I mean. The part you reference is specifically about (adl2) templates referencing other archetypes (including templates). As stated in the issue description the current rule for specialise statement is only major version.
Ian McNicoll March 18, 2025 at 4:22 PM(edited)
I support the idea i.e that archetype specialisation references should support full semantic versioning (and namespaces) but can I clarify what you mean here
`I’d also like to extend the semantics to state that specifying at the minor level means the latest available minor version. So ‘specialise org.openehr::openEHR-EHR-EVALUATION.problem.v2.4’ means the latest available minor version. Similar for patch.`
Do you mean that v.2.4.1 , 2.4.2 etc would be valid but not v2.5.0?
In which case I agree and AFIACT this is in line with current specs.
i.e hrid_ref
which would support current simple archetypeIds all the way up to a full namespcaed hrIds.
In theory it could be used in queries too but much less likely since e.g. a v2.4 query will always behave correctly for a 2.5 archetype and 2.5 datapoint will return a null if asked for in a 2.4 archetype.
Definitely in specialisations and use_archetype refs. This kind of potential tight control is going to be increasingly important
Currently adl2 archetypes are specified to identify their parent only by major version. I’d strongly recommend to change this to be able to also identify at the concept (no version), minor and patch level (and potentially including extension).
“A specialised archetype refers to its parent using the human-readable reference, including only the major version. …”
One reason is described here:
“... This means that a new version of an archetype in general may require child archetypes to be re-versioned as well.”
I’d like as a clinical modeller, to be able to prevent that. If I include the minor version in the specialise statement it no longer requires an update to the child if the parent has a minor upgrade. This is very helpful to manage complex inheritance structures. Especially since in adl2 templates are also archetypes.
It depends a lot on the archetype whether specialising at the concept, major, minor or even patch level is usefull. E.g. if you build a custom ui where the quality depends on the length of a label, which is recorded only in the archetype, it’s wise to specify at the patch level. If the string in the archetype becomes longer, without changing semantics, that would be a patch update, it does require a UI code change though. So you want to control that. For others e.g. some scale with a clearly defined concept that has auto generated forms, it may be desirable to auto propagate even breaking changes. Because the auto generated form handles the structural changes. And the risk of semantic mismatch is low.
This also needs to be changed at
I’d also like to extend the semantics to state that specifying at the minor level means the latest available minor version. So ‘specialise org.openehr::openEHR-EHR-EVALUATION.problem.v2.4’ means the latest available minor version. Similar for patch.
If we do this, it should also trigger a review of “The lack of minor and patch level version numbers should also be legal for non-namespaced identifiers, and be interpreted as meaning 0 in both cases, i.e. .v1 means .v1.0.0.” In
And probably also in the query spec.
I feel we should also clarify this for the other archetype references like for use_archetype.
This would also bring it back in line with template inclusions. Which does specify this behaviour. And in adl2 templates use exactly those mechanisms to include archetypes.
This is somewhat urgent. Because for the only adl2 production implementation at Nedap this already works this way.