AW: Versioning of archetypes: Minor or major changes?

Sebastian Garde sebastian.garde at
Thu Nov 16 06:28:49 EST 2017

Hi Silje,

From my point of view, we need to differentiate between technical necessary version increments and clinically necessary ones.
In CKM, we have tried to implement the technically necessary version increment, which can always be increased by the clinician modeller.
In that sense the technically suggested version increment is a minimum increment, but you can always opt to go higher.

Now, we seem to have a different idea about what technically necessary means and indeed it is very complex (and I don’t think one is necessary better, just different, as it depends on what you want to use the major version for). A while ago, Thomas, Ian and I tried to fill in a spread sheet with some cases to decide what is a major, minor, patch change…let’s say the differences, at least initially, were high.

My main criteria for the technical level would be whether it is technically guaranteed that data recorded using the old archetype can be read and principally understood when using the new archetype.
But not vice versa…!
If you need to exchange data from new to old, there will be problems like you describe below.
If you require this kind of compatibility to be a major change, you’ll end up having many, many changes creating a new major version, essentially ignoring that – this is, more or less  - what the minor version can be used for.
The one is intra-system, the other is inter-systems, in any direction, if you like.

On the clinical level, you could – in an extreme case - even go so far that a (alphabetically) miniscule change to the text or description of an at code can be major version change if it (sufficiently) changes the semantics of the element. There will be edge cases for this I suspect.

If any of the changes – in a concrete case - is critical from a clinical point of view, I would then argue this needs to be a major change by the modeller, even if technically it is just a patch or minor version change.

Using you examples below, if the new element (1.) is absolutely critical, it may warrant a new major version, even if it is not mandatory (for reasons discussed a few days ago on the list)
If a value is added to the internal value set (2.), I absolutely agree that, this may change the meaning of the other values, especially in the “other” case.
I have argued the same way like you before, but I now think that it is a clinical (or semantical/logical) decision, not a pure technical one, to make this a major version change.

Adding a runtime name constraint (3.) is a major change from a technical point already, in my view.
(More interesting in my view is if deleting a runtime name constraint is a major change as well, I think so (and CKM agrees, surprisingly 😉 ), essentially for what you argue below.

Widening cardinality/occurrence constraints (4.) would give you the problem you describe.
I still think this is the prototype of what constitutes a minor version change.

We could of course consider requiring a technical change to be backward compatible AND forward compatible, so that this works 100% under all circumstances BETWEEN systems, in all directions. Then the order of old and new doesn’t make a difference for the comparison. Most of the minor versions wouldn’t exist, but be major version changes instead.


Von: openEHR-clinical [mailto:openehr-clinical-bounces at] Im Auftrag von Bakke, Silje Ljosland
Gesendet: Donnerstag, 16. November 2017 11:07
An: openehr-implementers at; For openEHR clinical discussions (openehr-clinical at <openehr-clinical at>
Betreff: Versioning of archetypes: Minor or major changes?

Another crosspost between the Clinical and the Implementers lists.

In versioning archetypes, we’ve defaulted to SemVer’s three version levels MAJOR.MINOR.PATCH. When discussing with DIPS what should be considered MINOR or MAJOR changes, we’ve come to the preliminary conclusion that many more changes than we previously thought may require a MAJOR version change. This is exemplified below mostly with exchange of information between systems, but may also be relevant within a system when adding new functionality with a newer version of the same archetype.

These are as follows:

  1.  Adding non-mandatory elements (ie elements with occurrences 0..*): Depending on the validation mechanism at the receiving end, a system with an earlier version of the archetype that receives a message or payload with an element it doesn’t recognise may reject the message or just ignore the new element.
  2.  Adding values to an internal value set:
     *   If adding the value Z to a value set that was originally “X, Y, Other”, you’re modifying the value of “Other”, which previously would include Z. Semantically this is a major change, even if technically it’s a minor one.
     *   If sending data to a system that has an earlier version of the archetype, the new value will not be understood.
  3.  Adding a run time name constraint: A run time name constraint has its own AT code, which could confuse a receiving system if it receives a code it doesn’t know about.
  4.  All changes in cardinality or occurrences that opens up the archetype’s constraints, such as making a previously mandatory element optional, or making a previously single occurrence element multiple occurrence. Not receiving an element you thought was mandatory or receiving more instances of an element than you thought possible, can make a receiving system’s validation mechanism protest.


Kind regards,
Silje Ljosland Bakke

Information Architect, RN
Coordinator, National Editorial Board for Archetypes
Nasjonal IKT HF, Norway
Tel. +47 40203298
Web:<> / Twitter: @arketyper_no<>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the openEHR-clinical mailing list