Difference between revisions of "Template Versioning Requirements"
m |
|||
| (3 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
| + | ; This page has been moved to confluence: https://confluence.hl7.org/display/SD/Template+Versioning+Requirements | ||
| + | |||
[[Structured Documents WG|SDWG]] page. | [[Structured Documents WG|SDWG]] page. | ||
| + | |||
| + | '''*** DRAFT MATERIAL FOR DISCUSSION ***''' | ||
| Line 22: | Line 26: | ||
=Legacy template representation= | =Legacy template representation= | ||
*Given that these requirements are developed on top of existing IGs... | *Given that these requirements are developed on top of existing IGs... | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
=Background sources= | =Background sources= | ||
| Line 35: | Line 34: | ||
* Template DSTU | * Template DSTU | ||
* HL7 Template Registry requirements | * 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]. | ||
Latest revision as of 13:42, 3 October 2018
- This page has been moved to confluence
- https://confluence.hl7.org/display/SD/Template+Versioning+Requirements
SDWG page.
*** DRAFT MATERIAL FOR DISCUSSION ***
Contents
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].
