Archetype versioning on CKM

Clinical (archive)
1

Hello,

With the latest Demographic archetypes updates on the CKM I think we
have to be careful with archetype versioning. The new archetypes seem
quite different of the ones that were uploaded some time ago. They are
different on structure but the version of the archetype has not been
improved (and the last archetype is just missing from the CKM).
Shouldn't a change on the archetype structure create a new version
(v2) of the archetype?
I think changes like "significant update, simplifying structure",
"Updated for alignment with altered parent", "Significant re-working"
must generate new versions.
For all the changes, I think only "Constraint loosened" ones are the
only ones that won't need to generate new versions, but everything
else should.
We should be more careful with this kind of things.

Regards

2

Hi Diego,

For those who are not aware, Diego is referring to a slew of updates to the Demographic archetypes, most in response to Review comments to the Name and Address archetypes.

In many cases there have been significant structural changes and if any of these archetypes had been published, I would absolutely agree that we should have given them new versions. However because they are still in draft and have never been published, we need to have the flexibility to make significant changes to structure and content in response to review comments.Once these archetypes are published we will strictly follow the rules about revisions and new versions, and CKM provides very powerful validation checking to help us know when an archetype is no longer backward compatible.

Unfortunately because of other commitments,We have discussed the possibility of adding another publishing status to archetypes to distinguish between archetypes that are in early draft (like alpha code and therefore volatiile) and those that are effectively Release candidates - would this be helpful.

Regards,

Ian

PS Enjoyed your Japanese presentation.

Dr Ian McNicoll
office +44 (0)1536 414 994
+44 (0)2032 392 970
fax +44 (0)1536 516317
mobile +44 (0)775 209 7859
skype ianmcnicoll
ian.mcnicoll@oceaninformatics.com

Clinical Modelling Consultant, Ocean Informatics, UK
openEHR Clinical Knowledge Editor www.openehr.org/knowledge
Honorary Senior Research Associate, CHIME, UCL
BCS Primary Health Care www.phcsg.org

3

So do you mean that only 23 (everything that is not draft) of the
current 270 archetypes on the CKM are 'safe' to be used? Everything
else could be completely changed in the next revision of the draft :frowning:

4

Hi Diego,

CKM’s role is threefold. It acts as a central library for the openEHR artefacts in all stages of their lifecycle - from draft through to published and it is also the place for collaborative review of each artefact, and for governance of the published artefacts.

Archetypes in draft status on CKM are deemed to be a sound starting point, ready for collaborative review. This certainly implies that there could still be significant changes based upon broad feedback by clinicians, informaticians, terminologists, software engineers etc throughout the review process.

Those in team review status are undergoing a review process and therefore very likely to change in the next iteration. While we endeavour to upload initial archetypes that we consider reasonably mature, we use the crowd sourcing approach of team review to ensure that the archetypes are safe and fit for purpose - this is without doubt a very valuable quality process, but the outcome cannot be predicted at the outset. This is a very important differentiator - that the models have extensive and domain expert review, as I’m sure you’ll agree.

Only published archetypes are considered stable. Yet even then they may need to be updated. Once published, strong governance will be applied to ensure that implemented archetypes are revised appropriately when backwardly compatible, and re-versioned when there are breaking changed etc to support downstream implementation. To enable this, there is considerable ongoing work on release sets to support implementers manage versioning through this process.

Hope this helps clarify the situation

Heather

5

I am OK with all that, my only problem is that new iterations should
make new versions if changes are enough (even in draft status). If not
all current projects using archetypes will be just wrong with the
'official' current archetype in CKM
The situation of two incompatible archetypes with the same archetype
identifier is one of the main things we should avoid

6

Hi Diego,

I will be interested in other opinions but I don’t think that is really feasible for first draft archetypes. The only ‘official’ archetypes in CKM are those that are published. The remainder will definitely change, some quite substantially, as a result of clinical review and local implementation experience with the drafts. If we follow the same strict versioning arrangements that you suggest, and we agree are absolutely necessary for published archetypes, we very quickly run up the version number (it would have been at v3 /v4 by now just for the 2 reviewed demographics archetypes and these are comparatively simple).

Any projects, including our own, that are using ‘draft’ archetypes must accept that these are subject to change and have to be regarded as local copies.

Ian

Dr Ian McNicoll
office +44 (0)1536 414 994
+44 (0)2032 392 970
fax +44 (0)1536 516317
mobile +44 (0)775 209 7859
skype ianmcnicoll
ian.mcnicoll@oceaninformatics.com

Clinical Modelling Consultant, Ocean Informatics, UK
openEHR Clinical Knowledge Editor www.openehr.org/knowledge
Honorary Senior Research Associate, CHIME, UCL
BCS Primary Health Care www.phcsg.org

7

Hello!
There are two flavours:
A - You freeze everything, and enjoy a safe and stable set of
archetypes. These of course do not cover a lot of functionality right now.
B - You have dynamic response to new requirements, and will never be
sure that two versions interoperate.

A is what a clinical environment needs to stand a chance of surviving
risk management and project deadlines.
B is the creative chaos that the clinical community needs to develop
opinions and agreements.

I have the feeling that these flavours do not fit into the same set of
versioning policies.

It seems that the idea of "published" versions as Heather described it
is a very appropriate way to handle this.
I guess the best we can do is to be aware of this issue and support the
work that Heather describes:

"Only published archetypes are considered stable. Yet even then they may
need to be updated. Once published, strong governance will be applied to
ensure that implemented archetypes are revised appropriately when
backwardly compatible, and re-versioned when there are breaking changed
etc to support downstream implementation. To enable this, there is
considerable ongoing work on release sets to support implementers manage
versioning through this process."

Being in the middle of a project to develop a national laboratory report
template, I briefly went through CKM and tried to map what I find there
with our Austrian requirements. I have the feeling that the
harmonisation process is definitely doable. However to me this still
needs a few rounds in the "creative chaos" level. It still might take a
substantial and focused effort to get it done.

Looking forward to meet you again, greetings from Vienna,

Stefan Sauermann

Acting Program Director
Biomedical Engineering Sciences (Master)

University of Applied Sciences Technikum Wien
Hoechstaedtplatz 5, 1200 Vienna, Austria
P: +43 1 333 40 77 - 988
M: +43 664 6192555
E: stefan.sauermann@technikum-wien.at

I: www.technikum-wien.at/mbe
I: www.healthy-interoperability.at

Diego Boscá schrieb:

8

Hello!
Just some experience on update cycle frequencies, as they have
stabilised over years of evolution in organisations that successfully
survived the challenge of large scale implementation among many
countries, companies and healthcare organisations:

- IHE has a strict yearly update cycle that works.
- The Continua Health Alliance is now closing in on a strict yearly (or
was it twice a year?) cycle.
- The Austrian insurance card system (15000 GPs, 100 or so hospitals,
about 100 vendors) updates twice a year on average, and everybody is happy.

An attempt on the mechanisms of the "fittest" update frequency might
look as follows:
Anything that is faster than twice per year: vendors and care
organisations will have no chance to implement.
Anything that is slower than once per year will not meet clinical
requirements fast enough.

Anything that is in some kind of stable synchrony to the calendar year
helps:
"Oh it is January, we can throw in new requirements and start discussing."
"Oh it is August, now let us look at the new specs/archetypes and start
implementing."

Greetings from Vienna,
Stefan Sauermann

Acting Program Director
Biomedical Engineering Sciences (Master)

University of Applied Sciences Technikum Wien
Hoechstaedtplatz 5, 1200 Vienna, Austria
P: +43 1 333 40 77 - 988
M: +43 664 6192555
E: stefan.sauermann@technikum-wien.at

I: www.technikum-wien.at/mbe
I: www.healthy-interoperability.at

Ian McNicoll schrieb:

9

Hi Stefan,

This is very helpful.

As you suggest, it is not easy to reconcile the different speeds and requirements from all parties The next major upgrade of CKM due pretty soon will include a much more complete implementation of Release Sets which I think will help address this issue. In the real world vendors and developers will almost certainly work from pre-packaged Release Sets, rather than individual archetypes, particularly as we start to see much more complex inter-dependencies between archetypes, their specialisations, slotted-in components and termsets etc. The paradigm is of a library of related software components, rather than stand-alone documents. In line with your update cycle comments, I would foresee the openEHR CKM having once or twice yearly ‘official’ Release sets. At national level, things may be quite different with a number of different project-focused Release Sets being available to developers.

The ‘first draft’ of an archetype, where one can expect considerable churn is something of a special case, particularly as it is likely to introduce ‘breaking’ change and I can understand Diego’s concern but it is difficult to envisage a better solution.

Would calling first draft archetypes .v0 help to highlight their fragility?

Ian

Dr Ian McNicoll
office +44 (0)1536 414 994
+44 (0)2032 392 970
fax +44 (0)1536 516317
mobile +44 (0)775 209 7859
skype ianmcnicoll
ian.mcnicoll@oceaninformatics.com

Clinical Modelling Consultant, Ocean Informatics, UK
openEHR Clinical Knowledge Editor www.openehr.org/knowledge
Honorary Senior Research Associate, CHIME, UCL
BCS Primary Health Care www.phcsg.org

10

2011/4/27 Ian McNicoll <Ian.McNicoll@oceaninformatics.com>

Would calling first draft archetypes .v0 help to highlight their fragility?

In fact, that is what the specifications say. Our archetype editors should use 0 when creating a new archetype.

(Knowledge Artefact Identification specifications)

.v0 rule: all archetypes have this version on initial creation, before being accepted by the
collaborative authoring environment;

revision id rule: revision number starts at 0 and is incremented whenever a backwards
compatible change is made that affects the structure – by widening constraints and/or adding
new nodes;

commit id rule: commit number starts at 0 and increments for any change at all to an archetype,
including changes to meta-data, addition of translations and so on.

An archetype will start its life as a ‘v0’ artefact, and with no namespace. In this form, it can have any
number of revisions and commits. It may be maintained for some time outside a Publishing Organisation,
or it may be offered to a PO, where it will initially become part of an ‘alpha’ development area.
where it will remain until its identifier and location in the package and Library structure is stablised.

Once stable, an alpha archetype will migrate to the main ‘dev’ area, where it will be given a namespace
prefix and have its version incremented to ‘v1’. At this point it could be published into the
‘release’ area, or alternatively, further development may occur before publishing. Whenever the revision
is changed, due to a backwards-compatible structural change, the archetype should be re-published,
enabling the community to have access to the latest form of the archetype.

During development, each change will increment the commit number. Whenever an archetype is published,
the commit number is reset to 0.

11

Hi David,

Thanks for this, though I think these are still draft specifications. I had some input into that document but with experience I am not sure the revision rules really work for .v0 archetypes though the .v0 idea itself is useful. The problem is that any structural version changes would force us to move from v0->v1, which is what I think we need to avoid for these first draft archetypes. Once an archetype is published, the rules suggested (mostly) work just fine

Ian

Dr Ian McNicoll
office +44 (0)1536 414 994
+44 (0)2032 392 970
fax +44 (0)1536 516317
mobile +44 (0)775 209 7859
skype ianmcnicoll
ian.mcnicoll@oceaninformatics.com

Clinical Modelling Consultant, Ocean Informatics, UK
openEHR Clinical Knowledge Editor www.openehr.org/knowledge
Honorary Senior Research Associate, CHIME, UCL
BCS Primary Health Care www.phcsg.org

12

I still don't see the problem

If we wait until an archetype is published to care about versions then
you will have v2 or v3 archetypes as much, which in my opinion breaks
completely versioning purpose. What is the problem with having a v27
archetype? Is it less pretty?

13

Hi Ian,

The idea of v0 was to indicate to people using them that they are unpublished and substantial structural changes are quite likely whilst allowing us to use v1 for the first published version. If anyone used v0 then they do so at their own risk. This is not much different to the current state of play but is more obvious.

Regards

Heath

Heath Frankel

Product Development Manager

Ocean Informatics

14

The problem is that ontologically v1 is not actually a version identifier,
it is more like an axis of a concept ID, v1 and v2 have different concepts
although they represent the same concept domain (i.e. two different
representations of the same concept). The name of this axis is an
unfortunate legacy that keeps causing similar discussion threads. One
reason why meaningless identifiers would be an improvement.

Heath

15

A versioning system I proposed some time ago uses 'v0' to mean draft,
also meaning 'use at own risk', just like using software in initial
development. I actually don't think that anything should have a version
of 1 or higher unless it is reviewed and published.

If v0 were used for initial never-before reviewed drafts, then the minor
numbers could be incremented to indicate changes, i.e. v0.1.0, v0.1.1,
v0.2.27 etc

- thomas

16

for v1 and above, that is obviously true, but I think that slightly
different rules could be used to allow a v0 archetype to 'tread water'
at v0, with the 2 minor version numbers incrementing to indicate each
change during this phase.

- thomas

17

it should make no difference, although since the major version number in openEHR is reserved for breaking changes, one would hope that v27 archetypes would never occur. However, v2.0.154 or v3.18.26 could be realistic.

  • t
18

I still don't see the problem

If we wait until an archetype is published to care about versions then
you will have v2 or v3 archetypes as much, which in my opinion breaks
completely versioning purpose. What is the problem with having a v27
archetype? Is it less pretty?

it should make no difference, although since the major version number in
openEHR is reserved for breaking changes, one would hope that v27 archetypes
would never occur. However, v2.0.154 or v3.18.26 could be realistic.

We should have no problem with v0.1 or v0.2.1 then...
If we have two different systems that communicate and they are
referring to different archetypes with the same name then we are
throwing away all the supposed semantic interoperability (Not much
better than using HL7 v2 messages that use different Z segments).
If we want to openEHR to get broader use we can't just tell the people
that have been already using archetypes that the archetypes on their
projects were "not intended to be used" or "you used them at your own
risk". If we want to go that way then we should put at least a warning
on the download page of those archetypes.

19

Hi everyone,

I think you are missing some of the further complexity here. There is a definite need for differentiation between draft and published archetypes for which a version number alone is not enough.
Currently we are talking only about v1 archetypes and how to manage them, and to a degree it makes sense. We certainly considered using v0.x for drafts but it doesn’t solve the downstream problems - once a v1 archetype is published, the non-breaking revisions will become v1.1, 1.2 etc. No problem
But when we make a breaking change it becomes v2 (or v3 or v4 or 125), but it needs to be clear that it is v2 draft initially and not v2 published until we have completed the neccessary collaborative reviews.

When creating release sets it needs to be clear which are draft and which are published/stable plus which version, and this is being catered for in the CKM development.

As far as the suggestion to create warnings that draft archetypes are ‘use at your own risk’… they can certainly be used at any point eg as the basis for further work or in a pilot project… whatever. But to be perfectly frank, I think it is extremely problematic if anyone considers basing any development or implementation on any artefact or specification labelled ‘draft’ and not expect there to be potentially breaking changes arising. Personally, it seems redundant to add warnings when the status of each artefact is available - I’d prefer to ensure that the status is perhaps more prominently visible throughout the CKM and it’s processes than add popups and warnings all over CKM. It is not only per archetype, but per template where there may be a mix of statuses of archetypes, embedded templates and subsets etc - the problem becomes incredibly convoluted very quickly as we are not always talking about single pre-published artefacts.

Regards

Heather

20

I know that a draft is supposed to change, even big breaking changes.
what I don't like is the idea of not being able to describe what I am
using in my system or even describe it and everyone thinking is
another completely different thing

I think the main problem here is that we are using a single axis
identifier (v1...) to describe a process that is two axis or more (v1
draft, v2 published)