REST API for creating compositions with id

The current REST specifications does not seem to support creation of compositions by passing an id (similar to creating ehr with id). Is there any plans to support this feature?

This will be useful in situations when migrating data from one CDR to the other. Creating new compositions ids can have implications as the id may be referenced within and outside the CDR and will all need to be updated.


I think this is a case for the IMPORTED_VERSION class (Common Information Model) which I don’t think is well supported by the current API, at least there are no clear use cases for it.

Though I don’t have strong opinions, I think this use cases shouldn’t be part of the normal clinical flows API, but of an administrative API, because the use case is importing documents from another CDR, which is an administrative task, not directly related with the health care process.

Technically you can post a custom composition ID within the body of the POST, see: EHR API

But it depends on the implementation on how it is processed and if it is actually persisted. There was some discussion about that topic some time ago and whether or not it should be more streamlined. Simply put, either if this possibility should be removed from the REST spec or if it should be made mandatory option for implementers IIRC. Does anyone happen to know where we discussed that?

We could discuss about relaxing conditions for PUT (now used to “update” only) so that you can also create a first version and store it under that id, … but that id should be the same as the one in composition.uid.
@Dileep_V_S , is that not possible for you to place/set the id in the composition and then just use POST?

If you would need the use-case described by Pablo, you could use the ehr’s contribution-post, or perhaps you could propose to support POST/PUT on versioned_composition - as far as I remember we did not had that use-case yet.

EHRBase seems to ignore this and create a new id.

+1. The specs should remove the ambiguity for implementors. I personally feel that we should allow this either in POST or PUT.

Can you you elaborate a bit on what is the ambiguity that you think should be removed?

It will be good if we do that as it improved flexibility for deployments to evolve and refactor content as they mature and grow.

However, we may need to consider some possible situations and cover for it. Do we allow versioned composition IDs? if yes how do we allow newer versions to be committed without the older ones? How do we ensure system integrity in that case(openEHR systems are supposed to maintain versions) as he target CDR will not have the older versions?

Where can I do that?

The POST composition example body contains this

 "uid": {
    "_type": "OBJECT_VERSION_ID",
    "value": ""

That would imply that you can pass versioned composition ID in POST. But the description does not make it clear whether it will create a new composition or create one with the ID passed.

Also, if the passed version ID is used, then can that be any version or should it be only version 1?


Yes, that might need better clarifications. But the principle is that if possible, the server will create a (first version of the) composition with the ID passed, or respond with a status error in case of ID-conflict (this is however not yet specified, but I guess would be 409) or other kind of exception (invalid content, invalid ehr_id, etc).

We did not discussed in SEC about use-case when the first version is not that with id=1, but I don’t see any impediment there: by default, the first version is 1, but i guess you may choose to start with another higher number, as long as you’ll the build a lineage in version history. Some refs: Common IM - local_versioning, base_types identification_of_versions and base_types version_tree_id_class.

If you have a JIRA account you can do it in the SPECPR and use “ITS - Rest APIs” component please - see

This is what I meant we have discussed. And I actually found the ticket now:
So this topic is indeed not clarified and there’s no specified behavior yet.

@jake.smolka you are right, and @Dileep_V_S issue is closely related to this issue. But in my impression we don’t have an agreement yet on the solution for that ticket, still in the investigating phase. So more feedback/thoughts are welcome.