# Archetype Naming proposals - do we need V0? **Category:** [Clinical (archive)](https://discourse.openehr.org/c/clinical-archive/153) **Created:** 2014-10-01 10:23 UTC **Views:** 3 **Replies:** 81 **URL:** https://discourse.openehr.org/t/archetype-naming-proposals-do-we-need-v0/15726 --- ## Post #1 by @ian.mcnicoll Hi all, Apologies for cross-posting in both clinical and technical but this does neatly cross that divide. We are getting close in CKM to implementing the ADL1.5 archetype naming /versioning rules proposed at [http://www.openehr.org/wiki/display/ADL/Knowledge+Artefact+Identification](http://www.openehr.org/wiki/display/ADL/Knowledge+Artefact+Identification) mostly by adding the metadata to the ADL other_details section, which means we can carry the information in ADL 1.4 archetypes without disturbing current systems. These latest proposals are now very much in line with the de-facto standard SemVer 2.0 see [http://semver.org](http://semver.org/) which allows major revision minor revision patch build but one of the questions which remains controversial is whether to support a major revision of V0 (as allowed in SemVer). In Semver, V0 is allowed for very immature ‘first draft’ semantic artefacts/APIs prior to initial release but SemVer allows for any revision to appended with a pre-release modifier e.g. v2.0.0-alpha or v1.0.0-unstable This is recognised as meaning that the artefact is unstable and the version numbering cannot be relied on e.g to assert backward compatibility. In that sense v0.0.0 and v1.0.0-unstable are identical in terms of their ‘stability’ and lack of commitment to the versioning rules. So the question for us in the openEHR world is whether tooling should support v0.0.0, or simply use v1.0.0-unstable V0 Advantages 1. The archetype is clearly marked as immature 2. Full compliance with SemVer 3. Supported in current test build of CKM V0 Disadvantages 1. Tooling e.g Archetype Editor (actually ADL Parser) needs to change to support V0 2. Add another layer of complexity to the archetype naming/versioning rules 3. Question arises of whether / if to convert current draft V1 CKM archetypes to V0 with overhead of explanation to current users. 4. Adds complexity where V0 archetypes are being used within templates, when the archetype is published and needs to be updated to V1 within these templates. V1- Advantages 1. Compliant with SemVer 2. Does not need any changes to Archetype Editor. 3. Easier transition between draft and publication states when used within templates i.e does not need V0->v1 change V1- Disadvantages 1. Does not so clearly differentiate ‘first draft’ archetype from others Before a final decision is made, we are interested in feedback from the community on whether V0 should be implemented in CKM and other openEHR tools, although in practice V1- will do an identical job in terms of version number governance. Regards, Ian McNicoll Heather Leslie Sebastian Garde Thomas Beale --- ## Post #2 by @Seref Hi Ian, Personally I think V0 has significant costs in exchange for not so significant benefits. Semver compatibility would be nice, but nice is not worth the implementation cost for parser etc here. I don't know if V0 support would break things deep down in actual openEHR implementations but even that may be a possibility if there is a reg-ex sitting in some code that expects v1 as the starting point. The features in adl 1.5 would probably help provide a workaround to express the semantics that would otherwise be expressed with V0 Best regards Seref --- ## Post #3 by @ian.mcnicoll Thanks Seref, That is my feeling exactly. In practical terms, in an openEHR context, .V0 and .v1-unstable are identical. We do know that V0 breaks the old AE Eiffel parser. This is probably easily fixable but is an example of work that would need to be done. We are replicating the ADL 1.5 features as you suggest but in a way that does not change core archetype identification in ADL1.4, other than .V0. Perhaps the compromise is to defer the decision until tooling and systems are ready to use ADL1.5, by which time we will have experience with V1-unstable and have a better understanding of whether V0 is really necessary. Ian --- ## Post #4 by @yampeku I tested v0 with LinkEHR editor and works just fine\. I think that 'v1\.0\.0\-unstable' has additional problems, such as deciding which words are allowed \(e\.g 'unstable', 'firstdraft', 'alpha', etc\.\), which means that tools have to be modified anyway\. Arguably, is better to widen a range than to parse specific strings which end changing in the end\. Also, adding this breaks all current v1 slots \(related to my last question to the list\) v0 is also fully compliant with SemVer, which means that in theory archetype identifiers won't need to be changed when we move to ADL1\.5 \(going with v1\-unestable will need another change in the future\) --- ## Post #5 by @ian.mcnicoll Hi Diego, Just to be clear, under ADL1.4 the -unstable suffix (and other naming metadata) will not be added to the archetypeID but will be carried in the other_details metadata, so it does not disrupt current tooling. It is up to developers to decide how much of that metadata to make use of for now. When we move to ADL1.5 these new 'other_details' metadata items will become formal AOM and RM attributes but I think Thomas plans to keep the core archetype_id identical, again to minimise disruption. The only exception in ADL 1.4 is that V0 (if adopted) will potentially break some tooling or back-end systems. None of the other changes should cause things to break as long as other_details is supported correctly. Glad to hear LinkEhr is behaving correctly. We have made some changes to Archetype Editor, which will be released shortly, to ensure that other_details behaves equally well!! So until ADL1.5 comes along -unstable will not break anything. Semver does not actually specify which 'pre-release' labels are allowable. After a lot of discussion we decided that there were really only 2 pre-release states that have semantic significance in openEHR (and probably other archetypes) unstable => This archetype is in development or re-development and the formal Major/Minor/Patch identifiers cannot be relied upon as an indicator of whether the archetype is backwardly compatible i.e once the archetype enters an unstable state, the formal version numbering will remain unchanged, even though the archetype itself is not backwardly compatible. The major/minor/patch numbers will only be adjusted at time of publication or re-publication or when it goes into pre-release state - se next pre-release=> This archetype is still in development but the authors are confident that any future changes that are made will be trivial, and as such are prepared to adhere to the formal version numbering rules, just as if the archetype was fully published. CKM will not allow 'pre-release' to be set (for now). We can discuss allowing alpha, beta etc but really all that developers need to know is that once the -unstable flag is set, they need to be aware that this archetype is really not fit to be used operationally and is 'at your own risk'. The additional Build number identifies the archetype instance very specifically. Ian --- ## Post #6 by @system Hi Ian, I prefer V0, because it would be easier to adopt for other developers who do not know openEHR well\. For parser implementation, 1\.0\.0\-unstable is not a good design, because it is not clear that which is the later release amongs, unstable, testing, pre\-release, release\-candidate, draft, etc\.\.\. I would suggest 0\.9\.9 instead of 1\.0\.0\-unstable\. We can revise the revision 0\.9\.9 after it released, to 0\.9\.9\.9\. or 0\.9\.9\.99\. Shinji --- ## Post #7 by @thomas.beale Hi Ian, I don't think this is true. Firstly, the standard first possible version is v0.0.1 in any versioning environment I know of; secondly, the rules that I thought we were adopting have the following implications: I may still be missing something here, so this analysis is what seems sensible to me based on what I know today. - thomas --- ## Post #8 by @ian.mcnicoll Hi Shinji, Can I suggest you read the [semver.org](http://semver.org) specifications? Semver is now used pretty widely in systems and tooling (including the nodeJS Package Manager NPM). We have taken the - suffix directly from those specifications and in other respcts we are now following semver exactly so there should be open source parsers out there that can be used. Semver exists because we have to treat semantic specifications differently from normal software builds. In normal software alpha, beta, pre-release and indeed the numbering chosen do not need to have any computable significance. Windows 9 is only called Windows 9 for marketing reasons ,not because it represents a breaking change. My recent Yosemite Beta 3-> Beta 4 update may make all sorts of breaking changes but is still a Beta and appears to be only a build different from the Developer Pre-release Yosemite candidate. When we are dealing with Semantic artefacts such as APIs or archetypes, the numbering scheme and suffixes have very specific meanings and rules, to do with backward compatibility. The -suffix is necessary to make it very clear that this is a pre-release artefact and that the normal versioning rules do not apply. What comes after the suffix does not really matter and The prime responsibility we have as archetype authors is to make sure that developers know whether they are working with a stable, published archetype which has followed the versioning rules, or an unstable archetype where those rules are temporarily suspended. It is impossible to do this clearly with a numbering schema alone which is why the - suffix is well-established in SemVer and the tools which use it. In normal circumstances unstable archetypes would never be used in production systems. Ian --- ## Post #9 by @system Hi Thomas and all, The point when it becomes v1.0.0 is when the archetype is first published - i.e. the first published version will always be 1.0.0 and not v1.2.0 If the transition to v1.0.0 comes from v0.0.1[-unstable] or v1.0.0-unstable doesn't really matter - purely technically speaking the terms of stability and lack of commitment are the same for both 0.0.1[-unstable] and v1.0.0-unstable Supporting it as part of the specs for uncontrolled/chaotic development is one thing and I agree. But what we are looking at here is that all CKM archetypes would have a v0 extension until they are first published (as v.1.0.0). Existing pre-publication CKM archetypes would be converted to have a v0 extension (either as a batch or one-by-one when each one is updated the next time) That's not really an option unless you want to make this migration even more difficult. What you are suggesting requires two different sets of rules and someone needing to deciding which stays at v1 and which is converted to v0. I don't think it makes sense - either we use v0 to indicate pre-publication archetypes or we don't. Sure, looking forward to tooling support on it, but realistically at the moment it is a pain that is not needed for the first publication if you go with v1 as a the initial major version. Sebastian --- ## Post #10 by @ian.mcnicoll Hi Thomas, I agree with all you haver said but would stick to my original assertion that for *practical' and computable purposes, in terms of fitness to be used in an operational system and adherance to the version number rules, v0.0.1 and v1.0.1-unstable are identical. Both, when published will end up as V1.0.0, both are unstable. I can see the human argument for differentiating a truly feral archetype from one in a controlled repository but am not convinced that this outweighs the hassle of supporting V0 in ADL1.4. When we move to ADL1.5 tooling and downstream systems will need to be changed in any case, so perhaps that is the point to formally introduce V0? Agree with your other points and examples. Ian --- ## Post #11 by @system Actually, this is clearly defined by SemVer, see rule 11: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. But I don't think we would usually want to do this at all for unstable archetypes. They are just unstable, no guarantee whatsoever. If you want to have a specific one, you can always use the unique build id for that. Sebastian --- ## Post #12 by @system Hi Diego, That's great, although in this case I think you are actually being too lenient if you strickly stick to the current spec which defines a V_IDENTIFIER as [a-zA-Z][a-zA-Z0-9_]+(-[a-zA-Z][a-zA-Z0-9_]+){2}\.[a-zA-Z][a-zA-Z0-9_]+(-[a- zA-Z][a-zA-Z0-9_]+)*\.v[0-9]* v1.0.0-unstable is also fully compliant with SemVer - I don't understand why this would require more changes in the future that v0 doesn't need? Sebastian --- ## Post #13 by @ian.mcnicoll Thanks Sebastian, You are correct, of course, there is a rule about this, but is just about lexical matching e.g. -a is allowable and -a < -alpha. The labels themselves have no meaning. On that basis, perhaps -unstable should be renamed to something earlier in the alphabet to fit with the matching rule i.e so that it comes before -rc? On the other hand we do have a very specific meaning for rc, which is that although this is still an archetype in development, it will obey the versioning rules if it has to change. Ian --- ## Post #14 by @thomas.beale that sounds right to me - is it a problem? I would have thought that individual archetypes can have their version modified? I don't think the world minds if there is a period of a few months during the industry sprint when the rules are technical being broken. Once it's done, there will be 70+ archetypes with v1.x, and the rest with v0.x, and that will correctly represent the situation of the archetypes in CKM. Then for every mirroring, copy, and reuse of what's in openEHR.org CKM, there is no need to educate anyone on anything - it's obvious what the situation is. So we are only talking about a limited period of time where the rules are being broken (as they are right now in fact ;-) well I think its a bigger danger, given the level of reuse of CKM archetypes, that the version ids wouldn't correct reflect the state of the archetypes. We could in theory revert everything that is not published to v0 right now, and i guess that is breaking the rules for less time. But there are still some dozens of fully reviewed and published archetypes that have to retain their v1.x version anyway. So I think the only question is to do with the industry sprint archetypes. How about doing this: If I receive a copy of archetypes marked like that in say the GitHub mirror, or through a different CKM, I don't need any further education, it's obvious what's going on. - thomas --- ## Post #15 by @system Yes, not really that nice, is it - it just works coincidentally. That's one reason I said I wouldn't want to use more than one. Good point. Still if we use -unstable and -rc, we cannot claim to fully embrace the SemVer rules for precendence. Sebastian --- ## Post #16 by @ian.mcnicoll How about -ardvaark or -awfullybadideatousethis I would be happy with -alpha. I know it is a technical term but it would not normally be visible to a clinical audience, who are going to see 'real' publication process states like draft, team review etc. -alpha sends the correct message to developers that this thing is risky! Ian --- ## Post #17 by @system Hi Ian\. I have read once SemVer, but it is still confusing about suffix\. especially "alpha\.11 > alpha\.beta > beta\.1" sequence\. This needs tricky grammar rule to parse\. Hi Sebastian, I think revision history should be exclusive, even it is unstable version\. Regards, Shinji --- ## Post #18 by @sebastian.iancu Dear all, I'm surprise to see such a low analysis of the impact of changing v1 to v0 of the existing CKM archetypes\. Even though they are not 'published', or are in logical 'draft' mode, they were conformant to openEHR standards for at least past 5 years or so\. Some of them are used already in production environments for more than 2\-3 years \(at least in our case\)\. Changing them now on CKM will break logical binding with already existing production data\. This cost has to be eventually supported by industry implementers, and I can assure you this is not trivial, and it is giving the impression that openEHR standard is not reliable/stable enough\. Basically the proposal is to rename existing CKM archetypes \(published or not\) in contradiction with what the current openEHR specifications is stating right now, which is not right\. Other than this, I personally think that is nice to have v0 for 'drafts', and v1 for stable\-published; it might be a better indication about a state of an archetype\. So my suggestion is to keep existing CKM archetypes the way they are and only apply the new 'rule' for archetypes created from now one\. Published archetypes from the sprint can become v2 \(or 3, 4 etc\) depends on the need \(see specifications\)\. Sebastian Code24 --- ## Post #19 by @system This is what works in a CKM test version, so no it is no problem (but is certainly more complex than it may sound) You are trying to eat your cake and have it. For semantic versioning to be implemented in CKM, the version numbers need to be under CKM control. And then for your revisioning to work, CKM needs to know which archetypes should be converted and which ones shouldn't and then apply different versioning rules to them. I see no reason to add to the complexity like this. I don't care when it is done. It can either be as a batch or each time you change an archetype next. But when you change it next, CKM then needs to apply the correct revisioning rules to it or it will just be an endless migration mess. I don't see your problem. Naturally, published archetypes would not change their .v1 version to .v0. As above, then you are applying two different set of rules for migration, depending on whether the archetype is in the industry sprint or not. Apart from the additional complexity I tried to explain, what is the point? The only point I can see is that you want to identify industry sprint archetypes: I think they are all part of one project now and you can easily get them from there. Well, I for one, would not understand without your explanation that the difference between 0.5.0 and 1.0.0-unstable is that the one is in industry sprint and the other isn't. There are more logical ways to me to find this out (just look at the CKM project). Sebastian --- ## Post #20 by @yampeku > > Hi Diego, > >> >> I tested v0 with LinkEHR editor and works just fine. > > That's great, although in this case I think you are actually being too lenient if you strickly stick to the current spec which defines a V_IDENTIFIER as > [a-zA-Z][a-zA-Z0-9_]+(-[a-zA-Z][a-zA-Z0-9_]+){2}\.[a-zA-Z][a-zA-Z0-9_]+(-[a- > zA-Z][a-zA-Z0-9_]+)*\.v[1-9][0-9]* > We changed this 6 or 7 years ago when we removed the "v1draft" kind of identifiers that were a thing back then. We also allow the definition of single letter entities, that this regex does not allow but specifications did allow at least back then (not sure if still do). As somebody said "Be conservative in what *you* do, be liberal in what *you accept* from others" ;) > >> >> v0 is also fully compliant with SemVer, which means that in theory >> archetype identifiers won't need to be changed when we move to ADL1.5 >> (going with v1-unestable will need another change in the future) > > v1.0.0-unstable is also fully compliant with SemVer - I don't understand why this would require more changes in the future that v0 doesn't need? > Sebastian > I said that because we have to agree to a valid list of words we support for versions, and this kind of decisions are not easily taken (take for example the possible lifecycle status of an archetype). If we also override the lexic order then we must change it to fully agree with semver --- ## Post #21 by @ian.mcnicoll Hi Shinji, Github is your friend - see [https://github.com/npm/node-semver](https://github.com/npm/node-semver) but I agree, it is tricky. However it is simply not possible to manage the transition between stable and published archetypes safely by just using numbering alone. We need to very explicitly flag that unstable state so that it can be parsed safely - this is what the '-' gives us. We did look at all sort of numbering schemes and alternatives to Semver but eventually came back to the view that this is pretty well how it has to work. One big advantage of sticking with Semver is that we can take advantage of work like the NPM parser, apart from the The 'exclusive revision history' (if I understand you correctly) comes from the Build identifier, identified by a '+' So an unstable archetype may be v1.0.1-unstable+145567345 and after some internal authoring or reviewing goes to v1.0.1-unstable+35634512 The build identifier is not guaranteed to be sequential and there may well be breaking changes between the first and second iteration. From the developer perspective I can know exactly which build of the archetype I am using in my system, and that it is unstable. I would be very unwise to use this in any production system but may of course need it in a testing phase, or need to support its use within tooling. I am not wedded to -unstable , but I think you will find that if you try to work with some other number=based system, you always hit a problem ,and that some kind of pre-release signifier is required. If we agreed that openEHR would only officially support -unstable (or -alpha) and -rc, that would greatly simplify the parsing. Ian Ian Implementers do not have to parse what comes next --- ## Post #22 by @ian.mcnicoll Hi Diego, "... we have to agree to a valid list of words we support for versions, and this kind of decisions are not easily taken (take for example the possible lifecycle status of an archetype)." I agree that we should at least agree a limited list of reserved words which we are suggesting as -unstable (or -alpha) and -rc, which have very specific meanings in terms of the adherence of the archetype to the numbering rules. This 'flag' is purely the minimum required to indicate how/if the archetype adheres to the formal rules. Authoring lifecycle states (pre-draft, draft, team review etc) are handled separately and although it would be better if these were harmonised, they may differ across different RMs, modelling communities. I agree that we should avoid breaking the lexical order and re-think -unstable. -dev , -alpha, any other suggestions? Ian BTW we got rather more deeply into the rest of the renaming proposals discussions than we had intended! Our immediate priority is to resolve the V0 question, so that Sebastian get get the next CKM upgrade out of the door. Ian --- ## Post #23 by @system Sebastian, Although you are for sure right in your worries, that doesn't mean that current archetypes managed in CKM are safer\. For many years most of the current v1 archetypes in CKM where in draft and that meant that they have been changing without changing their id\. You can protect your systems if you check archetype correspondences not only by the archetype id but using something else such as their hash code\. And in that case, changing to v0 should not mean any difference or additional problem\. David --- ## Post #24 by @system Hi Ian, I would prefer https://github.com/flazz/semver/ , but not explain :\) CKM shows archetype revision history tree, but the version is not changed\. For example, openEHR\-EHR\-OBSERVATION\.blood\_pressure version has been kept 1 in these years, but it has 26 revision up\. I think it is non\-sense to change version by each revision commit, but meaningful change should be reflected to the version number, such as adding item, fixed typo, translation to other language completed\. Shinji --- ## Post #25 by @system Sorry, I have misused "exclusive" to "explicit"\. It is explicit mistake\. much sorry to confusing you\. Shinji ashamed\. --- ## Post #26 by @system Hi Sebastian, I realise you are physically not too far away from me in Germany and we even share the same name, so I hope you won't shoot the messenger here, but I have to say the following... The consequence of what you are saying would be that we cannot publish any v1 archetype if it is already on CKM without an analysis if there have been any breaking changes anywhere during the development and review process (which would be the case in most cases I suspect). However, this is the case with or without any of the changes being discussed here: It doesn't matter if draft archetypes become v0 for a while: once they are published they'd be v1 again anyway - and likely incompatible with the previous v1. If on the other hand, you leave the CKM draft archetypes as v1 and they are published subsequently, there is also no guarantee whatsoever that the published version is compatible with any draft revision (or any of the draft revisions with each other). Either way, if you use them now, no, you cannot just replace a draft archetype with the next revision of the draft archetype or its subsequently published revision. You cannot do it now, because there is no guarantee that they'd be compatible and you cannot do it with or without v0. So, while I certainly acknowledge the problem (more below), it is not a problem that is caused or increased by migrating draft archetypes to v0. And in fact solving this problem is one of the core reasons for the proposed revisioning rules. You will know exactly where you are at and how compatible two archetypes are. So, if you as a company use draft archetypes, this is the risk you have taken - draft archetypes just cannot be assumed stable or backwardly compatible just because they happen to be expressed in (more or less) correct ADL. The impression that draft archetypes are stable has of course been given by the lack of activity in getting draft archetypes published on the international CKM. The industry sprint will hopefully change the momentum of this considerably. The problem you describe is more or less the same for every vendor that uses unstable archetypes, which for lack of alternatives, will most likely be about every vendor. However, I can see some ideas for a solution to this problem, because you can clearly identify all archetypes under the new revisioning rules vs those that are not. Most importantly, archetypes under the proposed revisioning scheme will have a namespace whereas the old ones don't. In ADL 1.5. two archetypes with two different namespaces are two completely different archetypes. The same logic could just be used in ADL1.4, even if we can only express the namespace as part of the other_details section at present. Also, they would have the complete revision number (in other_details) that gives you another indicator as well as the development lifecycle in the archetype. So when you want to upgrade your system to replace an archetype that was a draft archetype with a v1 extension with a freshly published v1 archetype with the proposed revisioning rules, you can do this pretty safely by considering the namespace. It then is just like any other incompatible change to an archetype that would cause a replacement of the archetype - the only difference being that the namespace is changed, not the version number in this case. As I said I believe that this is a problem regardless of v0 or not and that it certainly is a problem of some sort for about every vendor. Therefore, I think it deserves a thorough discussion in a separate thread. Could you start this thread if you agree with me that this is a general problem rather than a v0 or v1 problem? Cheers Sebastian --- ## Post #27 by @system Hi Shinji, With the new revision rules a la SemVer we now have: There are some grey areas, but the intention is clear I think. In CKM, you can do this with the new revision rules. CKM will suggest a new revision number based on this general idea. In any case you can always go higher - if you think a patch change is so significant because of the wording that has changed, it can also be a minor (or even major) version increase, i.e. instead of going from v1.0.0 to v1.0.1, you go to v1.1.0 To take the example of the BP archetype that you mention: The archetype was published in Rev 16 in 2009. Since then it has encountered several more changes to it like adding a couple of translations. None of these would be a breaking change to my knowledge. So, in the old rules it just remains v1. With the new revision rules, the archetype would have been published as v1.0.0 in 2009 and would now maybe be v1.2.4 (or whatever) - which means it had a number of patches and 2 minor version changes in total, none of them backwardly incompatible. Is this the kind of stuff you are missing? If so, this is exactly what the revisioning rules are there for. Cheers Sebastian --- ## Post #28 by @ian.mcnicoll Hi Shinji, For clarity ... CKM 'revisions' have nothing to do with the official openEHR major.minor.path numbers. They are an internal format to do with the local workflows inherit in openEHR. We have discussed changing CKM 'revision' to something else to make this clearer. The official major.minor.patch number proposals are intended to be neutral to the use of CKM or any other repository tool, even the use of a simple Git repo, and make no assumptions about how the assets are organised within that repo e.g a git-based repo may have a quite different Trunk/branching method and use branch names/ tags to handle internal workflow. The aim of the openEHR major.minor.patch scheme is to ensure that where an archetype is used outside of a repo, in tooling or in applications, that the consumer can be very confident about the exact provenance of the archetype and especially its stability. So ignore what CKM does internally, that is not important in this context. In the future each archetype in CKM (and we hope other controlled repos) will also label every asset and version of the asset using major.minor.patch -XX + build, alongside what ever local internal versioning scheme they require. Ian --- ## Post #29 by @system Hi Ian and Sebastian, The rule figured by Sebastian and the explanation by Ian looks very clear, thank you\. But we will need to additional rule/guide to make it clear what is 'major' or 'minor', in the next step\. For example, if the archetype was converted from ADL 1\.4 to 1\.5\(or later\), is this minor change or major change? ADL conversion may break compatibility for machine readability, but not change in clinical semantics\. If an archetype was changed to be semantically incompatible, I think they should not be assigned for same archetype id\. regards, Shinji --- ## Post #30 by @system Hi Shinji, Good question \(again\) :\-\) It all comes down to whether the change from a 1\.4 to 1\.5 archetype changes the path to query any of the content\. Thomas is better placed to explain in more detail but the current suggestion ,supported by Industry is that ADL1\.5 archetypes should be backward compatible with their ADL1\.4 equivalents i\.e no change to the path structures\. Thomas's current work with CIMI is taking ADL to a place where some AT codes are being replaced with ID codes\. Whilst this is probably the right direction of travel, it does mean that changing to the current CIMI ADL \(which I think will now be called ADL 2\.0\) would result in every archetype path breaking\. Thomas is confident that the changes to the archetypes themselves can be made automatic but the problem remains that inside the patient record the old AT code\-based paths remain and thus incompatible with the new ADL 2\.0 archetype\. indeed if there are any query statements or other path references in the programming code that would also need to be updated\. The strong view from Industry at the Oslo meeting was that we should move to ADL1\.5 tooling support, with ADL 2\.0 as a later exercise\. I suspect we will bulk migrate ADL1\.4\-> ADL1\.5 with relatively disruption, but that ADL 1\.5 \-> ADL 2\.0 will need to be supported side\-by\-side because of the need to maintain backward compatibility in data\. So to answer your question ADL 1\.4\-> ADL 1,5 should not require blood\_pressure\.v1 \-> v2 ADL1\.5 \-> will require blood\_pressure\.v1 \-> v2 but I think this can be handled on a case\-by\-\-case basis as each archetype naturally comes up for revision\. Ian --- ## Post #31 by @thomas.beale but none of the existing CKM archetype ids has a namespace, so the new ids will be distinguishable from the old. It would be useful to have some real data on who has used any CKM draft (i.e. 'old') archetypes in real systems to know is there is in fact a problem here or not. Anyway, the renaming should follow the model: openEHR-EHR-ADMIN_ENTRY.encounter.v1 => openEHR-EHR-ADMIN_ENTRY.encounter. => review & changes => openEHR-EHR-ADMIN_ENTRY.encounter. so there is no way for the first and last versions to get mixed up that I can see. ah, you got there before me ;-) - thomas --- ## Post #32 by @thomas.beale I don't see how that can be. The former is for some uncontrolled archetype from an unmanaged external location, and the latter is a post v1.0.0 archetype in development, after having been published as v1.0.0.... in entirely different ways. the v0 isn't technically under development in CKM until you start working on it. That might be 6 months after upload. in ADL 1.4? I don't know, but the identification and versioning rules for CKM , even while it still has 1.4 archetypes, needs to be of the 1.5 variety. I thought the whole point was to introduce new style versioning (namespaces, 3 part version ids, extra meta-data) into CKM now? If so, why would we not include 'v0', which is part of that spec? - thomas --- ## Post #33 by @sebastian.iancu Hi Sebastian G, David M, Thank you for your elaborate answers\. I can proudly say, years ago, we were one of the early adopters of openEHR\. We've been there \(in fact actively participating\) when the CAM\-hash was introduced, or when \.v1draft was replaced with \.v1, or when the archetype\_id versioning policy was polished, or when Thomas started to work on distributed knowledge management and artefact identification\. I'm not a stranger to the fact that CKM archetypes are changing without having their version updated, sometimes breaking existing specifications\. I also acknowledge the benefits of the industry\-sprint, and that we need clearing things out in CKM content for that\. Finally, as technician, I'm aware of the impact of using 'draft'\-like artefacts in own software\. But, I cannot agree with a mass regression to v0:   \* What's the point of having this boolean logic where draft=0,     stable=1? Are we never going to have v2? And if yes, would that mean     something \(published\-on\-Mars\-aswell, or sprint\-2\)? The version     itself should not be important \(we can have v1 or v87\), it matters     only in relation with other versions and a timeline\.   \* There are already released specification about versioning, so why     violate them doing odd regression?   \* There is no guaranty that all current drafts will be published some     day \- in which case we might be stuck with v0, while v1 was already     available up to 2014\. Why should we destroy something that already     exists and it works?   \* We know CKM content is not perfect, archetype changes are not fully     considered in their version \- why should we create even more mess? Furthermore, for my point of view:   \* you hardly get early adopters if you discourage them to use 'draft'     archetypes   \* an archetype uploaded on CKM is in fact sort\-of technically     published, although not domain\-published\. Breaking it constantly     makes it unusable and lowers the adoption or real\-life testing chances\.   \* encouraging vendors or consumers to use their own archetype     repositories \(own namespaces\) as opposed to a global own \(CKM\) is a     threat to interoperability, and defies some of the openEHR principles\. In conclusion, I'm not at all against the new versioning identification, discussed these days \(i\.e v1\.2\.3, etc\), as long as it is introduced only in/for upcoming specifications \(ADL 1\.5, 2\.0 whatever\) and it is not breaking existing systems based on RM 1\.0\.2 and ADL 1\.4 archetypes\. Keep things simpler and don't focus too much on only syncing with semver, while you forget the big picture where these archetypes are actually used for \(namely to describe data\)\. Sebastian Code24 --- ## Post #34 by @yampeku I agree with your points\. I would say that some of your points are the reasons people is reluctant in adopting openEHR more\. It's not all about licenses\. It has always puzzled me why there is not a single v2 archetype in CKM after 7 years\. --- ## Post #35 by @system While a v0 would certainly be a draft, a v1 is not necessarily stable. v1.0.0 is stable, and so are e.g. 1.0.1 or 1.1.0 - but 1.0.1-unstable or 1.1.0-unstable are not Of course the will be v2 archetypes - if you break the archetype in a backwardly incompatible way. This is the case now, it just hasn't happened, partly due to editors trying to avoid incompatible changes if not necessary, partly because many changes have been simple [compatible] additions, partly because the better and comprehensive the feedback you got during the pre-publication review rounds reviews and more careful you were when designing the published archetypes, the less you need it and partly because the more important problem has been to get more draft archetypes reviewed and published. But the current CKM would strongly advise editors to republish a previously published archetype as v2 if there has been an incompatible change. With the revisioning rules in place, CKM will even create it for you automatically if you like when there have been incompatible changes between the currently published revision and the revision that is to be published. I think you have a point here against using v0. If we use v0 and still use current 1.4 rules than this would indeed be weird and messy. Essentially, as soon as you start to use these, you will have to acknowledge namespaces at the very least and maybe this should not be a requirement if you just want to continue to work the way you do now. I agree that CKM content is not perfect of course, but all archetype changes follow the current versioning rule that you have to increase the version identifier if there has been a breaking change. This is for published archetypes, drafts are simply unstable. True, I don't think anybody wants to particularly discourage their use, but you have to live with the risk. I think the bottom line for most of your points here is that we urgently need more published archetypes that stick to the rules and enable semantic interoperability. I think everybody would have liked to see something like the industry sprint happening 5 years or so ago, but I am very glad it is happening now. I too think that adding them to the next ADL version and not breaking what is currently in use is important. Namespaces and the revision number etc. would only be available in the other_details fields in ADL 1.4. And of course these fields have no formal meaning per se. So I think if we don't use v0, then you could continue to work in the same way as you do currently. You can then decide to start using these fields when you see fit (or not). What I personally don't like is having a mixture between non-published archetypes in CKM, some of which are v1 and other (newly uploaded) ones that are v0. I think this is indicating different levels of maturity for anybody looking at it, even if both types are simply non-published/unstable. Sebastian --- ## Post #36 by @heather.leslie Hi Diego, There will be a v2 very soon\. It will be the first of the small number of published archetypes that has had backwardly incompatible changes required\. It is Indirect Oximetry which will go out for further review next week, but we already have had a breaking error identified\. Regards Heather --- ## Post #37 by @Sam Hi Diego Version 2 archetypes are more likely to arise (in my opinion) when there are changes to the RIM. Having spent some time designing archetypes in a vacuum, it is clear that they are usually far more inclusive and comprehensive than existing systems, and any alterations are usually revisions (adding data without breaking existing data). I am pleased that this has been the case as multiple versions of the same data will require massive increases in processing - there needs to be a good reason to break from existing data. Cheers, Sam Dr Sam Heard Chairman, openEHR Foundation --- ## Post #38 by @yampeku Breaking data could be as easy as modifying a regular expression in a slot, but I've seen worse things than that happen to some archetypes \(drafts, but I don't understand why such a resistance to go up a version digit\.\.\.\) --- ## Post #39 by @system > Breaking data could be as easy as modifying a regular expression in a > slot, but I've seen worse things than that happen to some archetypes > (drafts, but I don't understand why such a resistance to go up a > version digit...) Especially since I was working with the Semver convention before the year 2000. Microsoft used it, Linux used it. Everywhere. Maybe it was not called Semver in those days, but a similar convention was widely spread. The "draft" idea is a mistake, it is never to late to change it and forget it. The "v" can also be removed. Just counting from zero for a draft version, and from one or higher for a ready version. So an archetype name would then be org.openehr:openehr-ehr-composition.something:0.1.2 for a draft, org.openehr:openehr-ehr-composition.something:0.1.3 for a draft revision, and org.openehr:openehr-ehr-composition.something:1.0.0 for a ready version. Some people need to change a small aspect of their software, if this would be expensive the software needed change anyway. This is my opinion. I was following this discussion a bit wonderingly. best regards Bert Verhees. --- ## Post #40 by @system It seems wise to me to not regard the version\-indication as a part of the archetypeId, the same for the namespace\. The archetypeId is to indicate what the conceptual contents of the archetype is about\. The version does not changes this, so it should not be part of the archetypeId, the same for the namespace\. This idea justifies the use of the colon between namespace and archetypeId and between version and archetypeId\. It also makes the use of the "v" before the version unnecessary\. "V" is a language\-specific indication, "v" stands for "version", and "version" is an English/Latin term\. In Danish they say "udgave", in Russian it is "версия", in Hebrew: "גרסה", in Arabic: "نسخة", in Maori: "putanga" and in Chinese: "版本" Wonderful tool, Google translate ;\-\) Bert --- ## Post #41 by @yampeku it's also 'versión' in spanish ;\) --- ## Post #42 by @system I like your reasoning Bert. --- ## Post #43 by @system Thanks :-) --- ## Post #44 by @system > it's also 'versión' in spanish ;\) Spanish is a Latin\-language ;\-\) --- ## Post #45 by @system Hi Bert Thanks for getting involved in this important discussion\. I am on a plane and don't have ooportunity for a full answer but it is not as simple as u have suggested\. Amongst other things You have to consider what happens to archetype numbering when the archetype has been published and goes back into review, at which point it is in an unstable state\. More to follow when I have landed\. This is not the same as handling normal software updates even though superficially the major minor patch arrangement is similar\. In software development these are arbitrary states\. In semantic versioning major minor and patch need to have very specific meanings and rules attached \(whether semver or some alternative is used\. To other developers , please get involved in this discussion\. We really need feedback\. Ian Dr Ian McNicoll Clinical modelling consultant freshEHR Clinical Informatics Mobile \+44 \(0\) 775 209 7859 Skype imcnicoll --- ## Post #46 by @system > Thanks for getting involved in this important discussion\. I am on a plane and don't have ooportunity for a full answer but it is not as simple as u have suggested\. Amongst other things You have to consider what happens to archetype numbering when the archetype has been published and goes back into review, at which point it is in an unstable state\. More That is why you often see in addition to Semver\-conventions some terms added\. My bash\-version for example is: GNU bash, version 4\.3\.11\(1\)\-release, My Linux version is: 3\.13\.0\-36\-generic Most artefact producers have the need to communicate more then only the version\-number\. The discussion is if the version\-number is the place to communicate this\. Software too can become stable, unstable, unsafe, release, beta, without anything changed to the bits and bytes\. But suppose it is: Suppose you have version 1\.1\.3\-release, and then you have 1\.1\.3\-unstable, which is later? You cannot tell\. So if 1\.1\.3\-release is followed up by a unstable\-indicator, it must be visible which of the two is later\. The version itself has not changed, because the archetype has not changed\. A solution can be, something like bash does: 1\.1\.3\(1\)\-release, 1\.1\.3\(2\)\-unstable, 1\.1\.3\(3\)\-release The Semver version\-number indicates that the code did not change\. The archetype stayed exactly the same, but the status changed, and status \(3\) is later then status \(2\) or status \(1\) In my opinion the version\-numbering must have nothing to do with the status of a product\. In the past they did that with Linux, even\-numbers where stable and odd\-numbers in development phase\. They left this system for several reasons\. One was, you could not always tell which code was later, the other reason was, two possible states were not enough\. Semver is not the ultimate answer, you almost never see a product which is only using version\-indicator, they almost all add something\. But Semver is much better then "draft", which remains draft for years and has changed many times without any version\-indicator\. Bert --- ## Post #47 by @thomas.beale Note that in AOM 1\.5 \(to be renamed AOM2\) spec <http://www.openehr.org/releases/trunk/architecture/am/aom1.5.pdf>, the idea of fixed string 'ids' is gone\. Multi\-part ids are now generated functionally\. See Fig 8 Right now, the functions interface\_id and physical\_id are defined a certain way, and they do include the 'v'\. But other functions can be added\. The only place I can think of where the full string id really matters is in ADL syntax\. In all other syntax, it's in pieces\. E\.g\. this is the JSON output from the current AWB for a flat archetype serialisation: I don't personally think it matters about having the 'v'\. Although I fully agree that the anglo\-centric nature of the internet \(domain names, etc et\) and IT in general \(UML models are mostly published only in latin alphabet languages, and mostly english in multi\-national orgs and standards orgs\) is in one sense unfair, it's also a\) there and b\) useful in solving what could otherwise be protracted and useless debates on minutiae\. The main reason to keep it is for backward compatibility in ADL texts; we could certainly define an 'id' function without it\. \- thomas [details="(attachments)"] ![aehahefi.png|697x388](upload://foDErLTQBRSSioNvoEl7wAX5GWq.png) ![ehigebbb.png|509x598](upload://nQLevF2jPZ6CAvZQxppiDfZMtJE.png) [/details] --- ## Post #48 by @thomas.beale the latest rules that Ian and Sebastian have worked out would mean that if there was 1\.1\.3 released, then the next version of that archetype if it goes back to development is 1\.1\.4\-unstable, i\.e\. at least the patch number has to be incremented\. It could be that something more is incremented say 1\.2\.0\-unstable\. So I think this is pretty logical \(and also pretty much the way we do it in software\)\. \- thomas --- ## Post #49 by @system That is also possible and very logical\. I wouldn't spent too much discussion on the difference between my proposal and your rules\. As long as everyone understands it, and it offers enough detail, it doesn't matter much\. Bert --- ## Post #50 by @system Hi Sebastian, Many thanks for your input. Your contribution is particularly important as Code24 is, as you say, one of the early pioneers of managing openEHR data and related artefacts. You have raised an important and very real issue, but I agree with Sebastian Garde that the .V0 question itself, is actually not what is going to potentially cause you a problem. Firstly I would defend what has been done in CKM to date as being completely in line with the specs and with the revisioning rules (which actually have worked extremely well for published archetypes). It has always been clear that any archetypes not marked as 'published' must be considered unstable and cannot be guaranteed to follow the numbering rules. I understand why you might take a view that 'anything that appears in CKM is de-facto published' but that is not, and never will be the case. CKM is first and foremost a clinical review environment which will always contain a mix of draft, published, re-draft and re-publshed archetypes. Having said all that, none of us are happy that it has take so long to get to a stage where we could get sufficient resource to properly fund editorial resource to take many archetypes through to publication though thankfully, through the Industry Sprint that point has now arrived. I am also familiar with and have sympathy for the issue you have raised which I will try to elucidate here, as I agree with Sebastian that it is a separate issue from V0. Your current situation is that you have used .v1 archetypes in your production system, even though they are marked as 'draft' in the metadata and by definition will have unstable structures leading to a situation where ongoing draft development and eventual publication of the draft v1 archetype may well break existing query paths in your patient data and in related code and querying statements. Although you can differentiate the draft from published archetypes in the archetypes themselves, there is no way that you can tell whether the instantiation of problem_diagnosis.v1 in patient data refers to the published version or to the previous draft version (and this may well include a breaking change). The problem essentially is not that the archetypes themselves are mis-labelled but that the archetypeId carried in data is not sufficient to disambiguate a draft archetype from a published archetype. This is a situation that was discussed on the lists a couple of years ago around the import of the NHHTA lab archetype where it was recognised that calling it lab_test.v1, been though it had many structural changes was going to cause problems for a number of vendors who had used the original draft lab_test.v1 in their applications. We asked the vendor community for their response and the message we got was that "by using draft archetypes we recognised that this might happen" and that we should keep the archetype at v1. I should add that this is not purely an issue for V0/V1 archetypes. When a published v1 archetype goes back into draft we will face the same issue, and for v2 and v3 etc. If vendors are going to use draft archetype in systems and in tooling (and they will) we need to be able to clearly identify unstable archetypes inside patient data and query statements, and not just in the archetypes. Vendors who do this need to understand that such an archetype is unstable and will break the rules but at least it is unambiguously identified in the patient data and any queries. This obviously comes back to the main discussion about the use of -unstable in the Semver proposals and I will try to explain our thinking in response to others who have made alternative suggestions. It turns out to be very,very tricky, and I don't think it is an accident that we have come back to Semver as the basis for a solution. So the issue you raised is real and significant, and will be faced by any vendor who is using a v1 draft archetype in an operational system. Adopting the new naming/numbering system will solve the problem going forward but the question remains about how to ameliorate the problem now There are, I think, three approaches: 1. Implementors accept that the use of draft archetypes was that 'own risk' and that they will have to manage the transition from draft to published, which will entail making changes to program code or query statements which refer to draft archetypes. i.e. rename lab_test.v1 to lab_test.v1-unstable or lab_test.v0. This is clearly a major pain (as Sebastian has said) but vendors we have spoken to so far have indicate that they are prepared to do this. Note that it will not have to be done as a batch, only when the system need to use each published v1 archetype, rather than the draft version. 2. Implementers rely on the new metadata that will be introduced when we publish archetypes from now on. This will include the original namespace and an optional Unique ID which can be used internally in the place of the current archetypeId. So the draft archetypeId reference in the data would be left unchanged as: openEHR-EHR-OBSERVATION.lab_test.v1 and any data captured using the published archetype would be labelled in the data (and any associated queries) as org.openehr::openEHR-EHR-OBSERVATION.lab_test.v1.0.0 or 123453446rhtytyyu.1.0.0 if you prefer When this published v1 archetype needs to go back into review it gets labelled as org.openehr::openEHR-EHR-OBSERVATION.lab_test.v1.0.1-unstable+build.e34dgtj67856 or using the uid - 123rhturytu55634567.v.1.0.1-unstable+build.e34dgtj67856 It is up to vendors to decide just how much of that mouthful to record in data and queries but if you are going to use unstable archetypes in data that is the only unequivocal method of knowing exactly which specific version of the archetype you are dealing with. I doubt that carrying the build is really necessary but knowing that this is v1.0.1-unstable is important, and resolves the problem that we all face right now. 3. The final option is that in CKM publication we bend the rules and go straight from V1 drafts to V2. We have discussed this as an editorial team and are not keen on the idea because it is a bit confusing for our clinical reviewer audience. If I was implementor I would go for option 2. At some point very soon I am going to have to get to grips with the need to identify namespaced and unstable archetypes in data. I don't have to upgrade to the new published archetypes right away, or as a bulk process but when I do so it makes sense at that point to be able to handle the kind of extended archetype naming that is proposed. Sorry that this was a bit of a tome. This ends up being a pretty complicated subject and part of the reason it took so long to figure out! We really need feedback. Everyone feel free to pitch in and argue!! Ian Dr Ian McNicol mobile +44 (0)775 209 7859 office +44 (0)1536 414994 skype: ianmcnicoll email: [ian@freshehr.com](mailto:ian@freshehr.com) twitter: @ianmcnicoll Director, freshEHR Clinical Informatics Director, openEHR Foundation Hon. Senior Research Associate, CHIME, UCL --- ## Post #51 by @ian.mcnicoll Hi Sebastian, Many thanks for your input. Your contribution is particularly important as Code24 is, as you say, one of the early pioneers of managing openEHR data and related artefacts. You have raised an important and very real issue, but I agree with Sebastian Garde that the .V0 question itself, is actually not what is going to potentially cause you a problem. Firstly I would defend what has been done in CKM to date as being completely in line with the specs and with the revisioning rules (which actually have worked extremely well for published archetypes). It has always been clear that any archetypes not marked as 'published' must be considered unstable and cannot be guaranteed to follow the numbering rules. I understand why you might take a view that 'anything that appears in CKM is de-facto published' but that is not, and never will be the case. CKM is first and foremost a clinical review environment which will always contain a mix of draft, published, re-draft and re-publshed archetypes. Having said all that, none of us are happy that it has take so long to get to a stage where we could get sufficient resource to properly fund editorial resource to take many archetypes through to publication though thankfully, through the Industry Sprint that point has now arrived. I am also familiar with and have sympathy for the issue you have raised which I will try to elucidate here, as I agree with Sebastian that it is a separate issue from V0. Your current situation is that you have used .v1 archetypes in your production system, even though they are marked as 'draft' in the metadata and by definition will have unstable structures leading to a situation where ongoing draft development and eventual publication of the draft v1 archetype may well break existing query paths in your patient data and in related code and querying statements. Although you can differentiate the draft from published archetypes in the archetypes themselves, there is no way that you can tell whether the instantiation of problem_diagnosis.v1 in patient data refers to the published version or to the previous draft version (and this may well include a breaking change). The problem essentially is not that the archetypes themselves are mis-labelled but that the archetypeId carried in data is not sufficient to disambiguate a draft archetype from a published archetype. This is a situation that was discussed on the lists a couple of years ago around the import of the NHHTA lab archetype where it was recognised that calling it lab_test.v1, been though it had many structural changes was going to cause problems for a number of vendors who had used the original draft lab_test.v1 in their applications. We asked the vendor community for their response and the message we got was that "by using draft archetypes we recognised that this might happen" and that we should keep the archetype at v1. I should add that this is not purely an issue for V0/V1 archetypes. When a published v1 archetype goes back into draft we will face the same issue, and for v2 and v3 etc. If vendors are going to use draft archetype in systems and in tooling (and they will) we need to be able to clearly identify unstable archetypes inside patient data and query statements, and not just in the archetypes. Vendors who do this need to understand that such an archetype is unstable and will break the rules but at least it is unambiguously identified in the patient data and any queries. This obviously comes back to the main discussion about the use of -unstable in the Semver proposals and I will try to explain our thinking in response to others who have made alternative suggestions. It turns out to be very,very tricky, and I don't think it is an accident that we have come back to Semver as the basis for a solution. So the issue you raised is real and significant, and will be faced by any vendor who is using a v1 draft archetype in an operational system. Adopting the new naming/numbering system will solve the problem going forward but the question remains about how to ameliorate the problem now There are, I think, three approaches: 1. Implementors accept that the use of draft archetypes was that 'own risk' and that they will have to manage the transition from draft to published, which will entail making changes to program code or query statements which refer to draft archetypes. i.e. rename lab_test.v1 to lab_test.v1-unstable or lab_test.v0. This is clearly a major pain (as Sebastian has said) but vendors we have spoken to so far have indicate that they are prepared to do this. Note that it will not have to be done as a batch, only when the system need to use each published v1 archetype, rather than the draft version. 2. Implementers rely on the new metadata that will be introduced when we publish archetypes from now on. This will include the original namespace and an optional Unique ID which can be used internally in the place of the current archetypeId. So the draft archetypeId reference in the data would be left unchanged as: openEHR-EHR-OBSERVATION.lab_test.v1 and any data captured using the published archetype would be labelled in the data (and any associated queries) as org.openehr::openEHR-EHR-OBSERVATION.lab_test.v1.0.0 or 123453446rhtytyyu.1.0.0 if you prefer When this published v1 archetype needs to go back into review it gets labelled as org.openehr::openEHR-EHR-OBSERVATION.lab_test.v1.0.1-unstable+build.e34dgtj67856 or using the uid - 123rhturytu55634567.v.1.0.1-unstable+build.e34dgtj67856 It is up to vendors to decide just how much of that mouthful to record in data and queries but if you are going to use unstable archetypes in data that is the only unequivocal method of knowing exactly which specific version of the archetype you are dealing with. I doubt that carrying the build is really necessary but knowing that this is v1.0.1-unstable is important, and resolves the problem that we all face right now. 3. The final option is that in CKM publication we bend the rules and go straight from V1 drafts to V2. We have discussed this as an editorial team and are not keen on the idea because it is a bit confusing for our clinical reviewer audience. If I was implementor I would go for option 2. At some point very soon I am going to have to get to grips with the need to identify namespaced and unstable archetypes in data. I don't have to upgrade to the new published archetypes right away, or as a bulk process but when I do so it makes sense at that point to be able to handle the kind of extended archetype naming that is proposed. Sorry that this was a bit of a tome. This ends up being a pretty complicated subject and part of the reason it took so long to figure out! We really need feedback. Everyone feel free to pitch in and argue Ian --- ## Post #52 by @thomas.beale Probably a side issue from Ian's main points, but.... I think that at the system interface (i.e. in any web service interfaces), we should stick to - thomas --- ## Post #53 by @ian.mcnicoll Hi Thomas, I agree. I would see the uid as being a reasonable option inside systems but the multi-axial Id is what should be exposed externally. The use of the new scheme is going to make it much easier for tooling to adapt to working with the different levels of version control that are required as an archetype goes through the development cycle, so even if system implementers decide not to use unstable archetypes, tooling definitely will, with a necessity to handle some of the inevitable dependencies in slot-filling etc. At the moment this is done by using the archetype MD5 hash in the archetype to ensure that the parent container is referring to exactly the correct version of the archetype (which can get very complex in an archetype dev environment with multiple iterations). This works but is a pretty blunt tool which can be over-sensitive to what we consider to be minor changes as editors. The new system should allow us to work fairly loosely while the archetype is in turmoil i.e only check that we are using the correct major version, then gradually tighten the constraints as it reaches maturity prior to publication. You see similar arrangements in package managers like RubyGems and NPM, and having good alignment with something like semver should allow us to make use of some of the open source code underpinning these tools. We are often accused (unfairly) of using non-standard technologies, and I think this is one area where sticking with a de-facto standard will pay dividends with the next version of tooling. Ian --- ## Post #54 by @ian.mcnicoll Hi Bert, I agree that the V is redundant but if we drop it now we just give everyone a headache, particularly the tooling people. However, it would also offer a different solution to Sebastian Ionescu's problem. re idfferentiating i.e a lab_test.V1 archetype would be quite clearly a 'legacy' archetype as opposed to lab_test.1.0.0. We would need to consider the downstream impact but .. hmmmm ? Ian --- ## Post #55 by @system My main objection against MLHIM was always that it had UUID's as element-names. For a programmer this is not very nice. Bert --- ## Post #56 by @system I think, the "v" just looks silly, it is not very important if you keep it or not\. It makes a better impression if you remove it\. But anyway, I think maintaining a legacy\-versioning system for some years besides the new system gives you more freedom to do it right\. How would that look like? Maybe in CKM, having a naming tool in which people can choose the versioning system, old or new, when they download or look at an archetype\. Having the default, of course on the new system\. I would incorporate also an automatich versioning system, that every time an archetype changes, at least the path\-number increments\. You don't want that situation from the "drafts" anymore\. Bert --- ## Post #57 by @system That's exactly what I was thinking at first. If maintaining the "v" is just a matter os taste, removing it can be a way of better differentiating the old "v1" archetypes from the new "1.0.0". But then I realized that "v1" it already syntactically different from "v1.0.0"... --- ## Post #58 by @system > > I would incorporate also an automatich versioning system, that every time > an archetype changes, at least the path\-number increments\. You don't want > that situation from the "drafts" anymore\. > > Bert > That is something we have also thought about to incorporate some day in LinkEHR Editor \(I think this is more a responsibility of the archetype editors rather that the archetype management systems\)\. The idea is to force the users to, at least, increment the PATCH number of the archetype if it is modified in the editor\. But we also know by experience that many times people don't like to be forced to do things in some way, even if it is mandated by the specifications\. So when all these changes come to the tools, an education effort will also be needed\. David --- ## Post #59 by @system Some compiler environments, like Delphi, automatically increment version-numbers, but it is possible to set it off. To really annoy people, you can refuse to do a save, and force a "save as" with an incremented patch-number, also in the internal id. But in fact, this is all legacy-thinking. The best solution is to decouple the version from the archetypeId. And also decouple the file and filename from the archetypeId. People are responsible for overwriting their documents in Word, or save a backup, if that is their choice. The same can go for the archetype-editors. Ask people to give it a name, any name they want, give them responsibility. Then it isn't your problem anymore. Less technical people think very strange about archetypes. They think that an archetype is a file. But in most kernels, I guess, it is not a file, but something in a database. We must intuitive learn people that archetypes are not files, are not ADL, but can also be JSON or XML, or even a relational model conform AOM. We must learn them that a file is only a way an archetype can occur. It is the file-metaphor which causes so much trouble. Maybe an archetype-editor should not save files at all, but maintain a local database, or connect to a company-server if appropriate, and if needed, in some cases, export it to a file. It would give unexpected features if an archetype editor would store archetypes in relational databases according the AOM-model. It would be possible to have a collections of archetype-snippets to copy from, to have repositories of CComplexObjects. Hmmm, let's see, I need an element with a DvDate, I have three kinds, which one do I take..... hmmm, I also need an medication-cluster, I have 7 types, yes, this looks most suitable. Remember, we tell all the customers about Lego-bricks. Business opportunities. Quick call my patent-lawyer. ;-) Bert --- ## Post #60 by @system You can also, when handling files, eat the previous version and save the archetype with the new version, Except when you do a "save as", than it gives responsibility\. --- ## Post #61 by @system Hi The thing is that we are making unstable changes in between which may even be incompatible changes which turn out to be not something you want to publish in the end (after e.g. Reviewing)... You cannot then just increment the patch, it would be insufficient and too much at the same time, depending on your point of view. Instead we propose a unique build id that changes every time, but which does not say anything about the nature of the change or the stability of the archetype itself. But it enables you to uniquely identify it. For each revision that is published(!) we propose exactly what you are saying - patch to be increased at least, more as required, semi/automatically. Sebastian --- ## Post #62 by @system There were companies which have a four\-number version\-system\. The last number was the build number, saying: We don't know what has changed or if it has changed, but it was build again\. After changing one of the other numbers, the build number will be set to zero again\. I worked with such a system, but it is a long time ago, a very long time ago\. They had a fantastic application in shell\-scripts handling all these things\. In that time, we programmed in "vi"\. We used Lint to check if we followed the company\-conventions as obligatory comments after variable declarations, etc\. A build was done every night, it took hours, there was already continuous integration\. We had a magician as system\-enabler\. Yeah yeah, those were the days my friend, we'd sing and dance \.\.\. \.\. \.\. More informative would be an ISO date\_time string\. Now, archetypes are not build, so that doesn't work, or you regard "save" as build\. Maybe that is the idea, having besides a Semver version, an extension with that date/time string\. On the other hand, information can become conflicting\. The version says it has not change, but the date\-time string tells me something else, what do I do? Back to work, I should say\. Sorry for this intermezzo\. This discussion brings up memories\. Bert --- ## Post #63 by @yampeku We already had that kind of premade patterns implemented in the editor\. You can even start creating an archetype with a pattern\. But that's got nothing to do with versioning ;D --- ## Post #64 by @thomas.beale All - please read my other post where I included some of the AOM spec, showing that the 'identifier' is actually multiple data parts, and the string 'ids' are computed. Something called an 'interface_id' is one of those things; that's just the multi-axial id with only the major version number, e.g. org.openehr::openEHR-EHR-CLUSTER.prescription.v1 This 'id' includes the major version number so that archetypes with breaking changes with respect to each other are treated as different archetypes, operationally. In the design environment, tools know that xxx.v1 and xxx.v2 are related. But that doesn't hold in the runtime environment. Filename is irrelevant, and has been freely choosable for 5-10 years in all archetype modelling tools that I know of. - thomas --- ## Post #65 by @system Except from CKM, it offers, when I click "Export Archetype \(ADL\)" a file named after the archetypeId with extension ADL or XML, if I click on the other\. Bert --- ## Post #66 by @ian.mcnicoll Hi Bert, I agree with a lot of what you are saying here. The important bit is the AOM not the physical instantiation and I hope that the development of AML (Archetype Modelling Language) the UML extension that is being developed by our CIMI colleagues with guidance from Thomas, will help cement the idea that ADL is only one kind of representation. Having said that, as a modeller, working with a wide variety of clients, the text file paradigm is very helpful. It means I can use industry standard approaches such a git/svn etc. It means I can pass the files to colleagues easily. I think it is interesting that the distributed governance approach required by open source environments has if anything, cemented the text file as the universal sharing format. In those terms I think we need to regard each archetype as a tiny software library package, rather than a single file. I completely agree that file names should not ever be regarded as the source of truth in terms of naming/numbering but having a filename which matches the internalID (or at least does not conflict) does help avoiding errors in practical authoring environments. I am very interested in harnessing the power of git to make archetype authoring/production environments easier to handle for people who are working with multiple projects and I think this will lead to an interesting discussion about filenaming / branching / tagging approaches. Perhaps something that is a mix of the archetypeID, a bit more like the SNOMED CT Fully specified Name and a more human narrative might be helpful. e.g. "Systemic Blood Pressure (Observation).1.0.0.json" I think this should be framed in terms of guidance, rather then fixed in the specifications, with a lot of optionality e.g re including version numbers. In some cases this can be helpful, in others not. Ian --- ## Post #67 by @sebastian.iancu Yes, that's what I wanted to hear: that regression or renaming CKM archetypes is potentially problematic for vendors already implementing openEHR in their systems. This topic is not only about archetypes (on CKM or not) but also about (existing) data using them. Indeed using 'draft' archetype is a risk we take and we'll find solutions when their are published. My objection was only against having v0 after we already had v1 - it is not logical. sounds good agree too For me this options would be the 'normal' one. As I said, I cannot think in terms of draft=0 and publish=1, so why is so much resistance against v>1?! I can imagine the 'confusion', but I guess is a matter of 'getting accustomed to'; and again ... how will they feel when they will have to re-publish an archetype and that will become version 2.0.0 according to semver? At first sight it sounds good, but I have to investigate a bit more to get a final position about this. It is still not very clear for me if you want rm1.0.2 adl1.4 to be able to coop with new ecosystem, or all these are intended to be used only by future specification releases. --- ## Post #68 by @system Sorry for my late reaction, I was very busy with outdoor sports events, I hardly did see a computer, which is very special for me. > Having said that, as a modeller, working with a wide variety of clients, the text file paradigm is very helpful. It means I can use industry standard approaches such a git/svn etc. It means I can pass the files to colleagues easily. I think it is interesting that the by the way, I discovered that it is hard to link directly to on archetype in CKM, maybe I am doing something wrong. But it would be very handy to communicate archetypes, inclusive connection to other tooling like mind maps, etc. I don't think git/svn offers some useful functionality in this context, having already a good versioning system. But maybe there is something I overlook. There are some disadvantages to the file-paradigm, that is, why I guess you keep on needing the "v", to point out where the versionnumbering starts, so software can handle it. It is of course because Windows as only OS does not allow a colon as legal character for a file name, so you need the "v". And we are used to having the version in the file name. The namespace is separated from the archetypeId by a colon. I think that is a good thing, the namespace should not be part of the content-indicating part of the archetypeId. So should the version. But I already mentioned that. The naming of the file, the tooling should be helpful. There are several ways to be helpful, this should be decided by the tool builders. In CKM, it is, because the archetype-download is under a button! it is not possible to do "save as", we have the name CKM offers. So there is a file name enforced, and because CKM is often the starting source from where an archetype enters a company-network, this name remains. This encourages the file paradigm, which is in fact disadvantageous. So to do what you advertise, discouraging the file paradigm, I hope you agree those two issues in CKM, possibility to link directly to an archetype, and possibility to do a "save as" when saving an archetype from CKM. Thanks Bert --- ## Post #69 by @system Bert, you can always go to the Share With Colleague tab for an archetype (or other resource) and you will see the direct link for it. You can also select an action (e.g. go to the mindmap directly or the discussion page). There is also a webservice to get the archetypes directly. If you want to go by the archetype id (which might change of course, pre-publication), you can also use e.g. For the browsers I know at least, this is a setting of the browser. You can select if you want the browser to save downloads immediately to a pre-defined download folder or save it under a folder/name of your choice. Depending on the browser, this is somewhere under settings, e.g. Chrome: Under setting, go to "show advanced settings" and then to the "Downloads" section. The option is called something like: "Ask where to save each file before downloading" I am fairly confident that if we wouldn't suggest anything there as a filename that people would complain as well. Sebastian --- ## Post #70 by @system very helpful. To bad it does not show up in the URL, but that is indeed a common issue with web-software. My browser does this when a simple GET always, or it can display it, or when it can't, it offers to save as. And thereby, in a simple GET, I can use my right mouse-click to "save as"-it. Here the right mouse click does not work, because it is not a link but a form-button. In this construction, you can only click it, and before that you must reconfigure the browser, which may be a problem with other web-software. So I would prefer a simple GET-link instead of a form-button which executes an unknown action. Anyway, this should somehow be more clear, because I am a quite experienced computer-user, and I didn't know how to handle this. Anyway, both questions solved. I am also sure too people would complain if you did not offer a filename, but when you offer a filename, it gives responsibility. And in that case, the "v" inside the filename is not a problem, because the version is sticked to the ID, but it is only a filename. In the internal ArchetypeID, which is authoritative, I would prefer not to see the "v", because it is an unnecessary addition, and can be confusing because the "v" is not normal used in semver-version-counting, and it causes extra string parsing. I think, the reason for the "v" in the internal authoritative ID is inherited by the filename restrictions from Windows. Thanks very much anyway, very helpful. Bert --- ## Post #71 by @ian.mcnicoll Hi Bert, While I understand your argument that 'archetype as file' can confuse people, from an archetype author perspective, it is really helpful to be able to handle archetypes as files. For you as a developer though, I completely agree that you are going to manage the operationalised 'compiled' versions of these files completely differently. As Sebastian has said, I would like any tools that offer to export an archetype as a file to offer some sort of sensible name, but perhaps we can think of an alternate (optional) file naming scheme that is clearly different from the archetypeId I would suggest the Clinical Concept Name ("Indirect oximetry") The Class "(observation)" to help disambiguate similar concept names from different classes. e.g "medication" action vs "medication" instruction (same idea as SNOMED CT FSN) The major revsion part of the revision string "Indirect oximetry (observation).v2.adl" This is pretty close to the file naming scheme that I am using for templates. Definitely optional and not intended to be parsable. Ian --- ## Post #72 by @system Certainly good deal, Ian, I agree, because the archetypeId is very often a compromise between one side : \[short\-length, funny underscores, dashes and periods\] and on the other side: \[trying to communicate something about the archetype\]\. People should not be confronted with such technically, strict syntaxly formed strings\. I am sure very few people can write an archetypeId down without errors, even when dictated, maybe less then five\-hundred worldwide\. And maybe less people understand what is meant here: openEHR\-EHR\-CLUSTER\.amount\-range\.v1, while this is perfectly understood by ten thousands: Amount of medication as a range Bert Ian McNicoll schreef op 6\-10\-2014 13:06: --- ## Post #73 by @Bostjan_Lah Hi everybody, sorry for not jumping in this earlier\.\.\. We \(Marand\) are looking at this from a vendor point of view much like Sebastian from Code24\. We have quite a bit of existing data, apps with AQLs, etc\. Now if I understood everything correctly we have two ways: \- existing archetypes would initially change from v1 to v0\.\* something and once published would become v1\.0\.0 \- existing archetypes would initially change from v1 to v1\.0\.0\-unstable \(or \-alpha \- to be decided\) and once published would become v1\.0\.0 I have no problem with either style and think both would work equally well\. But this is not the only change \- we would also add namespace to ids so final \(published\) full archetype id would be: org\.openehr::openEHR\-EHR\-OBSERVATION\.lab\_test\.v1\.0\.0 which includes namespace as well as new full version number\. So this makes change anyway much larger and needs to be tackled no matter if versions in CKM now go to v0 or to v1\*\-alpha\. Even though archetype id will in fact not change in ADL1\.4, other\_details will carry all the rest and we can already start using it\. The question is \- does it make sense to start using it while our whole stack is still on ADL1\.4 as it affects quite a few things: \- existing stored RM data \- RM paths \- this might be in AQLs or other tools that use such paths I would think this is too much hassle and would probably change to new versioning only when we also support ADL2\. The only danger I see with this is that we'd suddenly have existing archetype ids in the system with openEHR\-EHR\-OBSERVATION\.lab\_test\.v1 which in CKM might be completely different due to them going though the release process \(back to v0\* or v1\.\.\.\-unstable\) and finally becoming org\.openehr::openEHR\-EHR\-OBSERVATION\.lab\_test\.v1\.0\.0\. This case would indeed be solved by releasing them as v2\.0\.0 instead of v1\.0\.0 \- perhaps this can be on case\-by\-case basis \- I assume not all archetypes in the sprint will change in an incompatible way? Best regards, --- ## Post #74 by @system Hi Thomas Beale, > openEHR\-EHR\-ADMIN\_ENTRY\.encounter\.v1 => org\.openEHR::openEHR\-EHR\-ADMIN\_ENTRY\.encounter\.v0\.0\.1 => > review & changes => org\.openEHR::openEHR\-EHR\-ADMIN\_ENTRY\.encounter\.v1\.0\.0 Would file name nomenclature be changed? There is no spec for file name of archetype, but archetype ids have been assigned to file names\. Whereas, : is not available for file name in Windows OS \(and old Mac OS\)\. Shinji --- ## Post #75 by @thomas.beale well that's normal \- that's on download \- the file has to be called something ;\-\) \- thomas --- ## Post #76 by @thomas.beale well, as mentioned before, filenames don't matter, but of course when a tool generates a file, it should use an obvious name, something related to the id\. And you are right \- ':' won't work on Windows \(we'll never stop cursing the stupid Windows directory and file\-naming will we\.\.\.\.\)\. So it will need to be something else, maybe just using the '\-' character\. So for that reason, we had better add a file\-system friendly variant of the full id\.\.\. I'll repeat to make it very clear to everyone: tools shouldn't care what the filenames, are, they're only there for humans to understand, e\.g\. if emailing a file manually\. Tools should all do what the AE, TD and AWB do today: look in a configured directory \(tree\) for \.adl or \.adls files, and read the first couple of non\-comment lines to get the meta\-data\. In the AWB at least I do this in a 'fast parse' phase, with a dumb mini\-parser that reads file headers\. It never looks at the file names at all \- every filename that matches the regex '\.\*\\\.adl' or '\.\*\\\.adls' is matched\. \- thomas --- ## Post #77 by @system Thank you for kind explanation\. I was afraid about conflict of file name and file name conversion between OSs, but it looks no matter\. Shinji --- ## Post #78 by @ian.mcnicoll Hi Shinji, It is a fair question. I do think Bert makes a good case for moving away from filenames that are a copy of the archetypeId, and I also think that any file naming patterns should be advisory rather than compulsory. I don't think I would want to carry the namespace in a human readable file name. Ian --- ## Post #79 by @pablo Hi all, also arriving a little late, but... IMO v0 is a clear way of identifying unstable items, so I prefer that. Tooling might need to change anyway to have a better versioning support. E.g. the only way I found to change the version of an archetype in AE is by doing "Save as" and then change the name of the file. As said, the file name is meaningless. IMO the AE needs to have a "Create a new version of this archetype" functionality somewhere, as it has to create a specialization. Also, if there are changes for names/ids of current archetypes, I would propose to publish the mappings between old/new names and ids, so anyone can update their systems with ease. Without this, changes might "break" some systems. --- ## Post #80 by @Heath_Frankel3 I completely agree with this, The number one priority is that all existing clinical data using archetypes published in CKM for the last 2\-5 years is not Invalidated by this process\. I understand that it was use at your own risk but surely vendors that have taken the risk to be early adopters get some support by the foundation\. I think we need to keep all archetypes in CKM as they are unless there is evidence that no one is using a particular archetype\. They must be treated with the same status of published as new ones, they have passed the test of time and more importantly the test of implementation\. I see no problem with starting with v2 for the next iteration\. Regards Heath --- ## Post #81 by @system I also agree on this\. It is a good idea to decide the versioning from Archetype to Archetype\. If there are no need for breaking changes in the Archetype then the version should not be altered\. If some of the archetypes from a clinical point of view must be changed in a not backward compatible way then the Archetype should be either a\) moved to a new version \(v2\) or b\) if the changes are very large moved to a completely new Archetype\. As many have said it is use at own risk when using Archetypes that is not approved\. Said that , I think it is important to show that openEHR Archetypes is a safe choice for the long term\. This is why we should not change naming and versioning without very good reasons\. \+1 for the proposal from Marand v/ Bostjan :\-\) Vennlig hilsen Bjørn Næss Product Owner DIPS ASA Mobil \+47 93 43 29 10 --- ## Post #82 by @ian.mcnicoll Thanks for all the input and feedback. We will quickly put forward a proposed way ahead and see if we can get reasonable consensus. Ian Heather Sebastian Thomas --- **Canonical:** https://discourse.openehr.org/t/archetype-naming-proposals-do-we-need-v0/15726 **Original content:** https://discourse.openehr.org/t/archetype-naming-proposals-do-we-need-v0/15726