Versioning of archetypes: Minor or major changes?

Thomas Beale thomas.beale at
Fri Nov 17 08:23:43 EST 2017


for reference, the rules on what level of change is required to the 
version id is here, in the Identification specification 
I suggest that this is taken as the starting point for any discussion 
about changes to versioning rules. To my knowledge, these rules are 
already implemented in CKM.

Implementing organisations need to think very carefully about whether 
they want to be able to support all previous versions of their software 
at all times simultaneously, because that is likely to be semantically 
problematic, not just for archetypes, but for any standards (e.g. FHIR 
profiles etc), terminology static value sets (i.e. not intensional value 
sets) and any other semantics buried in business rules, application 
logic etc.

 From Silje's list, I have the following comments:

 1. adding non-mandatory elements: if a receiver system using an earlier
    version of the same archetype (why?) rejects data from the new
    archetype, this is an error in the receiver integration logic, since
    there can be always more elements, archetyped or not, except in the
    edge case where container attribute cardinality upper limit is
    constrained to a fixed number.
 2. correct; but modelling internal value sets, or any value sets as X,
    Y, other is bad practice, as documented for 15 years by the likes of
    Cimino, Rector, IHTSDO etc. Noone should be doing that. The question
    is how to do it properly in openEHR archetypes. Some posisbilities:
      * use the DV_CODED_TEXT and DV_TEXT; this has the effect that
        'other' items can be textually represented when there is no
        code, and avoids the fake 'other' code polluting code sets -
        this can be done today.
      * introduce an 'open' / 'closed' marker on DV_CODED_TEXT (i.e. on
        C_TERMINOLOGY_CODE). There is a discussion about this
        'exclusion' logic with respect to higher level structures in the
        AOM2 spec
        which may be useful. We would still have to do something new to
        implement this ability properly for term sets.
 3. agree; but runtime name constraints should never be added in
    archetypes, only templates. The rule is that they default to the
    rubric of the at-code of the node if not constrained, which should
    never be 'unexpected'.
 4. agree; but the problem here really is: if you now thing that data
    element X is optional clinically speaking, presumably you think that
    to be the case across the whole health system, or jurisdiction or
    whatever - so my question is: what is the sense in keeping old
    software that is wrongly mandating a data item that will no longer
    be clinically collected (items like religion, ethnicity, sexual
    preference, even social gender all seem to be common examples of
    this, but of course cliincal examples exist too, as science and
    business process evolve)

- thomas

On 16/11/2017 10:07, Bakke, Silje Ljosland wrote:
> 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.
> Thoughts?
> 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-implementers mailing list
> openEHR-implementers at

Thomas Beale
Principal, Ars Semantica <>
Consultant, ABD Team, Intermountain Healthcare 
Management Board, Specifications Program Lead, openEHR Foundation 
Chartered IT Professional Fellow, BCS, British Computer Society 
Health IT blog <> | Culture blog 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the openEHR-clinical mailing list