Documented Execution of UTG Versioning

IMPORTANT NOTE: Everything on this page is being reviewed and updated by the TSMG. If you have any questions about this page, please bring them to the TSMG or the TSMG Artefact Versioning Policy Task Force group. 

This page outlines the approach for versioning in UTG as approved by the Vocabulary Working group. This page only includes APPROVED versioning requirements. Please see UTG Versioning Refinement (Not Yet Approved) for requirements that still require approval. A versioning approach is needed to unify how versions are assigned and maintained going forward in UTG. Currently V2, V3 content etc have used different approaches and syntax. The versioning should provide information to inform users to the severity of the change(s) and if they need to update their content.

The UTG Versioning option detailed below (major/minor/patch) was proposed and approved by the Vocabulary WG (2019-10-21 Vocab WG Call Agenda/Minutes)

SCOPE: "Versioning" here refers to the versioning of UTG Resources (Code System, Value Set, Naming System and Concept Map). Thus, any reference to backwards compatibility is in reference to the content, and is not in reference to any API.

To see a summary of all options considered for versioning, please go to UTG Versioning Planning and Discussions. 

Overall Approach

The approved UTG versioning approach is to use three integers to represent the Major.Minor.Patch versioning (such as 2.0.0).

1. When a Minor number is incremented, the Patch number is reset to 0.
2. When a Major number is incremented, the Minor number and the Patch number are both set to 0
3. Newly created objects will have their initial version set to 1.0.0 upon publishing

The version of each object will be maintained in <version>.

The sections below indicate what changes qualify as a major, minor, or patch. Generally, major changes are not backwards compatible, minor changes are backwards compatible, and patches are technical corrections that are backwards compatible. 

Code System Versioning

This table outlines the type of change by Code System resource. Full notes can be found below the table. 

1. The version for the code system objects will be in <version>
2. Note this is for internal code systems, ie those owned, authored, maintained and published by HL7 only.   It does include the HL7 CS stubs for external 'hooks'.
3. Based on discussions in conference calls and with Lloyd on impact of versioning number assignment for initial versions, we will do the following for Code Systems
   1. For all v3 code systems, the initial version will be 2.0.0
      1. At some point in the future, if needed we will figure out how to mine the version information out of the last modified change tracker in the v3 maintenance mdb file, but will NOT be done unless needed
   2. For all v2 code systems, the initial version will be 2.n.0, where 'n' is the integer of the code system version from the v2 mdb file.
   3. For all FHIR code systems, the initial version will be 4.2.0. (may be done already as of 1/6) Note this is the CI version in FHIR as of 2/21/2020; we need to discuss in Sydney what we should really use as a starting version for the UTG FHIR code systems.
      1. Not yet decided what will happen when FHIR R5 is released
      2. Not sure yet if we need to do something different for the normative code systems in R3 and R4
      3. Brings up the older versions question for the FHIR code systems
4. For Code System updates:
               Major = Adding, Deleting, and any concept Status changes (to/from Active to Retired, Active→Backwards Compatible, or Deprecated→Backward Compatible) AND any defining Concept changes (hierarchical changes, defining relationships), changes to properties that are defining (to be listed - such as isSelectable), or changes to <name>
               Minor = non-defining property changes (like editorial property value changes).
               Technical Correction = Encoding changes, typos 
               Noting anything beyond Major would be a different CodeSystem (such as changes to OID and Defining URI)
               Everything here applies to Supplements and Fragments as well

Value Set Versioning

This table outlines the type of change by Value Set resource. Full notes can be found below the table. 

1. The version for the value set objects will be in <version>
2. For value sets, we must evaluate all of the attributes defined inn VSD to determine which ones will trigger what kind of version change, ie new object, increment of major number, increment of minor number.
3. VSD attribute list:
   1. All Revision History attributes - updates to these are only from updates to other elements, so do not trigger and version ID things by themselves
   2. Creation Information - only set once when created with version 1.0.0
   3. Value Set Definition Naming
      1. Value Set Definition Naming.Name - update triggers major number increment; new entry for an additional name such as in a different language, triggers minor number increment
      2. Value Set Definition Naming.Name Language - update triggers minor number increment
      3. Value Set Definition Naming.Preferred Name Indicator - update triggers minor number increment
   4.  Value Set Definition
      1. Vaue Set Identifier - change to the identifier triggers new value set; addition of one or more secondary identifiers with no change to primary triggers minor number increment
      2. Scope - change to the scope triggers new value set, unless just editorial text change to scope text, in which case it triggers minor number increment
      3. Immutable - change to the flag triggers new value set
      4. Definition URL - change triggers minor number increment (verify with team)
      5. Intellectual Property Information - change triggers major number increment unless change is spelling or other editorial corrections in which case it is minor number increment
      6. Experimental - change to flag triggers major number increment
      7. Source Reference - change triggers major number increment unless editorial in nature which triggers minor number increment
      8. Keyword - change triggers minor number increment (verify with team)
      9. Use - change triggers major number increment (verify with team)
   5. Value Set Version
      1. Comments - change or additonal comments trigger minor number increment
      2. Version Identifier - change triggers new value set
      3. Activity Status - change triggers major number increment
      4. Activity Status Date - change triggers major number increment
      5. Author - change triggers minor number increment
      6. Steward - change triggers major number increment
      7. Trusted Value Set Expansion Source - change triggers major number increment
      8. Type -  change triggers major number increment
      9. Workflow Status - change triggers major number increment
   6. Content Logical Definition
      1. Locked Date - change triggers major number increment
      2. ActiveOnly - change triggers major number increment
      3. CLD Syntax Reference -  change triggers major number increment
      4. Content Expression - if change supports scope change and the coverage or granularity of the value set is changed, then it is a new value set.   If the syntax is modified to improve efficiency of processing or simply the syntax but the intent is unchanged in terms of coverage and granularity then it is a major number increment.   Changes to code system basis is a new value set (verify with team). 
      5. Non-computable syntax expression - change is either a new value set or a major change depending upon the interpretation (verify with team)
4. Based on discussions in conference calls and with Lloyd on impact of versioning number assignment for initial versions, we will do the following for Value Sets
   1. All V3 value set definitions (the VS resources we are generating) will be set to version 2.0.0
   2. All V2 value set definitions will be set to 2.0.0

Naming System Versioning

1. Naming System resource instances will be set to 2.0.0 initially

Release 2 Versioning Additions

1. HL7 defined versions are to be stored using provenance 
   1. Version for the HL7 V3 code systems imported from the coremif
   2. Version for the HL7 V3 value sets imported from the coremif
   3. Version for the naming systems imported from the coremif
   4. Version for the HL7 code systems imported from the v2 publishing database
   5. Version for the HL7 value sets imported from the v2 publishing database
2. Need to consider Concept Map versioning once content has been approved for/imported to UTG