VERSION commit in XML


I'm using openEHR XMLs to commit VERSIONs to an API.

To have valid XMLs, each version should have a reference to the CONTRIBUTION, so there is a lot of redundancy if many VERSIONs are committed.

<xs:complexType name="VERSION" abstract="true">
<xs:element name="contribution" type="OBJECT_REF"/>

Possible solutions:

1. Change the XSDs to make the VERSION.contribution optional. The commit service provider will create the CONTRIBUTION using the AUDIT_DETAILS. The API will look like:

CommitContribution( HierObjectId ehrId, AuditDetails commitAudit, OriginalVersion[] versions)

2. Make the CONTRIBUTION the committal unit, and that will have all the VERSIONs in, also needs to have the VERSION.contribution optional, because it should also avoid the redundancy of having all the VERSION->CONTRIBUTION relationshiops. The commit service provider will have all the info to link the VERSIONs to the CONTRIBUTION when storing the data. The CONTRIBUTION will also have the AUDIT_DETAILS data. The API will look like:

CommitContribution( HierObjectId ehrId, Contribution contribution)




Heath Frankel
May 18, 2015, 8:45 AM

Hi Pablo,
By suggesting changes to RM due to the way the XSD is represented is implying that you are talking about messaging, XML is messaging.

You answer this yourself when you say in 3 when you say "the VERSION just has a link to its parent CONTRIBUTION". This link is represented in the RM using an OBJECT_REF. Similarly, the RM is indicating that the we don't want CONTRIBUTION to contain the instances of the VERSION, simply a reference.

I was pointing you at the EHR_EXTRACT because this is where you get a model that is intended for exchange and it does have VERSION containment.

I do not support your proposed CR. I believe the RM is correct in the context of its intended use.

Thomas Beale
May 18, 2015, 9:24 AM

What you are proposing is to change the RM from representing the CONTRIBUTION / VERSION associations as explicit id references to in-memory references, i.e. so that the RM represents an in-memory object graph. We would then have to add some further specification to say how this structure was logically represented in id reference form, in order for the structures to be communicable in pieces - for example an EHR Extract or query whose result is just some VERSIONs, but not the creating CONTRIBUTION.

I don't think this is likely to be helpful, if we maintain the RM as a definition of interoperable EHR data, which is it's raison d'etre.

I don't specifically have a problem with there being an XSD representation of CONTRIBUTION etc, but I'd have to agree with Heath, it's probably not the main RM XSD we can to modify, because that represents the standard XML transportable form of openEHR data. But open to ideas on this - I think this is a separate issue.

Pablo Pazos
May 18, 2015, 8:38 PM

@Heath & Thomas, Sorry, I think I'm missing something obvious here, please elaborate as much as you can. I'll try to answer both comments below.


Wasn't my intention to base the RM CR in the XSD CR, it was just a different, but related, idea. Because of that close relationship between the RM and the XSD (I'm talking about CONTRIBUTIONs and VERSIONs in both), I thought this could be a good place to put both CRs, of course I can split that in two if that makes it easy to discuss.

XML can be for anything! messaging, storage, UI, ... you name it. I'm not focused on messaging, but the XML representation of the RM, that I personally use for the SM (commit & query), but others use for persisting data.

Don't think I answered, having a direct reference without the intermediate OBJECT_REF is still not clear why is a problem. What this says "the RM is indicating that the **we don't want CONTRIBUTION to contain the instances of the VERSION**, simply a reference." is the WHAT but not the WHY. I can understand "this is a design decision" because we had X,W,Z problems with the other options. We are talking about improvements based on experience, mine is related to this:

We know that always CONTRUBUTION.versions points to VERSION and VERSION.contribution
points to a CONTRIBUTION. I just think we don't need indirections at the level of specific relationships
like CONTRIBUTION <(1)-> VERSION. If we have more generic items related, so the intermediate
OBJECT_REF class is needed to model that generic relationship, like using a LINK, I wouldn't even propose this CR.

The indirection on the relationship in the RM is reflected on the XSD and the SM, not the contrary (going back to messages vs. model). At the implementation level, for a XML VERSION we need to add an OBJECT_REF tag with the CONTRIBUTION id, even if the SM is creating the CONTRIBUTION after committing that XML (the tags are there but maybe without data, it depends on the implementation).

Your comment about querying for a VERSION that needs to pull the CONTRIBUTION applies: currently if we query for a VERSION, we will get the VERSION.contribution <OBJECT_REF> information. Even if we don't use it, or need it, or can't access the CONTRIBUTION data, since it is mandatory on the RM and the XSD. I don't think it should be mandatory on the SM / XSD.

We can commit anq query XMLs as described above (sending empty tags and retrieving tags that are not needed) without changing anything and will it be valid XML. But IMO this is not a clean solution and it is not clear on the specs (when studying the commit and query processes I couldn't find any info about who sets the CONTRIBUTION, it's uid, it's relationship with each VERSION and when, and which data should be provided on query). IMO we have a great static model but the "dynamic" SM is not so well defined.

I agree on the RM, VERSION.contribution shouldn't be empty, because the RM represents data after commit.


Yes. Just exploring the possibility of removing the indirection level.

Can you elaborate "...have to add some further specification to say..."?

Maybe that's on the SM specs side, and we need to improve those with or without any of my proposed CRs, e.g. say how these objects are related, when and who links them, how to commit, store and query. This is not specifying a ITS but the generic procedures involved on those transactions (I think our specs lack that kind of information: what info to send, who sets which ids, relationships, who creates the CONTRIBUTION, who sets CONTRIB/VERSION/COMPO uids, and when, i.e. client, server, both, etc.).

One example, not related to this CR (I think I raised this on the lists a while ago) is who sets the VERSION.uid.creating_system_id, when, and what is considered to be a system (because that depends on the architecture, is commit creator the same system as commit receiver? are both different systems?). We need to specify that on the SM to help developers!

Maybe with more info or examples I can see your point on why simplifying the RM removing indirections would difficult the RM to be interoperable.

With the current schema, when transporting data between systems, you need to include the contribution<OBJECT_REF> element to each VERSION XML, even if the system that receives the XML doesn't know the CONTRIBUTION or don't have access to it.
I don't see how adding the CONTRIBUTION to the core XSD affects the transportability of the VERSION, I think it allows to share information about commits between different systems. I would say that improves accessibility and maintains transportability.

Pablo Pazos
May 28, 2015, 6:41 AM

One further issue just came to my mind: if each VERSION committed has a reference to a CONTRIBUTION, and the commit is a set of VERSIONS, different VERSIONs can have references to different CONTRIBUTIONs.

To avoid that, extra rules need to be defined in the specs because the model allows that situation. IMO that shouldn't be allowed because the change set of the commit is the CONTRIBUTION.

Having an explicit containment from CONTRIBUTION to VERSION, and using the CONTRIBUTION as the committal unit container, removes the issue by construction. This works for XML commits or Object commits (e.g. using SOAP).

For the SM, the change would be from "commit(Version[], AuditData)" to "commit(Contribution)".

Pablo Pazos
October 16, 2016, 6:00 AM


In my implementation for commititng a set of VERSIONs to an EHR, my workaround was to create a VERSIONS element and commit one XML or JSON, so I have:


Since all the VERSIONs in one commit are associated to the same CONTRIBUTION. The only problem is that the VERSIONS element is not defined in the openEHR XSD.

As I proposed, the ideal for a 1 XML commit of many VERSIONs might be something like:


This is only XML/JSON serialization, doesn't affect the IM.

FYI: My commits are implemented as one POST request with content-type xml or json, and all the versions as one document in the body of the HTTP request. I don't use multi-part, and is all REST. It would be useful to know how others implement this and how this change might affect them.


Pablo Pazos



Affects versions