Add folders:LIST<OBJECT_REF> on EHR


The EHR class have an optional DIRECTORY structure. This is modelled as a reference (object_ref) to a DIRECTORY structure. The DIRECTORY is a package which have a versioned root folder which should contain all the sub_folders.

We are implementing openEHR folders now to support some proprietary folder use-cases. What we want to achieve is to be able to add FOLDERs to a given EHR. Each versioned folder with its hierarchy should be directly under the EHR.

That's why we want to add a new attribute: folders on EHR.

This attribute will then be used in the REST interfaces to add, update and delete FOLDERS.

GET /ehr/{ehrId}/folders/<folderId>

Addition from the November SEC-meeting in Oslo:
One of the references (perhaps the first one in the list?) in the new list folders:LIST<OBJECT_REF> should point to the same folder that the old/current "" points to.


Pieter Bos
August 24, 2020, 10:45 AM

I would agree with 2. of Sebastian.
I think it is easier to understand if there is just one concept of folders, for implementers and for users, and easier to implement with just one attribute, instead of two. Then directory could maybe be marked as the previous way of doing this, or even deprecated?

However, if these are to be separate structures, one for all users and one for specific users, I think the different purpose of these two attributes should be mentioned very clearly in the specification.
An alternative could be to define the first folder as the ‘main’ folder, or perhaps a folder with a specific archetype, or a folder with a specific name?

Thomas Beale
August 24, 2020, 11:05 AM

Well, we have two attributes (having had to add anew one to get the type `List<FOLDER>`), and AFAIK, the directory attribute is in use in some implementations and will therefore exist in some EHR data. So I think deprecating directory might be tricky.

However… I’m not a fan of having special rules for specific items in a container in a general spec i.e. making the first one somehow special, in this case. It means all your code that looks at that property has to have some special logic for the first item, and other logic for the rest. Requiring the first folder to be based on a particular archetype (at the spec level) I think is even more problematic - it’s too restrictive in a generic spec I think.

If we agree that we will have two attributes, it does seem more obvious to me that the directory one be documented for ‘shared use’, i.e. act as a kind of public directory of the EHR, and the folders be documented as a container of specific use FOLDER structures. Here I am assuming that there is a meaningful idea of ‘shared use’ available for any given institution, but not that it is standardised, i.e. the structure under directory is quite likely to be different across institutions.

So the above is my argument for doing it as two distinct properties. If we go this way, I’ll document it more clearly.

I think for proponents of deprecation of directory and/or a ‘special first member' of folders, it needs to be shown more clearly how this won’t be problematic (for existing data/software) / restrictive / confusing etc.

Sebastian Iancu
August 26, 2020, 1:32 PM

Well, as said somewhere above, I don’t remember the exact reasoning behind the statement in question, neither who made it. What I can do is to give my personal opinion about the current state.

Deprecating directory is not needed - it is anyway optional. One of the reason we introduced folders beside directory, was that the directory design was not performant (in real life implementations) for a large set of data and a big sub-tree. The folders may facilitate the same functionality (with a little help), while also adding more features (multiple subtrees, user views and permissions, less redundancy, etc) - but that does not mean that we no need to deprecate directory.

The way the spec is at this time is quite good, only small issue I have is with the ‘additional’ word on EHR.folders. Similar to EHR.compositions, EHR.contributions and EHR.tags I thought we could say that EHR.folders contains list of all folders, implicitly also the directory. I already gave my acceptance, meaning that I’m ok with the current text, if you feel this is better.

Thomas Beale
September 23, 2020, 4:18 PM

Ok all, I have now improved the text in the EHR spec to correspond to the idea discussed 2 weeks ago, and above, which is that ‘directory’ is merely a copy of the first reference in ‘folders’. Could at least , and have a look at the new text and diags - easiest way is to go to section 4.2.5 and just read the text. I also added a new Invariant to the EHR class called ‘Directory_in_folders’.

Sebastian Iancu
September 25, 2020, 12:54 PM

I read them, looks good to me. I've done some small adjustments on text .adoc files in and push them - see
If you think they are good, then please generate the html docs.


Bjørn Næss

Raised By

Bjørn Næss


Affects versions