# CKM progress and Archetype versioning on CKM

**Category:** [Clinical (archive)](https://discourse.openehr.org/c/clinical-archive/153)
**Created:** 2011-06-21 09:04 UTC
**Views:** 4
**Replies:** 4
**URL:** https://discourse.openehr.org/t/ckm-progress-and-archetype-versioning-on-ckm/15066

---

## Post #1 by @heather.leslie

Hi Erik, Thomas,

I think we need to address three issues separately here. The first is the archetype identification in CKM; the second is use of the draft archetypes and the third, the apparent lack of progress of archetype publication in the openEHR CKM.

Archetype identification is ultimately a technical issue and one in which I normally don’t have an opinion. Clearly it is useful from an implementation point of view to have unique IDs for each archetype and be able to determine diffs etc. However, from a non-technical point of view I believe that it is extremely helpful to clearly delineate between early/alpha/raw models and the mature ones that have been published, more than just by a ‘status’ or icon, although we need these too.

I’m increasingly of the opinion that it will be helpful to have a common understanding that the first published version of an archetype in CKM is always known as v1.0, such that if we eventually find we are using v4.x we (the non-technical) can easily infer that this is a published archetype that has undergone 3 major updates. This is very valuable to the non-techies who will be using CKM. Otherwise we run the risk of having a release set that will contain wildly disparate version numbers and will infer no idea of the state/maturity of the archetypes

To be honest, how we version the pre-published, currently known as ‘draft’ archetypes doesn’t worry me – v0.x seems sensible in light of the previous statements but if you have a better way to approach it, I’m cool with that.

Second point: use of the draft archetypes is an increasing issue. My general rule of thumb is ‘don’t’ – because they are likely to change significantly by the time they are published. Do a diff on any of the published archetypes in CKM eg Blood Pressure – this is available by clicking on the ‘Archetype History’ icon on the toolbar in CKM <img width="25" height="22" id="Picture_x0020_1" src="upload://n6dHk0jv2e8o2WWjRItjWqr8OXi.jpeg">. Check the ‘Compare’ box for the latest version of the archetype (on the left) and the first version (on the right); Select ‘Compare archetypes’ up the top. I think you will be surprised at the amount of change.

So if anyone wants to use them, do so, but understanding the implications. In addition, further work in other domains has meant that modelling practice has matured and when we are able to revise these archetypes we might approach some quite differently. Draft is draft – please don’t infer anything more from them.

And this leads in to my related third point – the apparent lack of progress on the openEHR CKM re archetype publication. To me it is the proverbial ‘elephant in the room’. I am somewhat embarrassed, but we have not been resourced to be able to continue this work directly in the volunteer openEHR space. The Ocean team did a lot of huge amount of work in the early days to get CKM up and running – Sam, Ian and Sebastian in particular – please don’t underestimate it. That burned me out, and I had to cut back; now paid work has become busier – I have had to prioritise just like everyone else.

I would love to see the openEHR CKM flourishing but the Foundation and the community needs to take it on and resource it, not just rely on Ocean resources to drive it or do the actual work. The Editorial resources are largely the bottleneck. It does take a particular personality and mindset, attention to detail and a considerable time commitment to become an Editor. Ian McNicoll and I took these roles on originally – we were learning and needed to establish some processes. This is still being fine-tuned but we are certainly in a position to mentor and train others who might be interested in taking on some Editorial responsibilities and have the time to do the job properly – it is never done in isolation, and the Editorial team approach is proving very successful. I have approached some individuals who I have thought might be suited but unfortunately most have baulked at the potential time commitment. We have had one Editor start but they have drifted off with other priorities. So we are absolutely open to more efforts and probably should have been making this more public for some time now.

And the modelling efforts have not disappeared totally. There is active modelling and reviewing of archetypes happening in the Australian [NEHTA CKM](http://dcm.nehta.org.au/ckm/). Many of the archetypes in here have been drawn from the openEHR CKM and are now undergoing review and fine-tuning by stakeholders in Australia. NEHTA’s approach to development of a clinical model library and publication of their specifications are found [here](http://www.nehta.gov.au/connecting-australia/terminology-and-information/detailed-clinical-models). As we undertook this work with NEHTA we understood that the models published in their CKM would be able to be shared back to the international community – we are seeking confirmation of this, and hope to be able to update the openEHR models with these more mature ones soon. They are making good progress.

Ultimately we need the community more active in the openEHR CKM – make it yours! Take the initiative. Volunteer as an Editor. Send us candidate archetypes. Tell your colleagues. Translate the published archetypes from inside CKM – simply select ‘Translate archetypes’ from within the ‘Archetypes’ menu.

Interestingly one member has been busy translating archetypes into Arabic (Syrian) – both the draft and published. I did email them to advise they prioritise the published archetypes to ensure they realised that if the draft archetypes change, the translation will potentially need to be re-done, yet they keep coming;-)

I’m still excited… the more I’m involved, the more I’m convinced that this work has great potential to make a real difference. Please join in.

Cheers

Heather

---

## Post #2 by @thomas.beale

Hi Erik, Thomas,

I think we need to address three issues separately here. The first is the archetype identification in CKM; the second is use of the draft archetypes and the third, the apparent lack of progress of archetype publication in the openEHR CKM.

Archetype identification is ultimately a technical issue and one in which I normally don’t have an opinion. Clearly it is useful from an implementation point of view to have unique IDs for each archetype and be able to determine diffs etc. However, from a non-technical point of view I believe that it is extremely helpful to clearly delineate between early/alpha/raw models and the mature ones that have been published, more than just by a ‘status’ or icon, although we need these too.

I’m increasingly of the opinion that it will be helpful to have a common understanding that the first published version of an archetype in CKM is always known as v1.0, such that if we eventually find we are using v4.x we (the non-technical) can easily infer that this is a published archetype that has undergone 3 major updates. This is very valuable to the non-techies who will be using CKM. Otherwise we run the risk of having a release set that will contain wildly disparate version numbers and will infer no idea of the state/maturity of the archetypes

To be honest, how we version the pre-published, currently known as ‘draft’ archetypes doesn’t worry me – v0.x seems sensible in light of the previous statements but if you have a better way to approach it, I’m cool with that.

---

## Post #3 by @system

Hi Erik, Thomas,

I think we need to address three issues separately here. The first is the archetype identification in CKM; the second is use of the draft archetypes and the third, the apparent lack of progress of archetype publication in the openEHR CKM.

Archetype identification is ultimately a technical issue and one in which I normally don’t have an opinion. Clearly it is useful from an implementation point of view to have unique IDs for each archetype and be able to determine diffs etc. However, from a non-technical point of view I believe that it is extremely helpful to clearly delineate between early/alpha/raw models and the mature ones that have been published, more than just by a ‘status’ or icon, although we need these too.

I’m increasingly of the opinion that it will be helpful to have a common understanding that the first published version of an archetype in CKM is always known as v1.0, such that if we eventually find we are using v4.x we (the non-technical) can easily infer that this is a published archetype that has undergone 3 major updates. This is very valuable to the non-techies who will be using CKM. Otherwise we run the risk of having a release set that will contain wildly disparate version numbers and will infer no idea of the state/maturity of the archetypes

To be honest, how we version the pre-published, currently known as ‘draft’ archetypes doesn’t worry me – v0.x seems sensible in light of the previous statements but if you have a better way to approach it, I’m cool with that.

---

## Post #4 by @yampeku

I like the idea of a warning on the use \(or misuse, purpose\.\.\.\) part
of the archetype\.
I also believe that anything thas has been made public needs to have a
unique identifier

---

## Post #5 by @thomas.beale

> > so I think this is compatible with:
> >
> > - a v0 rule that says start at v0.n.m, and go to v1.x.y on first 'publication'
> > - a lifecycle set of states whose names we still need to agree on, but could be something like:
> >
> > - alpha, beta, published, obsolete, superseded- the semver.org rules, which would allow versions like v0.0.1 but also v1.0.4beta
> >
> > I will look at updating the current openEHR artefact specification to reflect this.
> >
> > - thomas
>
> Thomas and all,
>
> Changing the version number of the archetype just before publication is not the right thing to do I believe.

Just to try to add some better reference points to this discussion, I think that 'publication' has to be seen as being equivalent to 'release' for software. I.e. an event by which a group of artefact authors (= 'committers' + reviewers in the open source software world) decides that the artefacts are 'ready to go'.

> This means you are doing the review process on the old id (v0, v1, v2, etc.) and this means that we are required to make incompatible changes to the old already published archetype [unless it is v0 of course], i.e. while it still has the old archetype id.
> This is something to avoid at all costs I believe.

ok, so the two approaches here are:

- perform work on artefacts at old version number, then change version number post-approval, but prior to actual release
- change version number to the target new version number, set lifecycle state to 'alpha' or similar, and then publish/release with same version number, when lifecycle state has cycled through to 'published' or 'approved' or whatever we call it.
Normally software development does follow the second path, although a lot of software development uses the 0.x version numbering scheme in the initial development phase to indicate: 'warning changing fast, don't trust this!'. I have to admit I am not completely sure what 'rules' are being followed (if any) by users of this de facto 0.x versioning identification, but it seems to me that they usually move from somethine like 0.95 to 1.0 to indicate that 'now you can trust the interface of this, and we will be maintain backward compatibility according to accepted norms'.

Now, our / my motivation for using a v0 version id was to indicate 'not approved' or 'alpha'. So if we did start with v0.x and apply consistent rules, it would mean that a 'published' v0.x artefact was by definition not 'approved'. This tells me that **the use of the word 'published' is misleading among CKM authors, and we should instead use a word like 'approved' for the intended life-cycle state**. in software, the usual think is 'alpha' => 'beta' => '' (nothing, i.e. no lifecycle name), because the idea is that once your software artefacts have been approved or passed QA, you want a 'clean' version id, one with no letter hanging off it.

So my adjusted proposal would be that:

1. we do stick to the idioms used in software, and that Sebastian mentions, i.e. that changing lifecycle states are always applied to the same version id, which is the next version id (not the old one);
1. we define a lifecycle consisting of states

- **alpha, beta, in_review, approved, obsolete, superseded**
1. we do not use the word 'published' to mean 'approved' - instead, we should just understand it informally, meaning 'made public'. Since a repository like CKM is essentially open all the time anyway, all changes are visible at all times (possibly on branch versions).
1. during any execution of the lifecycle, any change made that is committed back to the 'trunk' version of the repository has to cause an appropriate version number change, according to teh semver rules (except for v0, see next point). This means that the series of versions in a single 'cycle' could be:
- v1.0.0 alpha, v1.0.1 alpha, v1.0.2 beta, v1.1.0 beta, v1.1.0 beta, v1.2.0 in review, v1.2.0 approved
- note that this should not be the norm, because the development team should have planned for v1.2.x in the first place, but .... humans are not perfect....
1. we consider allowing v0.x versions for early, furious development in which the semver.org rules are not rigorously applied (i.e. any changes are allowed no matter how violent, with v0.x). This would correspond to Heather's 'play at own risk' warning, similar to the typical v0.5 you see on early software.
These rules (rule 4 in particular) would mean that you can use just the version number part to mechanistically infer the kind of changes made at each point, but you have to look for the lifecycle state to know about quality. The alternative is that we ruthlessly apply the whole lifecycle to each patch, minor ('revision') and major version, which is also common enough in the software world. I am unsure if archetype authors think they could / would stick to such a discipline.

I also am unsure of whether we should allow the appending of lifecycle state to version id where the latter is references, e.g. '1.0.7beta', because we just got rid of this idea a couple of years ago in openEHR, where 'v1draft' was originally allowed. Certainly we would not want 'v1.0.0approved', only 'v1.0.0', or probably more usefully, just 'v1'.

The real question here is about where the version id is mentioned, e.g. in data. Currently archetype version ids are written into the data, but not the lifecycle state. But if someone were to create data using v4.1.0beta of an archetype, should we write that into the data instead of just 'v4.1.0'? I am not sure it is useful.

> I agree that it is valuable to know that v1 is the first published *version* (and v2 the second, etc), but I question the value of knowing that v1.0.1 (or is it v.1.1.1 or v1.0.0 ??) is the first published *revision*.
> What if we made a spelling error and we have to correct a just published archetype to v1.0.2 or something? Immediately it is not only irrelevant to know that v1.0.1 was the first, but also ugly because everybody can now see that v1.0.1 was error-prone and never actually used because it was revised minutes after publication. I can already see the requests to manipulate revisioning in CKM to get this little change into v1.0.1 without changing the revision number!

which I think corresponds to my rule 4 above.

> While I am also keen to see from the version/ revision numbers whether an archetype is published or not...it does not really work and is one reason why the DRAFT ids were deprecated in the first place.
> I strongly believe that the status is pretty much orthogonal to the archetype id/revision and that we should not mix this up.

agree - do the rules above achieve this?

> Also, we already had archetypes in CKM with a big DRAFT in their archetype id - and this did not prevent anybody from using these anymore or less than the status of the archetype being "DRAFT".
> If people have a need to use them, they will use them if we make them available - no matter what their version number or status.
> I believe this holds true even if the archetype id ends with VERYEARLYDRAFTDONEVEREVERUSEANYWHEREWEAREJUSTEXPERIMENTING!

also agree.

> And by all means - let them use them! Just let us be clear on our message that incompatible changes are likely to occur before publication...this can be better visual indications of the draft state and its consequences in Archetype Editors, CKM, etc.
> It can also be a text in the ADL/XML of the archetype itself. It can be a disclaimer in the USE part of the archetype for all DRAFT archetypes.
>
> If you are keen to infer from these numbers whether it has never been published, why not use v1.0.1 up to v1.0.n for any not yet published revision. On publishing, it then could be v1.1.0 or v1.1.1 (or so). It is not quite as clear (but as I said I don't think it makes any difference), but at least it is not requiring us to make incompatible changes under the old archetype id for all versions after v0. Or the prepublication revisions are even called draft: v1.draft.1 up to v1.draft.n and v.1.0.0 or v.1.1.0 (e.g.) on first publishing.

I think this is the danger of how we use the word 'publishing'...

Are we getting closer to a solution?

- thomas

---


**Canonical:** https://discourse.openehr.org/t/ckm-progress-and-archetype-versioning-on-ckm/15066
**Original content:** https://discourse.openehr.org/t/ckm-progress-and-archetype-versioning-on-ckm/15066