# ADL versions again

**Category:** [Implementers (archive)](https://discourse.openehr.org/c/implementers-archive/158)
**Created:** 2006-05-09 08:43 UTC
**Views:** 19
**Replies:** 13
**URL:** https://discourse.openehr.org/t/adl-versions-again/14534

---

## Post #1 by @system

Hi

I am looking at
http://svn.openehr.org/knowledge/archetypes/dev/index.html

I see a lot of archtypes, very interesting\. Very good is that it is possible to open them in colored view, which makes them "very" readable, as far as an archetype can be readable\.

I am reading the docs, and probably it must be clear, but I can't find it\.

So please allow me some more stupid questions, so that I can go on with my work\.
I try to put my questions in such a way that answers can be short

Thanks in advance\.

Question 1:
Which archetype version is the current version, this means, supported by all the sourcecode on your website\.

Question 1a:
Specially I would like to know it for the Java\-code, I guess Rong can tell me this\.
I could have emailed him personally for this, but maybe one or two readers of this list also did not find the information\.

Question 1b:
But I also want to know for the rest of the code\.

I mentioned the URL in the top of this email, and I read in the docs, that since ADL version 1\.2 there is an optionally possibility to mark an ADL\-file with a version\-number\. This is not always done\.

Question 3:
Why is that, is it backwards compatible, the ADL\-version

Question 4:
Which version do the ADL\-files have which are linked on this URL \(top of this email\)
I guess I can find out myself by reading all versions docs, and analyse those files, but that is hardly to do for a newbie

Question\(s\) 5
Why are ADL 1\.3 and ADL 2\.0 well documented\. Is it because both are still important, ADL 1\.3 as being the current version of ADL 1?
Does this mean that ADL 1\.2 and 1\.1 are obsoleet?
Does this also mean that ADL 1 \(1\.3\) is not obsoleet?
Does this mean that ADL 1 still is necessary when I want to work with openehr, and that I can forget about ADL2 for this moment, maybe something for next year?

Question 6
Well, I could ask some more, but maybe I give it a break here, I do not want to look greedy\.

Thanks
Bert

---

## Post #2 by @rong.chen

Bert Verhees wrote:
> Hi
>
> I am looking at
> http://svn.openehr.org/knowledge/archetypes/dev/index.html
>
> I see a lot of archtypes, very interesting\. Very good is that it is possible to open them in colored view, which makes them "very" readable, as far as an archetype can be readable\.
>
> I am reading the docs, and probably it must be clear, but I can't find it\.
>
> So please allow me some more stupid questions, so that I can go on with my work\.
> I try to put my questions in such a way that answers can be short
>
> Thanks in advance\.
>
> Question 1:
> Which archetype version is the current version, this means, supported by all the sourcecode on your website\.
>
> Question 1a:
> Specially I would like to know it for the Java\-code, I guess Rong can tell me this\.
> I could have emailed him personally for this, but maybe one or two readers of this list also did not find the information\.

Hi Bert,

About the Java ADL parser, it's based on ADL 1\.2 specification originally and is being updated according to the latest \(1\.4\) specs\. You can find more info in readme\.txt in the root directory of the parser project\.

Currently 36 out of total 46 EHR archetypes from the openEHR archetypes repository \(http://svn.openehr.org/knowledge/archetypes/dev/adl/openehr/ehr/) are parsed correctly\. We are working on the update of both the parser and the kernel right now\. Some of the archetypes should be adjusted as well\.

Cheers,
Rong

---

## Post #3 by @thomas.beale

I will answer Bert's questions later,  but for now I should mention that various date/time syntax errors in the openEHR\.org archetypes have been fixed \- mostly either missing 'T' characters and '\.' instead of ',' for the decimal separator\. These have been fixed, and will be uploaded shortly\. We are trying to make all of openEHR properly ISO8601 compliant\.

\- thomas beale

Rong Chen wrote:

---

## Post #4 by @thomas.beale

Bert Verhees wrote:
> Hi
>
> I am looking at
> http://svn.openehr.org/knowledge/archetypes/dev/index.html
>
> I see a lot of archtypes, very interesting\. Very good is that it is possible to open them in colored view, which makes them "very" readable, as far as an archetype can be readable\.
>
> I am reading the docs, and probably it must be clear, but I can't find it\.
>
> So please allow me some more stupid questions, so that I can go on with my work\.
> I try to put my questions in such a way that answers can be short
>
> Thanks in advance\.
>
> Question 1:
> Which archetype version is the current version, this means, supported by all the sourcecode on your website\.

there are two versions specified, ADL 1\.x and ADL 2\.0\. ADL 2\.0 will be the future, but the tools only support 1\.x\. By the time 1\.0\.1 is released, or shortly thereafter, all the tools should be very close to supporting exactly the 1\.4 revision in Release 1\.0\.1\. One further change will be made to ADL 1\.4 which is to make the date/time constrainer patters \(things like "YYYY\-MM\-??", "hh:??:XX" etc\) more closely aligned with ISO8601, on which they were based\. Specifically the 'T' and 'P' characters will be supported in time and duration constraint patterns respectively\.
>
> Question 1a:
> Specially I would like to know it for the Java\-code, I guess Rong can tell me this\.
> I could have emailed him personally for this, but maybe one or two readers of this list also did not find the information\.
>
> Question 1b:
> But I also want to know for the rest of the code\.

The Eiffel code is being upgraded right now for various fixes, and to correctly support the ISO8601 changes, both in the constrainer patterns and in date/time values as well \(e\.g\. when someone puts in a date/time in the meta\-data, or as a fixed or assumed value in the definition section\)\.
>
> I mentioned the URL in the top of this email, and I read in the docs, that since ADL version 1\.2 there is an optionally possibility to mark an ADL\-file with a version\-number\. This is not always done\.
>
> Question 3:
> Why is that, is it backwards compatible, the ADL\-version
>
> Question 4:
> Which version do the ADL\-files have which are linked on this URL \(top of this email\)
> I guess I can find out myself by reading all versions docs, and analyse those files, but that is hardly to do for a newbie

these archetypes are more or less 1\.4\. We are engaged in a testing process right now to make sure they are 100% 1\.4\. One of the fixes to the code is to output the adl\_version marker when saving archetypes\.
>
> Question\(s\) 5
> Why are ADL 1\.3 and ADL 2\.0 well documented\. Is it because both are still important, ADL 1\.3 as being the current version of ADL 1?
> Does this mean that ADL 1\.2 and 1\.1 are obsoleet?
> Does this also mean that ADL 1 \(1\.3\) is not obsoleet?
> Does this mean that ADL 1 still is necessary when I want to work with openehr, and that I can forget about ADL2 for this moment, maybe something for next year?

ADL 1\.3 is the current official version for right now, but 1\.4 will become the official version in  less than 2 weeks\. In terms of tools, everyone is working with 1\.4\. Probably you don't need to worry about it given that you can just use one of the existing parsers to access archetypes in an object form\.\.\.\.

\- thomas

---

## Post #5 by @Sam

Bert

The archetypes on the Ocean website are almost 1.4 and will be in the next week when the parsing issues are resolved. We guarantee that the editor will parse these archetypes in the future so people can proceed with confidence.

I believe that the 1.4 archetypes and 1.0.1 reference model will be *open*EHR for some time. If adl2 has a lot of advantages we may see archetypes transformed to a new syntax, but this is not a priority from the clinical perspective. In fact the need for stability is paramount and something we have been working towards for many years.

As a senior *open*EHR player, it will take a lot to shift me from my stance on stability. These things can always be better, and when there is enough energy and momentum we can move ahead. The 1.1 spec will be out soon which will include all the extract classes - but this will only add to the model, not make anything redundant.

Cheers, Sam

Bert Verhees wrote:

---

## Post #6 by @system

Sam Heard schreef:
> Bert
>
> The archetypes on the Ocean website are almost 1\.4 and will be in the next week when the parsing issues are resolved\. We guarantee that the editor will parse these archetypes in the future so people can proceed with confidence\.
>
> I believe that the 1\.4 archetypes and 1\.0\.1 reference model will be /open/EHR for some time\. If adl2 has a lot of advantages we may see archetypes transformed to a new syntax, but this is not a priority from the clinical perspective\. In fact the need for stability is paramount and something we have been working towards for many years\.

I couldn't agree more\.

I like to see a "freeze" or  even "finalize" as they say in Eiffel, and save that for a version where everything works and works together, and is a complete system\. It really is very annoying to find every day pieces of code which don't even compile\. It spoils so much of my time, and I am working under time\-pressure \(we all are, life is short\)\. And the documentation is sometimes behind, or incomplete, but one can not distinguish that from docs which are up to date\.

But it is all very understandable, the community has worked for many years to achieve this\. They are used to grow, the are used of being a moving target\.

But all the work cannot be done for fun, it has purpose to be used in applications\.

So I suggest following

Like Linux, Linus Torvalds decides, this is a kernel, though it is not perfect, we lable it 2\.6\.14 and it is ready\.

Let someone please do that for OpenEhr, let us consolidate\.

Let us define a point and make a repository where everything belongs to each other, everything compiles \(java, Eiffel\), all the ADL\-files have the right version, all the PDF's are up to date\.

And an applicationbuilder like me can trust that everything belongs together\.

This is really needed to bring OpenEhr to a success\.

Thanks, and I hope these problems will be recopgnized\.

Bert

---

## Post #7 by @thomas.beale

Bert Verhees wrote:
> Sam Heard schreef:
>> Bert
>>
>> The archetypes on the Ocean website are almost 1\.4 and will be in the next week when the parsing issues are resolved\. We guarantee that the editor will parse these archetypes in the future so people can proceed with confidence\.
>>
>> I believe that the 1\.4 archetypes and 1\.0\.1 reference model will be /open/EHR for some time\. If adl2 has a lot of advantages we may see archetypes transformed to a new syntax, but this is not a priority from the clinical perspective\. In fact the need for stability is paramount and something we have been working towards for many years\.
>
> I couldn't agree more\.
>
> I like to see a "freeze" or  even "finalize" as they say in Eiffel, and save that for a version where everything works and works together, and is a complete system\. It really is very annoying to find every day pieces of code which don't even compile\. It spoils so much of my time, and I am working under time\-pressure \(we all are, life is short\)\. And the documentation is sometimes behind, or incomplete, but one can not distinguish that from docs which are up to date\.
>

without trying too hard to make excuses, I will try to offer an explanation:
the openEHR work until end 2005 has been fluid, driving toward Release 1\.0\. As anyone with experience in software will know, in fact you have to get to the release after that to get rid of the little problems\. In our case it will be Release 1\.0\.1, which fixes various annoyances and minor errors in 1\.0\. Release 1\.0\.1 is the baseline for software engineering\. Due to spending most resources on specifications and standards for the last few years, the software is only just becoming solid\.

So the community here I hope will realise that although now is the point in time when software starts to crystallize, we are sitting on some millions of dollars worth of public IP, in the form of \(I think\) pretty good specifications\. Anyone coming in and expecting a completely clean compile, bugfree execution of the software today won't always get it\. But they will within the next few months\. Some might complain that "other open source is better"\. Indeed it is\.\.\.for now, but almost all other open source is in its own non\-interoperable data silos\. Very few other open source efforts could point to design or requirements documents, or know that many others around the world are working with common information models\.

So, yes the "finalise" in the specifications is pretty much there \(i\.e\. the CR rate is now very low, and I believe easily manageable by normal software efforts\); the finalise in baseline software to implement these specifications will occur over the next few months\. \(The actual act of publishing takes many hours of work as well\)\.

Some of us have been working 7 days a week for the last few months to get the specifications and tools close to a completely stable state, but of course we also have to do paid work to survive\. Release 1\.0\.1 we expect to have issued within 2 weeks, but for practical purposes, the documents in the Release 1\.1 candidate area can be used now \(if anyone is wondering, we initially planned to go to Release 1\.1, but decided after making the subversion branch to target 1\.0\.1 first\)\.

People who want to work on the Java and Eiffel efforts in a serious way are welcome to join \- just email me \(Eiffel\) or Rong Chen \(Java\)\. The C\#/\.Net effort will start a little later when Ocean Informatics makes its openEHR C\#\.Net kernel available open source\.

hope this helps\.

\- thomas beale

---

## Post #8 by @system

Please read my reply below
>>> I believe that the 1\.4 archetypes and 1\.0\.1 reference model will be /open/EHR for some time\. If adl2 has a lot of advantages we may see archetypes transformed to a new syntax, but this is not a priority from the clinical perspective\. In fact the need for stability is paramount and something we have been working towards for many years\.
>>
>> I couldn't agree more\.
>>
>> I like to see a "freeze" or  even "finalize" as they say in Eiffel, and save that for a version where everything works and works together, and is a complete system\. It really is very annoying to find every day pieces of code which don't even compile\. It spoils so much of my time, and I am working under time\-pressure \(we all are, life is short\)\. And the documentation is sometimes behind, or incomplete, but one can not distinguish that from docs which are up to date\.
>>
>
> without trying too hard to make excuses, I will try to offer an explanation:
> the openEHR work until end 2005 has been fluid, driving toward Release 1\.0\. As anyone with experience in software will know, in fact you have to get to the release after that to get rid of the little problems\. In our case it will be Release 1\.0\.1, which fixes various annoyances and minor errors in 1\.0\. Release 1\.0\.1 is the baseline for software engineering\. Due to spending most resources on specifications and standards for the last few years, the software is only just becoming solid\.
>
> So the community here I hope will realise that although now is the point in time when software starts to crystallize, we are sitting on some millions of dollars worth of public IP, in the form of \(I think\) pretty good specifications\. Anyone coming in and expecting a completely clean compile, bugfree execution of the software today won't always get it\. But they will within the next few months\. Some might complain that "other open source is better"\. Indeed it is\.\.\.for now, but almost all other open source is in its own non\-interoperable data silos\. Very few other open source efforts could point to design or requirements documents, or know that many others around the world are working with common information models\.
>
> So, yes the "finalise" in the specifications is pretty much there \(i\.e\. the CR rate is now very low, and I believe easily manageable by normal software efforts\); the finalise in baseline software to implement these specifications will occur over the next few months\. \(The actual act of publishing takes many hours of work as well\)\.
>
> Some of us have been working 7 days a week for the last few months to get the specifications and tools close to a completely stable state, but of course we also have to do paid work to survive\. Release 1\.0\.1 we expect to have issued within 2 weeks, but for practical purposes, the documents in the Release 1\.1 candidate area can be used now \(if anyone is wondering, we initially planned to go to Release 1\.1, but decided after making the subversion branch to target 1\.0\.1 first\)\.
>
> People who want to work on the Java and Eiffel efforts in a serious way are welcome to join \- just email me \(Eiffel\) or Rong Chen \(Java\)\. The C\#/\.Net effort will start a little later when Ocean Informatics makes its openEHR C\#\.Net kernel available open source\.

The reasons for my experiences are just as I expected \(hoped\) them to be, it is because of dedication to this job done\.
It is a very good build of specs, and the following code is of highly professional level\.
And I can only express admiration for those people which made this happen\.
It is because of this admiration for the people and the quality of their work that I recommend OpenEhr to investors, even when knowing we will run into problems, because we are early birds\. \(Most of the problems are of the kind, of not being able to follow tight time\-schedules\.\)

I know, I just have to be patient\.

It is not that I want to criticize the project, that I bring up this subject, let me please explain my feelings\.

I was confused about the 1\.0\.1 and 1\.1 release\-naming\. This confusion also came from the fact that the third figure should be used for a bugfix\-release and the second should be used for a minor feature\-release\. \(Errors happen, now I know it is no problem\)
I was assuming there were two developing lines simultaneous, and I was afraid, the next developing line would distrub the actual one, which then could result in published code, that would never be compilable, or compatible, specs which would never be ready\. Already defining a new ADL\-version \(2\.0\) while there is on the same time a 1\.4 planned which should be delivered in two weeks? I wondered, in what stage would the code be at that time, will the documents be ready on time\. or will it something I have to figure out by trial and error? How could I be sure that a moving target would ever stop a split second at a point where I could use it? And how would I know when that split second was there?

Now, afterwards, Thomas and others have explained that the goal is to come to a stable and complete version, my doubts from before seem silly, but isn't that always the case? Many of my previous questions came from the perspective of this doubts\.

Now I know, I just have to wait some time\.
I still have some small questions, but I keep them for the pieces may fall together anyway\.

I know, that involved people, like Thomas, and others, despite of working seven days a week to get this done, offer a lot of time in communications, especially on this mailinglists\. This is good\.  But some communications are hard to find, I must have missed the announcement that 1\.1 should be 1\.0\.1, that there is a ADL 1\.4 on the way, that ADL 1\.4 is the version which works with the kernel 1 \(\.0\.1\)
I also see sometimes there are only minor changes in the different ADL\-versions, which is confusing\. I would expect then, \(again\) the third figure to express the changes, so ADL 1\.0\.1, ADL 1\.0\.4, etc\.
Again this is not a big issue, but can easily bring someone to wrong conclusions\. \(it did with me\)

Still, besides the criticism, one should realize that communication is often very much worse at other open source projects\. Some very good projects find it sufficient to have just a page at sourcefore\. It is not often that projects are so well documented as openehr is\. It is sure that there is a huge amount of time and effort spent in doing this\.

Thanks for the convincing replies
Bert

---

## Post #9 by @thomas.beale

Bert Verhees wrote:
>
> Now I know, I just have to wait some time\.
> I still have some small questions, but I keep them for the pieces may fall together anyway\.

there is quite a lot of code changes being made right now, and the code will get better fast\.
>
> I know, that involved people, like Thomas, and others, despite of working seven days a week to get this done, offer a lot of time in communications, especially on this mailinglists\. This is good\.  But some communications are hard to find, I must have missed the announcement that 1\.1 should be 1\.0\.1, that there is a ADL 1\.4 on the way, that ADL 1\.4 is the version which works with the kernel 1 \(\.0\.1\)

we haven't announced it\. But I had better;\-\) I have just to set up the web page that contains the final list of CRs\.\.\.
> I also see sometimes there are only minor changes in the different ADL\-versions, which is confusing\. I would expect then, \(again\) the third figure to express the changes, so ADL 1\.0\.1, ADL 1\.0\.4, etc\.
> Again this is not a big issue, but can easily bring someone to wrong conclusions\. \(it did with me\)

we didn't do this originally beacuse I used a 2\-part document versioning scheme from British Telecom from years ago when I worked there\. We have been using this scheme for 10 years on GEHR and openEHR documents, and I have been in two minds as to whether to change to a 3\-part one or not \- the problem is that the revision histories in the documents will then have mostly 2\-part numbering, with 3\-part numbering starting at the top\.\.\.\.this might be confusing\.\.\.or not\.
>
> Still, besides the criticism, one should realize that communication is often very much worse at other open source projects\. Some very good projects find it sufficient to have just a page at sourcefore\. It is not often that projects are so well documented as openehr is\. It is sure that there is a huge amount of time and effort spent in doing this\.

well, I am aware that our communications could be a lot better as well, and we really rely on people to provide feedback to help with that \(but also to provide some effort in fixing things\!\)\. Still, the lists seem to be working alright, and  we have created some new mailman lists for project groups, and that is also going well\. We are learning all the time\.\.\.

\- thomas

---

## Post #10 by @Sam

Also worth stressing that 1.1 will, we hope, be only an addition to 1.0.1 - that is it will include the Extract classes and schema. For this reason we will take it to 1.1 as this will give us the opportunity to have a very stable label and release.

Cheers, Sam

Thomas Beale wrote:

---

## Post #11 by @system

>> I also see sometimes there are only minor changes in the different ADL\-versions, which is confusing\. I would expect then, \(again\) the third figure to express the changes, so ADL 1\.0\.1, ADL 1\.0\.4, etc\.
>> Again this is not a big issue, but can easily bring someone to wrong conclusions\. \(it did with me\)
>
> we didn't do this originally beacuse I used a 2\-part document versioning scheme from British Telecom from years ago when I worked there\. We have been using this scheme for 10 years on GEHR and openEHR documents, and I have been in two minds as to whether to change to a 3\-part one or not \- the problem is that the revision histories in the documents will then have mostly 2\-part numbering, with 3\-part numbering starting at the top\.\.\.\.this might be confusing\.\.\.or not\.

The most confusing is the CM documentation in the OpenEhr which in chapter 5\.3 talks about a 3\-digit numbering, and seemed not in line with the common practise\.
The third position is for error corrections and minor additions\.  This seemed to be the case in the ADL versions
The second positions is for siginificant additions which do not break semantics\.

Maybe it is a matter of taste, but I would for clarity prefer the change of the third digit in the ADL versions because the changes are minor, and they belong to kernel 1 \(which is 1\.0\.1\)\. This is now more important because the kernel version changed from 1\.1 tot 1\.0\.1\.
Before I was thinking that there was an ADL version for kernel 1, and one for 1\.1 \(because there was a kernel 1\.1\) and I was afraid, that I head to distinguish four ADL versions, and there were 4  kernels to come \(1\.0 till 1\.4\)\.
A moving target is bad for an implementor like me, but Openehr looked to me like a target with  supersonic speed\.

Now the numbering is more talking for itself, this is a great improvement\.
>>
>> Still, besides the criticism, one should realize that communication is often very much worse at other open source projects\. Some very good projects find it sufficient to have just a page at sourcefore\. It is not often that projects are so well documented as openehr is\. It is sure that there is a huge amount of time and effort spent in doing this\.
>
> well, I am aware that our communications could be a lot better as well, and we really rely on people to provide feedback to help with that \(but also to provide some effort in fixing things\!\)\. Still, the lists seem to be working alright, and  we have created some new mailman lists for project groups, and that is also going well\. We are learning all the time\.\.\.

I notice that many GP or decisionmakers don't give a \.\.\.\. about openehr or how data are stored, and if there is flexibility\. People are damned to always make the same mistakes if not a few take care\.
Therefore, in my opinion, the readers of the documentation are implementors \(mostly technical\), they will \(if it is good\) be touched by the beauty of the system, and they will convince their decisionmakers \(business\) the openehr is to choose for\.

So the technical part of the documentation:
What I miss is  better worked out UML, which would give more easy understanding of how things work\.
I am thinking of use\-cases, sequence\-diagrams, that kind of things\.
A lot of emphasizing in the documentation is towards class/package diagrams, which is also important\.
The accompanying text often is to much in depth, it is difficult to find small pieces of information, one can easily get lost in details, and from there go to other details, and forget the intial question\.
\(
For example, I take one, which is on top of the pile: Support information model
Chapter 1, I skip, nothing there that talks to me, it is only one page, so maybe it is meant to be formal
Chapter 2, Starts with a package diagram and class definitions
Chapter 3, Assumed types, and class definitions,
Chapter\.\.  and so on and on
\)
\(I am not suggesting the community should fix this, because, they do a lot of work already, it could well be done by someone else \(I could volunteer for some things to do, but my English is bad, \(though good enough for understanding \(I am lazy, which is a good habit for a occupied man, like me\)\)\), I think, if someone would pick it up, I would add some assistance\.\)
Explanation on different levels of complexity about \-HOW it happens\-, besides of \-WHAT it is\- would be good\.
\(
for example
Chapter 1\.1: What is the Support package, what is it purpose, why are these classes choosen to be inside this package
Chapter 1\.2: How does it interact inside the system
Chapter 1\.3: How does it interact internally
etc\. go to class level of explanation of the interacts
\)

So, these were my 3 cents

kind regards
Bert Verhees

---

## Post #12 by @thomas.beale

Bert Verhees wrote:
>
> The most confusing is the CM documentation in the OpenEhr which in chapter 5\.3 talks about a 3\-digit numbering, and seemed not in line with the common practise\.
> The third position is for error corrections and minor additions\.  This seemed to be the case in the ADL versions
> The second positions is for siginificant additions which do not break semantics\.

actually the scheme we use in openEHR's own model of versioning is pretty common \- it's a fairly standard way to name branches, using the following scheme:
\- trunk version \(which trunk version?\)
\- branch id \(which branch?\)
\- branch version \(which version on this branch?\)

But this is a version identification scheme for EHR and other content, not for the openEHR specifications themselves\.

> Maybe it is a matter of taste, but I would for clarity prefer the change of the third digit in the ADL versions because the changes are minor, and they belong to kernel 1 \(which is 1\.0\.1\)\. This is now more important because the kernel version changed from 1\.1 tot 1\.0\.1\.

I agree with that\.
> Before I was thinking that there was an ADL version for kernel 1, and one for 1\.1 \(because there was a kernel 1\.1\) and I was afraid, that I head to distinguish four ADL versions, and there were 4  kernels to come \(1\.0 till 1\.4\)\.
> A moving target is bad for an implementor like me, but Openehr looked to me like a target with  supersonic speed\.
>
> Now the numbering is more talking for itself, this is a great improvement\.

I think we probably should go for 3 part numbering on the documents \- we will need to investigate whether this causes any issues, but I don't imagine it will\. I am perfectly happy to live by the major\.submajor\.minor pattern for that\.
>
> So the technical part of the documentation:
> What I miss is  better worked out UML, which would give more easy understanding of how things work\.
> I am thinking of use\-cases, sequence\-diagrams, that kind of things\.

I think we should limit such things to a second tier of documentation \- system / component design documentation, rather than the main specifications, although there may be exceptional areas where we should use these things\.\.\.but I wouldn't want to have to embark on a systematic software system design documentation exercise within the existing documents\.\.\.\.
> A lot of emphasizing in the documentation is towards class/package diagrams, which is also important\.
> The accompanying text often is to much in depth, it is difficult to find small pieces of information, one can easily get lost in details, and from there go to other details, and forget the intial question\.
> \(
> For example, I take one, which is on top of the pile: Support information model
> Chapter 1, I skip, nothing there that talks to me, it is only one page, so maybe it is meant to be formal
> Chapter 2, Starts with a package diagram and class definitions
> Chapter 3, Assumed types, and class definitions,
> Chapter\.\.  and so on and on
> \)

there is a general format common to all documents, but it has to be admitted that the Support IM is a bit of a grab bag of low\-level semantics\.
> \(I am not suggesting the community should fix this, because, they do a lot of work already, it could well be done by someone else \(I could volunteer for some things to do, but my English is bad, \(though good enough for understanding \(I am lazy, which is a good habit for a occupied man, like me\)\)\), I think, if someone would pick it up, I would add some assistance\.\)
> Explanation on different levels of complexity about \-HOW it happens\-, besides of \-WHAT it is\- would be good\.
> \(
> for example
> Chapter 1\.1: What is the Support package, what is it purpose, why are these classes choosen to be inside this package

did you have a look at the Architecture Overview document \(http://svn.openehr.org/specification/BRANCHES/Release-1.1-candidate/publishing/architecture/overview.pdf)? I would hope that people would find overview answers here\. Feedback on this document, like all others, is welcome\.\.\.\.

\- thomas

---

## Post #13 by @system

Thomas Beale schreef:
> Bert Verhees wrote:
>>
>> The most confusing is the CM documentation in the OpenEhr which in chapter 5\.3 talks about a 3\-digit numbering, and seemed not in line with the common practise\.
>> The third position is for error corrections and minor additions\.  This seemed to be the case in the ADL versions
>> The second positions is for siginificant additions which do not break semantics\.
>
> actually the scheme we use in openEHR's own model of versioning is pretty common \- it's a fairly standard way to name branches, using the following scheme:
> \- trunk version \(which trunk version?\)
> \- branch id \(which branch?\)
> \- branch version \(which version on this branch?\)
>
> But this is a version identification scheme for EHR and other content, not for the openEHR specifications themselves\.

I quote from the CM document:
"The purpose of this document is to describe the management of openEHR technical projects in the openEHR technical space  \(as described in the document Introducing OpenEHR\)"
I see in referred document Figure 3 what belongs to Technical Activities: specification projects, implementation projects and delivery activities\.

I don't understand what you mean, I think we are communicating about different subjects\. Please explain\.

>> Maybe it is a matter of taste, but I would for clarity prefer the change of the third digit in the ADL versions because the changes are minor, and they belong to kernel 1 \(which is 1\.0\.1\)\. This is now more important because the kernel version changed from 1\.1 tot 1\.0\.1\.
>
> I agree with that\.
>> Before I was thinking that there was an ADL version for kernel 1, and one for 1\.1 \(because there was a kernel 1\.1\) and I was afraid, that I head to distinguish four ADL versions, and there were 4  kernels to come \(1\.0 till 1\.4\)\.
>> A moving target is bad for an implementor like me, but Openehr looked to me like a target with  supersonic speed\.
>>
>> Now the numbering is more talking for itself, this is a great improvement\.
>
> I think we probably should go for 3 part numbering on the documents \- we will need to investigate whether this causes any issues, but I don't imagine it will\. I am perfectly happy to live by the major\.submajor\.minor pattern for that\.

major\.submajor\.minor is 3 part numbering?
The CM document talks about this, it would be according the specifications

>> So the technical part of the documentation:
>> What I miss is  better worked out UML, which would give more easy understanding of how things work\.
>> I am thinking of use\-cases, sequence\-diagrams, that kind of things\.
>
> I think we should limit such things to a second tier of documentation \- system / component design documentation, rather than the main specifications, although there may be exceptional areas where we should use these things\.\.\.but I wouldn't want to have to embark on a systematic software system design documentation exercise within the existing documents\.\.\.\.

That is possible to position this on another level\. I don't know\.
I find the the system \(schematically\) described as a rather static system, I would like to see it also \(schematically\) described as a dynamical system\.
But maybe I am wrong, while working longer with it the understanding grows\.
When thinking now about it, maybe the documentation is nearly sufficient, it describes almost everything, every detail is explained\. I say almost, not because I found something missing, but just for sure\.

The documentation is purely technically, there could be a second line of documentation which would be more educattional\. Could be handy for newbies
But the real diehards do not need it\.
>> A lot of emphasizing in the documentation is towards class/package diagrams, which is also important\.
>> <snip>
>
> did you have a look at the Architecture Overview document \(http://svn.openehr.org/specification/BRANCHES/Release-1.1-candidate/publishing/architecture/overview.pdf)? I would hope that people would find overview answers here\. Feedback on this document, like all others, is welcome\.\.\.\.

Yes, it was the first document I read, I see now, it was a previous version, 1\.0\.2, so I did not yet read the current 1\.1 version\.
It is a very necessary document\. It explains a lot, it is a kind of educational document, explaining instead of only describing\.

Bert

---

## Post #14 by @thomas.beale

Bert Verhees wrote:
> Thomas Beale schreef:
>> Bert Verhees wrote:
>>>
>>> The most confusing is the CM documentation in the OpenEhr which in chapter 5\.3 talks about a 3\-digit numbering, and seemed not in line with the common practise\.
>>> The third position is for error corrections and minor additions\.  This seemed to be the case in the ADL versions
>>> The second positions is for siginificant additions which do not break semantics\.
>>
>> actually the scheme we use in openEHR's own model of versioning is pretty common \- it's a fairly standard way to name branches, using the following scheme:
>> \- trunk version \(which trunk version?\)
>> \- branch id \(which branch?\)
>> \- branch version \(which version on this branch?\)
>>
>> But this is a version identification scheme for EHR and other content, not for the openEHR specifications themselves\.
>
> I quote from the CM document:
> "The purpose of this document is to describe the management of openEHR technical projects in the openEHR technical space  \(as described in the document Introducing OpenEHR\)"
> I see in referred document Figure 3 what belongs to Technical Activities: specification projects, implementation projects and delivery activities\.
>
> I don't understand what you mean, I think we are communicating about different subjects\. Please explain\.

ok \- you are talking about the CM plan, I was talking about the change\_control package in the Common IM \- sorry about that\.\.\.\.the current definition of the numbering scheme is:

The meaning of a change in each digit is as follows:

    \* \(minor\) 3rd position: used to indicate error corrections and minor
      additions that do not change the semantics\. Thus, Release 1\.0\.2 is
      the second error correction release after Release 1\.0\.
    \* \(sub\-major\) 2nd position: used to indicate significant additions
      that do not change the semantics of the existing part of the
      release\. Release 1\.3 would be the 3rd release containing
      compatible additions to Release 1\.0\.
    \* \(major\) 1st position: used to indicate changes to the semantics or
      large changes\. Release 2\.0 would contain changes incompatible in
      some way with Release 1\.0, most likely requiring software upgrade
      and possibly data migration\.

do you think this should be changed? Note that this is the numbering scheme of releases of the whole of an openEHR project\. Currently, as you have pointed out, we have not followed 3\-part numbering in documents\. But we can change to doing so that for example ADL's next small change release is 1\.4\.1\. And so on\.

> That is possible to position this on another level\. I don't know\.
> I find the the system \(schematically\) described as a rather static system, I would like to see it also \(schematically\) described as a dynamical system\.
> But maybe I am wrong, while working longer with it the understanding grows\.

the openEHR RM specifications try to describe information models and some basic functional characteristics\. It is clearly in the ISO RM/ODP information viewpoint\. We are developing APIs and service models in the computational viewpoint \- these will be more "dynamic" in that they will indicate calling patterns etc\. But we need a base layer of specifications for the information dimension in the e\-Health space \- we cannot afford to mix  too many things in with that\.
> When thinking now about it, maybe the documentation is nearly sufficient, it describes almost everything, every detail is explained\. I say almost, not because I found something missing, but just for sure\.
>
> The documentation is purely technically, there could be a second line of documentation which would be more educattional\. Could be handy for newbies
> But the real diehards do not need it\.

well, as I have said, we are always interested in criticism and feedback of the documents \- for new\-comers, we are no longer the best judges of how well it works\! But we need specific feedback, and also if people want to create some FAQ or other web pages during their own learning process, we will include that in the website\. At this stage, the community needs to see this as collaborative work\.

hope this helps,

\- thomas

---


**Canonical:** https://discourse.openehr.org/t/adl-versions-again/14534
**Original content:** https://discourse.openehr.org/t/adl-versions-again/14534