Re: Versioning of archetypes: Minor or major changes?

[Thomas Beale]

All,

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 

Versioning of archetypes: Minor or major changes?

[Bakke, Silje Ljosland]

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.

Thoughts?

Kind regards,
Silje Ljosland Bakke

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

___
openEHR-implementers mailing list
openEHR-implementers@lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-implementers_lists.openehr.org