What's allowed in FOLDER.items

Currently FOLDER.items is a List<VERSIONED_OBJECT>, which allows COMPOSITION, EHR_STATUS and FOLDER.

See: Common Information Model

Shouldn’t the spec be constrained to List<VERSIONED_COMPOSITION>?

I guess what raises red flags for me is that FOLDER already has a List, so having VERSIONED_FOLDER instances in FOLDER.items seems strange.

Also the possibility of having EHR_STATUS in the FOLDERS seems strange, unless there is a clear use case for that.

Any comments on this?

1 Like

Folders are part of common IM, so besides Compositions might be possible to have also Party items (by refs).
On the other hand It could be a design choice what would be stored there in items, does not feals right to constrain it in the specs. In any case, they are object refs.

Folder.items is object_ref but constrained to versioned_object, which could be any of versioned_composition, versioned_folder or versioned_ehr_status. Not sure on what happens at the demographic model.

I’m not following the rest of your comment about the common package.

Just to be precise, FOLDER.items is of type List<OBJECT_REF> (see here in spec).

Normally, it should be references to VERSIONED_COMPOSITION, that’s true. There’s no way to specify that properly in UML unless we introduce more subtypes of OBJECT_REF.

Well, no-one should do this, for sanity :wink:

Or this…!

1 Like

Yes, I tried to represent what is in the specs: OBJECT_REF with target VERSIONED_OBJECT.

See the UML here Common Information Model

The current representation could have target VERSIONED_COMPOSITION instead of VERSIONED_OBJECT.

The issue is what the specs allow, more than what’s common sense. I couldn’t find something that says “ONLY this is allowed” or “that is NOT allowed”.

Perhaps I’m repeating myself, but I need to express my concerns here.
Those items are not only refs of Versioned_compositions. We (at Code24) took it as was stated in specs for many years already, any kind of OBJECT_REF; in practice we use refs of VERSIONED_COMPOSITIONs as well as VERSIONs. We’ve also used VERSIONED_PARTY in our Demographics repository, although nowadays we have another alternative solution. My concern is about production data for more than 6y. For us any restriction/constraint added now in the spec will be a breaking change …and I don’t quite see the added value of such change.
I would see as “unusual” any use of refs other than VERSIONED_COMPOSITION or its VERSIONs, but to forbid it - it seems a step to far.

Thanks Sebastian, I’m not really proposing any changes, just trying to check what is valid or invalid, my goal is to clarify all this so we can create a better conformance test suite.

Your feedback about implementation cases is exactly what we need to figure out the exact rules we might include later, or even state: “this is open to the implementation”, which is in fact a specific rule that enables to support anything there.

For instance, if I create a test case where the refs in FOLDER.items can target any LOCATABLE, I will quickly find many of those refs might not be supported by current implementations, and we need to know if that is valid or invalid in terms of the spec, so we can assure “this is compliant” or “this is not compliant”., since for compliance, even though we can have optional areas, we can’t say “don’t know if this complies or not”.


Yes, I think this is right - we need to document ‘recommended’ uses clearly. Code24’s original use (the one that creates a kind of double-level versioning) is outside our original intent (as we discussed a lot during previous f2f meetings!), but technically it is just a different interpretation of the same spec, and that we (I…) had not described the intended use of the structures clearly enough.

So I think we need to improve the documentation, and for conformance testing, this would be an instance where you test ‘recommended’ usages of the model, and don’t worry about ‘off-label’ uses except for some specific product.

I think we are forgetting about the spec versioning. I mean: Code24 implementation is correct in terms of the version of the spec they picked up to implement. If we correct this in the future, by adding constraints, recommendations, etc., the new version will solve those issues for the future, and the current implementation of Code24 will still be valid against a previous version of the spec. If they want to migrate things to implement the newer version, some refactoring will be needed, but this is will happen to any implementer! For instance, EHRServer is still v1.0.2 only :slight_smile: and I plan to implement 1.0.4 when some of the infrastructure components are also updated.

Actually, the spec of that has not changed for 15y (we added an attribute to FOLDER more recently). Here’s 1.0.2.


The idea was always just to maintain references to VERSIONED_OBJECTs (representing logical COMPOSITIONs, each with all its versions).

However, the presence of VERSIONED_FOLDER probably made it look as if the OBJECT_REFs were meant to point to VERSIONED_FOLDERs rather than just VERSIONED_COMPOSITIONs. VERSIONED_FOLDER is just the type of EHR.directory, but not the type of anything inside it.

This more modern diagram shows the intention of FOLDERs: each one just points to a collection of VERSIONED_COMPOSITIONs, and also has more FOLDERs beneath.

My memory is (@sebastian.iancu will correct me) that Code24 used the FOLDER.items link to also point to VERSIONED_OBJECTs containing FOLDERs, i.e. introducing versioning of each FOLDER subtree.

The original design intention what just that the whole directory, i.e. the whole tree, is versioned. Within each version is a FOLDER hierarchy, and those OBJECT_REFs pointing to VERSIONED_COMPOSITIONs.

Code24’s interpretation (if I have it right) is not technically incorrect, it just wasn’t the expected use of the model - it’s a more complicated structure. And we didn’t make it that obvious I guess, because there was no detailed explanation in the directory package (Common IM)…

1 Like

Constraining type of refs would be a restrictive change. Assuming that we will release such change of RM, not only that implementation application logic has to be changed (if something else other then VERSIONED_COMPOSITION was used), but also legacy data will not be compliant anymore with RM specs. Therefore I see this potential change of the specs as a breaking change, part of major release (of course has to be properly analyzed and confirmed in SEC).

Agreed - I don’t think we should change the technical spec, just improve the documentation.

Our creative interpretation was a necessity after working for about 2-3y with EHR.directory to support episodes of care, and care plan in mental care. It proven to be not suitable enough for our use-case, too much overhead data caused be continuously versioning the tree, which sometimes referred to thousands of compositions of one EHR. Our solution was to work with multiple subtrees (versioned) and to bind them virtually in the directory (which acts also as a view) on the application level, whenever the EHR above is opened. It might not be what exactly what the specs textually describes, but it is a valid use case as long as we accept to let the FOLDER.items refs point to VERSIONED_FOLDER also (which was supported by specs). This is the way we used folders for the last 5-6y.

This is now better supported by RM Release-1.1, and we no longer need to bind together subtrees into the main directory, as those subtree are also reachable individually.

However, the type of those OBJECT_REF would be good to keep it open. At Code24 we not only refer to latest version of a Composition, but also to a specific version. This can be done by properly setting that attribute. And who knows, there might be future needs to even refer to other types of non-versioned openEHR objects, like GDL/TP - I don’t know for sure, just thinking out of the box for now…

Yes - probably a differential versioning representation would be needed to make this efficient.

Maybe we should just describe this in more detail, with diags in the specs as well?

The only problem though, with multiple uses of the same structure is that they tend to be non-interoperable, e.g. between different vendor systems. But maybe this is one for which we need different flavours?

1 Like