Templates 1.4 versioning & identification

Target release
Document statusDRAFT
Document owner

Pablo Pazos

Tech lead
Technical writers


Define template versioning for OPT 1.4 and the management strategy/process.

Success metrics


1. Define versioning mechanism, format, and where that should be specified in the template

Agreement in SEC

2. Define process and conditions in which a template version will changeAgreement in SEC
3. Define template version control for modeling toolsAgreement in SEC
4. Define template version control for CKM and other artifact repositoriesAgreement in SEC
5. Define template version control for implementations (systems, apps, APIs)Agreement in SEC


Template versioning has been an open issue for many years, adding ambiguities, variations and inconsistencies on implementations, since is a needed feature and is not specified in OPT 1.4.


Jul2018AugSepOctNovDecJan2019FebMarAprMayJunMilestone 1Go/No goMilestone 2

Feature 1

Feature 2

Feature 3

Feature 4

iOS App



#RequirementUser StoryImportanceJira IssueNotes

2 ....

Open Questions

QuestionAnswerDate Answered
1. Where to specify the version in OPTs 1.4?

Ian McNicoll: custom metadata or other_details

Pablo Pazos: +1 ^ but also consider specifying the TEMPLATE_ID format to include the version number, that is defining https://specifications.openehr.org/releases/BASE/latest/base_types.html#_template_id_class

In the EHRServer we use this format for template ids: concept.language.version, e.g. physical_activity.en.v1

2. Which version format to use?

Ian McNicoll: semver

Pablo Pazos: +1 ^

3. How versioning should be handled by modeling tools?

Pablo Pazos: a. modeling tools should be able to set the version number in the place agreed for question 1., using the format we define in question 2., even ask the modeler to modify the version number when they open a template for editing.

b. also when saving a template, tools might ask modelers to increase the version number (any of it's fields if we use semver: major, minor, revision, ...)

4. Versioning is dependent on the language?Pablo Pazos: since OPT 1.4 is language dependent, I think versions should be handled per language, even though we have two templates that represent the same document and have the same structure/constraints. We use concept.language.version as template id format that contemplates that.
5. How versioning should be handled by the CKM and other artifact containers?Pablo Pazos: CKM and ACs should be able to read the version number from the place we define in question 1. and use the format we defined in question 2.
6. How versioning should be handled by systems / implementations / APIs?

Pablo Pazos: version parameters when uploading templates should be avoided, the upload should consider the version number of the template and read it from the place that will be defined on question 1. following the format defined on question 2.

Internally, implementations should arrange and link the different versions of the same templates, use the last version by default, and a specific version if asked for it, or retrieve all versions for a template if doing, for instance, auditing.

7. What affects template versioning?Ian McNicoll: My starting assumption is that we follow the same rules as for archetypes and that any changes to component archetypes or bound terminology 'bubble-up' into the template version e.g if a component archetype goes from v1 to v2 the template version must increment etc Is that resonable. We can apply similar/identical rules to whatever semantics are added in templates themselves e.g altered constraints. termsets. We can also use the semver identification rules for archetypes - unique build number increments/ uids.

Out of Scope