AW: Versioning of archetypes: Minor or major changes?

Ian McNicoll ian.mcnicoll at
Thu Nov 16 07:00:44 EST 2017

Hi silje

I think we have always been clear that the definitions of major minor and
patch only ever applied to the techicalities of path handling and data
compatibility. I have always made it clear that minor changes may carry A
whole range of potential clinical risk, your examples being quite correct.

The problem there is that it is simply not possible for archetype or even
template developers to know whether these changes represent an s tual risk.

My approach would always be to assume that any minor change could induce
risk and have it cliniccsly reviews before deployment

I ian

On 16 Nov 2017 at 11:31, <Sebastian Garde
<sebastian.garde at>> wrote:

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

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

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:
      1. 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.
      2. 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

_______________________________________________ openEHR-clinical mailing
list openEHR-clinical at
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the openEHR-clinical mailing list