Template Versioning Requirements

This page has been moved to confluence

https://confluence.hl7.org/display/SD/Template+Versioning+Requirements

SDWG page.

*** DRAFT MATERIAL FOR DISCUSSION ***

Template compatibility requirements

• Ability to indicate forward/backward compatibility
  • Forward compatibility: An instance that conforms to a new version of a template will also continue to conform to a prior version of the template. (Example: Template X, version 1 constrains observation.code to Y. Version 2 constrains observation.code to Y and also constrains observation.effectiveTime to TS)
  • Backward compatibility: An instance that conforms to an old version of a template will also continue to conform to a new version of the template.

From the perspective of the IG constraint

• Template referencing is ALWAYS static (e.g. is ALWAYS to a specific version).
• Ability to constrain to a particular version of a template.
• Different versions retain the same name (suggesting the need for id and setId).
• Ability to distinguish a family of templates in a versioned chain from the particular version within a family.

From the perspective of the instance

• Template referencing is ALWAYS static (e.g. is ALWAYS to a specific version).
• An instance needs to be able to claim conformance with a particular version of a template.

Template metadata requirements

• Version history

Legacy template representation

• Given that these requirements are developed on top of existing IGs...

Background sources

• HITSP Template versioning position statement (TN904)
• Value set versioning
• Data types R2 Instance Identifier representation (version identifier)
• eMeasure versioning / clinical document versioning
• Template DSTU
• HL7 Template Registry requirements

TEMPLATE VERSIONING PROPOSAL

INTRODUCTION

Any edits to a published template will result in a new version. Some revisions will be forward or backward compatible.

While the act of revising a template is straightforward, the generation of a revision has a rippling affect on dependent templates. The fundamental requirement is that one must always be able to disambiguate a template reference (both in the IG and the Instance) to a specific version.

IMPLICATIONS FOR TEMPLATE DATABASE

(... this is where the dynamic referencing lives. within an IG or instance, the references are resolved to static ... Date logic also works here, where you typically export the most recent versions at time of export)

IMPLICATIONS FOR IMPLEMENTATION GUIDE

There are cases where template referencing is to a specific version of a template (a.k.a. "static referencing"). There are also cases where a template reference is "dynamic", pointing to the latest version of a template. Dynamic referencing can make it easier to maintain a large library of inter-dependent templates.

Dynamic referencing is resolved to a static reference within the context of an IG, where the publication date of the IG is used to disambiguate.

IMPLICATIONS FOR INSTANCE

Instance data must always reference a specific version of a template, since it may not be possible to infer the template version based on the publication date of the IG (e.g. where an instance includes templates that aren't defined as part of the IG).

TECHNICAL IMPLEMENTATION DETAILS

Based on the above requirements and implications, a proposed model for template versioning emerges:

[1] Template Identifiers: A template has an identifier that is the same across revisions (a.k.a. the "template ID"), and a version specific identifier (a.k.a "template version ID").

[2] Template ID is carried in templateId/@root. Template version ID is carried in templateId/@extension.

[3] Each template version is date stamped, based on the date the template is published.

[4] Template references in an IG must include template/@root, and may include templateId/@extension. Where templateId/@extension is not present, the specific version of a template being referenced is based on a comparison of IG publication date with template version date (and should be indicated somehow).

[5] Template references in an Instance must include template/@root, and should include templateId/@extension. [Within the context of an IG, where, based on the publication data of the IG one can disambiguate the dynamic reference, it is allowable to reference just a template ID].