Target release
Epic
Document status	DRAFT
Document owner	Pablo Pazos
Designer
Tech lead
Technical writers
QA

Objective

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

Success metrics

Goal	Metric
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 change	Agreement in SEC
3. Define template version control for modeling tools	Agreement in SEC
4. Define template version control for CKM and other artifact repositories	Agreement in SEC
5. Define template version control for implementations (systems, apps, APIs)	Agreement in SEC

Assumptions

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.

Milestones

Dashboard

Notification

Feature 1

Feature 2

Feature 3

Feature 4

iOS App

Android

Requirements

#	Requirement	User Story	Importance	Jira Issue	Notes
1			HIGH
2	....

Open Questions

Question	Answer	Date 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

ADL/OPT 2