# Archetype versioning on CKM **Category:** [Clinical (archive)](https://discourse.openehr.org/c/clinical-archive/153) **Created:** 2011-04-27 01:38 UTC **Views:** 2 **Replies:** 31 **URL:** https://discourse.openehr.org/t/archetype-versioning-on-ckm/15010 --- ## Post #1 by @yampeku 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 --- ## Post #2 by @ian.mcnicoll 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](mailto:ian.mcnicoll@oceaninformatics.com) Clinical Modelling Consultant, Ocean Informatics, UK openEHR Clinical Knowledge Editor [www.openehr.org/knowledge](http://www.openehr.org/knowledge) Honorary Senior Research Associate, CHIME, UCL BCS Primary Health Care [www.phcsg.org](http://www.phcsg.org) --- ## Post #3 by @yampeku 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 :\( --- ## Post #4 by @heather.leslie 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 --- ## Post #5 by @yampeku 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 --- ## Post #6 by @ian.mcnicoll 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](mailto:ian.mcnicoll@oceaninformatics.com) Clinical Modelling Consultant, Ocean Informatics, UK openEHR Clinical Knowledge Editor [www.openehr.org/knowledge](http://www.openehr.org/knowledge) Honorary Senior Research Associate, CHIME, UCL BCS Primary Health Care [www.phcsg.org](http://www.phcsg.org) --- ## Post #7 by @Stefan_Sauermann 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: --- ## Post #8 by @Stefan_Sauermann 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: --- ## Post #9 by @ian.mcnicoll 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](mailto:ian.mcnicoll@oceaninformatics.com) Clinical Modelling Consultant, Ocean Informatics, UK openEHR Clinical Knowledge Editor [www.openehr.org/knowledge](http://www.openehr.org/knowledge) Honorary Senior Research Associate, CHIME, UCL BCS Primary Health Care [www.phcsg.org](http://www.phcsg.org) --- ## Post #10 by @system 2011/4/27 Ian McNicoll <[Ian.McNicoll@oceaninformatics.com](mailto: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. --- ## Post #11 by @ian.mcnicoll 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](mailto:ian.mcnicoll@oceaninformatics.com) Clinical Modelling Consultant, Ocean Informatics, UK openEHR Clinical Knowledge Editor [www.openehr.org/knowledge](http://www.openehr.org/knowledge) Honorary Senior Research Associate, CHIME, UCL BCS Primary Health Care [www.phcsg.org](http://www.phcsg.org) --- ## Post #12 by @yampeku 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? --- ## Post #13 by @Heath_Frankel3 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 --- ## Post #14 by @Heath_Frankel3 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 --- ## Post #15 by @thomas.beale 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 --- ## Post #16 by @thomas.beale 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 --- ## Post #17 by @thomas.beale 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 --- ## Post #18 by @yampeku > > 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\. --- ## Post #19 by @heather.leslie 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 --- ## Post #20 by @yampeku 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\) --- ## Post #21 by @heather.leslie Indeed - it is a major issue. The more we explore knowledge governance the more complicated it becomes, especially when multiple artefacts become involved, not just archetypes:) It gets further convoluted when we consider the addition of federated national repositories and all the governance requirements when using artefacts from multiple sources (not to mention local archetypes in local systems). Hence the recent additional discussion of namespaces to start to differentiate at that level. CKM development is evolving as a means to embrace all of this complexity and hide/reveal as much as each type of user needs - most clinicians reviewing don't want to see any of this or most of the RM; the implementers need clear guidance as to the state of each artefact they are using - it is a bit of a juggling act, not perfect by any means yet but gradually being refined. All feedback gratefully received. Cheers Heather --- ## Post #22 by @Stef_Verlinden1 Isn't it better that everybody who chooses to use v\.0 drafts creates their own internal version numbering so they can keep track of it\. As far as i understand there can be more than 1 v\.0 of an AT \(at least there where for the demographich AT's and some of them might not be present in openEHR database\)\. As said before v\.0 AT's aren't supposed to be used widely/ in more than one system for operational purposes\. The idea of v\.0 AT's is to explore their feasibility, to share and discuss some ideas and to be able to test some variants before we go into the formal process\. As soon as the community agrees to proceed, a v\.1 draft AT is generated based on the 'crude' common sense generated from the v\.0 variants\. From there we start the official process of reviewing, versioning, etc\. It could well be in that case that we go from v\.1 draft to v\.2 published because during the 'formal' review process, breaking changes were introduced\. As a consequence all published v\.0 AT's are for educational purposes only and to be used at your own risk your own versioning if you choose so\. If you want that v\.0 to be formal you should initiate a request to give that AT a v\.1 draft status and if everybody agrees that will become the starting point for versioning\. Just my 2 cents\. Stef --- ## Post #23 by @system 2011/4/28 Heather Leslie <[heather.leslie@oceaninformatics.com](mailto:heather.leslie@oceaninformatics.com)> > 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. I see your point and I completely agree with it. Using v0 to denote draft archetypes before going to v1 only solves the first iteration. When moving to v2, v3, etc. we certainly will have drafts and published archetypes for those new versions and we have to manage all them. Even when creating v1.x or v1.x.y archetypes we can need drafts prior to the formal voting/validation/publication of them. Archetypes, as a technical resource (not as a concept definition) need to have unique identifier for each minimal change. We have the archetype revision history but we should also show those changes by changing the identifiers. So, we fall back to the need of rethinking archetype identifiers to include these new requirements or change them into identifiers with no semantics. Or a third option, maybe the best one, to clearly separate between a "concept identifier" that would be the current identifier and a "resource identifier" to track every change and to, at least, warn systems that use archetypes that something has changed. David --- ## Post #24 by @thomas.beale There are two ways to look at this: - A - 'draft' is only possible at the notional v0 or first version stage; after initial publication, it can't be used, since the archetype is now 'in the open' - B - it is possible to go back to 'draft' status when the major version number is incremented on the basis that a new major version is a new archetype, and authors need to be able to go back into 'initial development' mode I can see arguments for both. What we need to decide on as a community is what rule we want here, and to stick to it. If we can decide that, we can document it and post it in a new draft of the [identification specification](http://www.openehr.org/svn/specification/TRUNK/publishing/architecture/am/knowledge_id_system.pdf). Diego's problem of knowing what archetype one is actually using is real and needs to be solved. CKM does track revision numbers, but they are not part of the version id, and you have to go into the revision history view to see them. However the above-mentioned identification draft spec indicates a system of referencing to do this such that an archetype whose id is currently shown as openEHR-EHR-EVALUATION.diagnosis.v1 would be referenced from data and / or software (i.e. in any operational context) as openEHR-EHR-EVALUATION.diagnosis.v1.29.0, or in the future with a namespace as well, i.e. org.openehr.ehr::openEHR-EHR-EVALUATION.diagnosis.v1.29.0 Note that in this system of identification, if the final part of the revision number is a '0', i.e. the '0' above in '1.29.0', it means that the archetype is published; if it is anything else it is draft or some other pre-release state (this corresponds with view B above). Changes in the lifecycle state of the archetype are assumed to always cause an increment in final number of the extended version id. A fuller idea of referencing archetypes from from data is described in this spec, exemplified by the following: se.skl.epj::openEHR-EHR-EVALUATION.genetic_diagnosis.v1.12, -- some Swedish archetype org.openehr.ehr::openEHR-EHR-EVALUATION.diagnosis.v1.29, -- its parent, the CKM diagnosis archetype org.openehr.ehr::openEHR-EHR-EVALUATION.problem.v2.4 -- the ultimate parent, the CKM problem archetype here the whole specialisation lineage has been included. The reason for doing this are a) if the archetype lineage information is not shared between sender and receiver (maybe the receiver can't see the Swedish CKM) and b) to enable the receiver to know what archetypes could be used for querying the data, assuming it was not going to use the most specialised one (e.g. the data might have been sent from Sweden to Denmark, and the Danish system doesn't use the Swedish genetic diagnosis archetype, but does use the other two). Note that the version ids above only have 2 parts, because the final part is always '0' for published archetypes (but it could be included for better consistency). Assuming this kind of system was used, then supporting it requires some changes in CKM to a) make the full version + revision id visible. Note that the 'identifiers' above are just strings. Even in a future where Oids were used for identifying artefacts, you still need to generate the above strings, or the equivalent, from meta-data - essentially as composite keys (in the relational sense) so that comparisons can be made between artefacts. (Or they might also be obtainable from some Oid-keyed meta-data repository). In other words, embedding such strings in data isn't making a statement about how archetypes are identified, it is just one useful means of **referencing** archetypes. Finally, to be sure that the archetype you have in your environment is indeed what you think it is, digital signing, or at least hashing, is needed such that published archetypes are posted with their signatures alongside for verification by accessing systems. MD5-based hashing is already in use in some openEHR-based products, but it has not been properly described (an initial idea is in section 8 of the identification spec doc). It seems that there is enough use of archetypes now to finalise many of these issues, and describe them in a new issue of the identification specification. We then need to work out an implementation plan, mostly to do with changes to CKM to support the decisions. There are two ways to go about this: - interested parties review the identification spec, and provide feedback - we work out the details on the technical list + wiki via discussion and then update the spec. Key things that need decisions: - do we go with starting at v0 or v1 (I still like v0 because it implies 'you will most likely get burnt by using this archetype in a real system, but have fun and tell us your experience')? - can we agree on the archetype life-cycle states and the idea that a change in state always causes an increment in minor revision number? - how should archetypes be referenced from data? - what system of hashing and signing should be used? - thomas --- ## Post #25 by @heather.leslie > > > 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. > > There are two ways to look at this: > > - A - 'draft' is only possible at the notional v0 or first version stage; after initial publication, it can't be used, since the archetype is now 'in the open' > > - B - it is possible to go back to 'draft' status when the major version number is incremented on the basis that a new major version is a new archetype, and authors need to be able to go back into 'initial development' mode 'A' is nice in theory but 'B' is describing what will need to happen in practice - any changes, large or small to a published archetype will need to go through a review process and ratification that the archetype is safe and 'fit for purpose'. Remember too, that a draft archetype might seem sensible on first upload to CKM, but based upon expert review it is possible for the archetype to need to: - have the concept name changed - have the archetype id changed - increase or decrease in scope - increase or decrease in granularity - be split into two or more smaller archetypes - be merged with one or more additional archetypes It would be ideal to track the archetype through concept name, id and scope changes, but if there are splits or mergers as is required to make safe and fit for purpose models, then provenance tracking becomes impossible. There will be some situations where we can't resolve Diego's issues. > I can see arguments for both. What we need to decide on as a community is what rule we want here, and to stick to it. If we can decide that, we can document it and post it in a new draft of the [identification specification](http://www.openehr.org/svn/specification/TRUNK/publishing/architecture/am/knowledge_id_system.pdf). > > Diego's problem of knowing what archetype one is actually using is real and needs to be solved. CKM does track revision numbers, but they are not part of the version id, and you have to go into the revision history view to see them. However the above-mentioned identification draft spec indicates a system of referencing to do this such that an archetype whose id is currently shown as openEHR-EHR-EVALUATION.diagnosis.v1 would be referenced from data and / or software (i.e. in any operational context) as openEHR-EHR-EVALUATION.diagnosis.v1.29.0, or in the future with a namespace as well, i.e. org.openehr.ehr::openEHR-EHR-EVALUATION.diagnosis.v1.29.0 I believe that CKM has asset IDs as well - which can follow an asset/archetype through concept name/archetype id changes etc. > Note that in this system of identification, if the final part of the revision number is a '0', i.e. the '0' above in '1.29.0', it means that the archetype is published; if it is anything else it is draft or some other pre-release state (this corresponds with view B above). Changes in the lifecycle state of the archetype are assumed to always cause an increment in final number of the extended version id. > > A fuller idea of referencing archetypes from from data is described in this spec, exemplified by the following: > > se.skl.epj::openEHR-EHR-EVALUATION.genetic_diagnosis.v1.12, -- some Swedish archetype > org.openehr.ehr::openEHR-EHR-EVALUATION.diagnosis.v1.29, -- its parent, the CKM diagnosis archetype > org.openehr.ehr::openEHR-EHR-EVALUATION.problem.v2.4 -- the ultimate parent, the CKM problem archetype > > here the whole specialisation lineage has been included. The reason for doing this are a) if the archetype lineage information is not shared between sender and receiver (maybe the receiver can't see the Swedish CKM) and b) to enable the receiver to know what archetypes could be used for querying the data, assuming it was not going to use the most specialised one (e.g. the data might have been sent from Sweden to Denmark, and the Danish system doesn't use the Swedish genetic diagnosis archetype, but does use the other two). > > Note that the version ids above only have 2 parts, because the final part is always '0' for published archetypes (but it could be included for better consistency). > > Assuming this kind of system was used, then supporting it requires some changes in CKM to a) make the full version + revision id visible. > > Note that the 'identifiers' above are just strings. Even in a future where Oids were used for identifying artefacts, you still need to generate the above strings, or the equivalent, from meta-data - essentially as composite keys (in the relational sense) so that comparisons can be made between artefacts. (Or they might also be obtainable from some Oid-keyed meta-data repository). In other words, embedding such strings in data isn't making a statement about how archetypes are identified, it is just one useful means of **referencing** archetypes. > > Finally, to be sure that the archetype you have in your environment is indeed what you think it is, digital signing, or at least hashing, is needed such that published archetypes are posted with their signatures alongside for verification by accessing systems. MD5-based hashing is already in use in some openEHR-based products, but it has not been properly described (an initial idea is in section 8 of the identification spec doc). > > It seems that there is enough use of archetypes now to finalise many of these issues, and describe them in a new issue of the identification specification. We then need to work out an implementation plan, mostly to do with changes to CKM to support the decisions. > > There are two ways to go about this: > > - interested parties review the identification spec, and provide feedback > - we work out the details on the technical list + wiki via discussion and then update the spec. > Key things that need decisions: > > - do we go with starting at v0 or v1 (I still like v0 because it implies 'you will most likely get burnt by using this archetype in a real system, but have fun and tell us your experience')? Some current plans for CKM include recognising the need for "alpha" archetypes. However the feeling is that these could and should be managed in a connected but separate proposed archetype 'sandpit' - something planned for CKM as a space where we can start archetype collaboration from a very raw concept stage and evolve it in a (potentially) open way. This will enable the current CKM to continue to be the place for 'serious' archetype candidates, open collaboration and appropriate governance (at a level that is deemed appropriate for the status of the archetype - looser for drafts, extremely tight for published). *If* and when the "alpha" archetypes are mature enough to be reasonable candidates for collaborative review then they can be promoted to the CKM as we know it now - effectively the current CKM drafts. We don't need to do this in the current CKM process > - can we agree on the archetype life-cycle states and the idea that a change in state always causes an increment in minor revision number? Current states include draft; team review; published; reassess (ie a published archetype is currently undergoing further team review, which could simply result in a non-breaking revision or alternatively in a breaking change and new version); and rejected/deprecated. Team review is simply indicating a review process has commenced, not that there has been any specific change in the artefact itself, although changes are likely to follow on as part of the review process --- ## Post #26 by @thomas.beale the separate sandpit seems like a reasonable idea, but archetypes there will still need to be identified, and there will always be someone who will use them - at least in purely research systems - so I think the need for 'v0' doesn't go away... - thomas --- ## Post #27 by @heather.leslie > > > > - do we go with starting at v0 or v1 (I still like v0 because it implies 'you will most likely get burnt by using this archetype in a real system, but have fun and tell us your experience')? > > > > Some current plans for CKM include recognising the need for "alpha" archetypes. However the feeling is that these could and should be managed in a connected but separate proposed archetype 'sandpit' - something planned for CKM as a space where we can start archetype collaboration from a very raw concept stage and evolve it in a (potentially) open way. This will enable the current CKM to continue to be the place for 'serious' archetype candidates, open collaboration and appropriate governance (at a level that is deemed appropriate for the status of the archetype - looser for drafts, extremely tight for published). > > *If* and when the "alpha" archetypes are mature enough to be reasonable candidates for collaborative review then they can be promoted to the CKM as we know it now - effectively the current CKM drafts. > > We don't need to do this in the current CKM process > > the separate sandpit seems like a reasonable idea, but archetypes there will still need to be identified, and there will always be someone who will use them - at least in purely research systems - so I think the need for 'v0' doesn't go away... v0 is absolutely a good place to start in the 'sandpit' plus the CKM digital asset ID plus...??? --- ## Post #28 by @system Hi\! I came to think of this openEHR versioning discussion thread when I read about the Semantic Versioning initiative at http://semver.org/ I think the reasoning there is very appropriate also for openEHR artifacts\. The problem for openEHR might be that there are so many seemingly usable archetypes in the openEHR\-hosted CKM that are neither modified for a long time nor officially tagged as "published"\. It is understandable if it's tempting to start using them in real systems already now\. After all the alternative is to reinvent the wheel locally and is that really better? Perhaps there should be a time limit on how long artifacts in the CKM can stay at a version below 1\.0\.0? Perhaps things would become easier if we break the link between an artifact having "published" status \(as in being CRB approved\) and the fact that an artifact has a version over 1\.0\.0\. That way systems can start using archetypes past 1\.0\.0 knowing that non\-compatible changes will have new major version numbers \(irrespective of if they are published or not\)\. Keeping approval "badges" like "ARB published", "NHS approved" or "WHO 2011 Certified" separate from technical version numbers might be a good idea anyway\.\.\. \(Example: the first "ARB published" version of Archetype X might be 2\.4\.2 and the next time it's awarded an "ARB published" badge again might be when the ARB has time to get around to looking at version 2\.8\.4 or 7\.8\.9\)\. Likely, agencies will want to approve sets of artifacts on a regular basis like tagging a number of mutually compatible archetypes and templates as "NHS 2012\-Q1 approved"\. The reasoning under \#3 at http://semver.org/ \(regarding 1\.0\.0beta1 < 1\.0\.0beta2 < 1\.0\.0\.\) might solve the "draft problem" discussed in this openEHR thread previously\. \(Provided that beta versions etc\. don't get used/abused in live EHR systems\.\) The Semantic Versioning specification formalism is also machine processable in a nice way\. Best regards, Erik Sundvall erik\.sundvall@liu\.se http://www.imt.liu.se/~erisu/ Tel: \+46\-13\-286733 --- ## Post #29 by @Peter_Linhardt Hi\. I would like to add my flag behind Erik initiative\. I would be great help for all hesitating and for those whu try to transfer the OpenEHR solution into local conditions, if the list of CKM published and approved archetyps will be labeled by country representations in form : apporved by "national authority" Since "dat" but even it would be better if there is a statement : Implemented by "vendor" in IS for "care provider organisation" since "date"\. I gues, except Slovakia in much more countries the OpenEHR pioneers might need this support in process of new platform penetration in oblsoletly thinking structures\. Peter Linhardt \* Competence Center eHealth manager \* Division Public Ness Slovakia a\.s\. Galvaniho Business Centre, Galvaniho 15/C, 821 04 Bratislava, Slovakia Tel\.: \+421 2 6826 1000 Mobile: \+ 421 911 899 827 peter\.linhardt@ness\.com |www\.ness\.com Please consider the environment before printing this e\-mail --- ## Post #30 by @Stefan_Sauermann Hello\! Here are some experience reports from the semantic web veterans, who have been through many fierce semantic artefact "versioning hells" and back\. Semver\.org seems to capture the idea in a useful way\. Greetings from Vienna, Stefan Sauermann University of Applied Sciences Technikum Wien Leo Sauermann wrote: The idea of semver is good as it writes up best practice\. Continually publishing versions on a server and then "approving" them is typical in open source\. For major releases that need a longer feedback and BETA phase I would point to open source software who release BETA Versions within normal release cycles\. A good example would be KDE 4\.0\.0 which was quite experimental and did not really work\. But developers could start updating their software to be 4\.y\.z compatible\. Or html 5 from w3c\. Drafts of the standard circulated before, marked as "editors draft" and could be used\. Main learnings from this: \- use a coherent scheme in the core and slavishly stick to it\. If you increase version numbers for every change, you will get v2\.0\.478beta\. Knowing that there have been 478 beta versions is fine but here the trouble starts: BETA means anything could change\. So the rule of incompatible changes causing an increase in the major version could be dropped for versions marked beta\. \- if you publish or release or communicate a BETA version which is intended as editors draft or a way to "get started" you MUST clearly communicate that the standard is experimental/unstable and there can be compability breaking changes within draft releases\. There was trouble with KDE 4\.0 because it was very instable and actually not intended for productive use\. But thousands of desktop users read the news "4\.0 is out" and started installing it without reading the fineprint\. That caused bad feedback\. KDE 4\.2 was the "real" release\. The lesson learned is that releasing 4\.0 was the right thing to let developers start their work, but the labeling as "beta" or "unstable" and the right marketing message missed\. The "approval" by WHO or other standardization bodies is similar to the way linux distribution works: in linux the developers release v4\.2\.1 and the packagers \(red hat, debian, ubuntu\) decide whether v4\.2\.1 is in their "ubuntu edgy 2009" standard release or not\. The packagers thus play the role of standard approval\. Leo Sauermann, Dr\. CEO and Founder mail: leo\.sauermann@gnowsis\.com mobile: \+43 6991 gnowsis http://www.gnowsis.com helping people remember, so join our newsletter http://www.gnowsis.com/about/content/newsletter --- ## Post #31 by @thomas.beale Erik, thanks for the pointer. I like this set of rules. It is not too different from the current [draft identification spec](http://www.openehr.org/svn/specification/TRUNK/publishing/architecture/am/knowledge_id_system.pdf), and it would be easy to upgrade it to reflect the SemVer rules more faithfully. In the openEHR spec, major.minor.patch is referred to as version.revision.build. I seem to remember a discussion where we thought about renaming these. Do people think we should just stop mentioning version/revision/build with respect to archetypes? Or is it helpful to think of an openEHR 'revision' as being the same as a 'minor' version (personally I think yes)? The only thing I don't like that much is going back to putting 'draft' etc on the end of the version string, but I guess it is so common, that we should just go with the flow. If we can get a bit of consensus here, I can update this draft proposal to reflect it pretty quickly. - t [details="(attachments)"] ![OceanInformaticsl.JPG|183x82](upload://2lcnRHcC3QqDv6AeaDZuo8M9Qlv.jpeg) [/details] --- ## Post #32 by @thomas.beale I meant to add that the SemVer concept of 'public API' for an archetype will obviously be something a bit different from a standard software API, i.e. set of class/function definitions. So the 'public API' itself will be part of what needs to be described. We can potentially interpret the version rules below for openEHR (for versions above 1.0.0; prior to that, you do what you want): 7. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. openEHR: - increment patch version ('build') incremented if change limited errors are corrected so that the original intention is preserved. Q: how do we document what the 'original intention' was? 8. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. openEHR: - increment minor version (openEHR 'revision') if change limited to compatible additions; in openEHR-land, the idea is that data of a previous revision remains conformant to new form of archetype. The general rule with constraints is that this can be done by: - widening existing constraints - adding new constraints not incompatible with existing constraints, i.e. at a clinical/domain semantic level 9. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. openEHR: - increment major version (openEHR 'version') if change causes archetype to no longer be compatible with existing data. In openEHR, a new 'version' is a treated like a new archetype, hence the use of the top-level version number in the semantic identifier. some more work is obviously needed to get all this where it needs to be, but I think the SemVer rules look like a good basis to hang openEHR principles on. - thomas --- **Canonical:** https://discourse.openehr.org/t/archetype-versioning-on-ckm/15010 **Original content:** https://discourse.openehr.org/t/archetype-versioning-on-ckm/15010