Best practice for updating templates

Hi all,

I’m new to openEHR and have been playing around with ehrbase. I am wondering what is the best practice for updating a template that has been uploaded to an openEHR server.

I have noticed in the REST spec that there is no DELETE or PUT/PATCH endpoint for templates, and in my experimenting with ehrbase it prohibits me from uploading a template with the same template_id. My impression is therefore that templates can not be deleted or updated and the template_id must be unique (makes sense).

From looking at other templates and archetypes I named my test template ID acme.test-consult.v0(i.e. including the major version but omitting the minor and patch) however in order to make a change it seems I need to change the template_id. Should I put the full semver-style version as the template_id? E.g. acme.test-consult.v0.0.1? I haven’t seen the full version name included in any other example, but it’s the only way I can seem to upload a new version of an existing template. I noticed that a lot of archetypes have a revision field that contains the full semver-style version, however ehrbase at least does not seem to look at this.


1 Like

Hi @jessarcher,

we are currently working on the Admin API in EHRbase that will allow you to delete and update Templates. There is also a spring configuration that allows to simply overwrite templates with the same ID. You can find this one in the application.yml


or you provide it as a parameter if you are using Docker:


Using semver-style is advised. When overwriting templates the challenge is to ensure it is backwards compatible and EHRbase unfortunately does not have these checks in place at the moment (I think the Clinical Knowledge Manager has some means to distingush between minor and breaking changes).

Hope this helps!

1 Like

Hi Jess,

Welcome - good questions and I agree with Birger’s response. We figured out how to apply the server config to a Docker install so let me know if you need any advice on that.

Quite clearly, once we are in a production phase, we really need to keep tight control of versioning, so not allowing updates via the REST API makes sense but this is pretty burdensome when in the development stages, particularly if one is rapidly iterating the UI and making changes to the template in response, or (as in the CVID scenario) where the template is changing fairly regularly in response to fast-moving requirements changes.

The semver numbering approach has served us well for archetypes but for various reasons has not yet been applied to templates. However, I think the general approach should be the same (certainly my policy) - add the Vn major version number to the templateId.

You can add minor and patch numbers to the templateID but you then get into problems of making it difficult to apply non-breaking changes. I think the principle that we applied for archetypes is best. Use a separate semver number to manage more subtle changes.

When we finally get moved to ADL2 for templates there is a formal place for semver , but we don’t have this now in the .oet/.opt files. I think it is time for us to agree on adding that as a ‘standard’ annotation
which would allow the semver to be carried until such time as we make the jump to ADL2.

and welcome to the community :slight_smile:


One general request for feedback: we are currently implementing the delete template function in a way that we forbid it as long as templates are still being referenced by compositions.

Furthermore, we are thinking about a mechanism that provides versioning on templates similar to versioned objects in openEHR. This means that updating means not overwriting but creating an active version and still keeping track on the previous versions. This way, it is possible to re-create the state of the database at any point in time regarding the template used. Good idea, or do you think this is not too useful in reality?

Thanks for the great responses Birger and Ian :slight_smile:

I imagine Ian will have far more insightful feedback, but I can provide my early perspective.

With regards to deleting - the rule you’ve outlined sounds great, although I don’t currently have too much of a use case for deleting templates, especially with the overwriting functionality that you’ve previously mentioned.

I am very interested in template versioning and having the ability to upload new versions of templates. Both with backwards compatible changes, but also with breaking changes. Similar to the archetypes on CKM.

I have been involved with creating clinical forms and am currently investigating how openEHR might fit for us. I’ve witnessed a lot of change requests to our forms (mostly during UAT, but sometimes after launch as well) and I am trying to work out how best to handle that with openEHR when the form change requires a change to the underlying template.

I’m still in the proof-of-concept phase though. So I’m not sure yet how problematic it would be to just include the full semver in the template_id and effectively create a new template for every change. I’d just need to make sure that all new compositions use the new ID.

From an AQL point of view I think I should still be able to run queries like “give me all the blood pressure readings for an EHR” regardless of what template was used when the data was recorded.

What Birger has proposed is a great approach. That way the older versions will not be actively available, but still will not break any data already in the CDR.

  1. Delete only if no reference in any composition
  2. Version update for those in service already so that old version is not in service anymore, but available in the system.
1 Like

Hi Jess, Good discussions,

From experience and would countenance against adding the full semver to the templateId, especially in the development phase. Inevitably there is a lot of to and froing between the app developer and the template developer, particularly if you are using form builders. It gets even more messy if you are uploading to a tool like CKM which works on the templateId as a key.

My current approach in development is…

  1. Just put the major version in the templateID name.
  2. Add the semver to the other_details metadata sem_ver =0.n.n asa stop-gap until ADL@ allows us to record that ‘correctly’.

I have started a conversation with @borut.fabjan of Better and @sebastian.garde of CKM about how we can get tooling to help us here.

Semver has worked very well for us at archetype level, since it is really helpful to understand the nature of a change major, minor etc and this will be equally helpful at template level.

One decision we took for archetypes was that for a V0 archetype, the minor and patch numbers really had no defined meaning i.e v0.2.3 the .2.3 could not be relied on as any number of breaking changes may have occurred.

This probably makes sense in the context of CKM but I certainly found it helpful, when doing rapid template iterations as part of covid-19 app development, to be able to flag a potential breaking change to the app developers by incrementing the minor number to signify a breaking change , and incrementing the patch number to signify a minor revision (albeit that the overall published state is still V0). Sebastian and I were discussing that earlier this week - semver itself seems not to care what you do with V0 numbering so we are not breaking any rules there.

Essentially for a .v0 we shift the numbering one to the right, and drop patch.

We definitely have to get smarter tooling here that interrogates the semver number but I’d keep the minor and patch numbers out of the templateID.

The other issue is whether versioning rules apply the same for templates and whether that just reflects a bubble-up of changes in the underlying artefacts. e.g a major version change in a child archetype -> major version.

There are complications where a minor change in a child archetype may be constrained out in the parent template, and as such is applying a real-world revision but after playing with a few scenarios we reckoned that it is safer to apply the rule consistently , and allow the tooling to flag that the change applies to an unused node, and let a human being decide if a minor version change should actually be applied, or just apatch. Currently that’s how CKM operates - makes a suggestion but allows human override.


Thanks Ian!

I definitely agree it would be nice just to have the major version in the templateID.

How are you currently making changes to the one template ID though? Via the SYSTEM_ALLOW_TEMPLATE_OVERWRITE=true option in ehrbase?

And are you keeping prior versions of the template somehow, or do you find that you don’t need it?

I agree regarding v0 - says:

  • Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
  • Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

Sometime ago we chose to normalize the OPT 1.4 template_id to be able to better manage OPTs in the EHRServer, including the explicit major version number in the template_id:

So when you upload an OPT to EHRServer, openEHR Toolkit or Atomik, the template id is always normalized to concept.lang.version

Also, in EHRServer/Atomik, we have a minor version that is managed internally when you upload many times a template with the same UUID or template_id, which is useful to keep tracking of template development and testing.

I proposed to use such schema many times on the SEC, but it’s not been a priority for the SEC, I guess each implementation does it differently. In ADL 2 there is no problem because template IDs are like archetype IDs. But in OPT 1.4 we don’t have a standard solution, and most implementations are still in OPT 1.4.

1 Like