EHR API for VERSIONED_COMPOSITION - puzzled over identifiers.

Implementation
,
1

I have been looking at the EHR REST API, specifically around the retrieval of VERSIONED_COMPOSITION data.

The REST API expects these parameters (from the specification).

image
image944×450 34.3 KB

Why does it need both the versioned_object_uid and the version_uid - the root of the version_uid appears to hold the versioned_object_uid anyway. Is this convention or mandation?

Also, when retrieving the data, I see that the returned payload includes an attribute called branch. I don’t see where this is documented in the specification; where can I find that? Appreciate this might just be an ehrbase feature.

image
image1917×969 77.9 KB

The API specification shows the response structure to be the following, which does not have 'branch'

image
image343×301 3.66 KB

2

AH, I see this might overlap with Inherited VERSION.uid to be copied to COMPOSITION.uid

3

While we wait for others to respond, I can confirm that I omitted versioned_object_uid in my implementation. If needed, we can get it from version_uid.

4

I just noticed that versioned_object_uid is also in the url:

https://{baseUrl}/v1/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}

This url format comes from following the pattern of “Get versioned COMPOSITION version at time”:

https://{baseUrl}/v1/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version

So the question is whether:

  • we introduce an unnecessary parameter versioned_object_uid in the url to have the same url pattern as in “Get versioned COMPOSITION version at time”, or
  • we remove the unnecessary parameter and use https://{baseUrl}/v1/ehr/{ehr_id}/versioned_composition/version/{version_uid}

Can we please get some guidance from the authors?

I expect the current url will be kept in which case a note in the Get versioned COMPOSITION version by id would help.

5

I must admin I don’t quite understand what is the exact question that needs answer. Having REST Api specs ‘supporting’ both uids was a deliberate design decision - the serve different purpose.
Regarding ‘branch’ property - I don’t know the reason, it is perhaps an implementation feature.

6

The confusion stems from structural redundancy in the endpoint URL:

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}

Because an openEHR ObjectVersionId (version_uid) already embeds the versioned_object_uid as its leading UUID prefix (e.g., 884f103c-...::system.com::1), passing both in the path feels redundant from a pure data routing perspective.

The specific points for the SEC:

  • Distinct Purposes: You mentioned that supporting both UIDs was a deliberate design decision to serve different purposes. Could you please share a link to the relevant spec section or elaborate on what those distinct functional purposes/use cases are?
  • Path Validation: Should the specification require server implementations to validate that versioned_object_uid matches the root ID inside version_uid (returning a 400 Bad Request if they mismatch)?

Assuming the current URL format will be kept, adding a brief explanatory note under the “Get versioned COMPOSITION version by id” section in the specification would be very helpful for future implementers.

(Regarding the branch attribute: as noted, that appears to be an EHRbase-specific implementation detail and not part of the official openEHR response schema.)