Skip to end of metadata
Go to start of metadata

This page will be used to gather our ideas about how to best implement the versioning for UTG. 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 goal is to have a proposal for versioning of vocabulary object resources in UTG before the Main Vocabulary call on 10/24/19. 

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.

Status of discussion: Vocab is leaning towards a UTG specific versioning approach that utilizes three categories of changes (major, minor and technical correction). We also need to discuss including a diff to see what has changed.

Versioning Ideas

Ted will enter his initial thoughts about versioning here. Others are encouraged to add their ideas. 

The three initial options proposed are:

  1. Simple integer (includes Date Time Stamp format)
    1. Advantages
      1. Easiest to automatically apply
    2. Disadvantages
      1. Doesn't provide distinction between Major and Minor changes. Takes away the meaning from end-users regarding the severity of change.
  2. UTG Versioning
    1. Advantages
      1. Easier to automatically apply than Semantic Versioning
    2. Disadvantages
      1. Almost everything is a major change. How does this align with the use of GitHub branches for UTG now?
      2. Date Time Stamp format DOES NOT align with this approach, but is not precluded from being part of the metadata associated with each version
    3. Possible specification: The following information is only the beginning of a much longer discussion that needs to occur in order to provide detailed constraints about what constitutes a major, minor, or technical change
      1. For CodeSystem:
                    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 = Concept attribute changes (non-defining changes/properties - such as synonymCode), concept Status change of Active→Deprecated, addition of language translations of the text bits (print names, descriptions, etc.), or changes to CodeSystem metadata such as <title>, <Committee>, <Steward>, or <Publisher>
                    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
                    Open question: What about concept name and term name changes? – Reuben believes these would constitute a major change
      2. For ValueSet:
                  NOTE: Expansions are not considered here, only Value Set Definitions.
                  Per VSD, for Value Set Definition, any change to definitional elements means a new Value Set Definition (not version). This includes scope and immutable and any changes to Defining URI or OID. Any change to non-definitional elements do not require a new Value Set Definition. 
                  Per VSD, for Value Set Definition Version, any change to definitional elements means a new Value Set Definition Version must be created with a new Value Set Version Identifier assigned but the Value Set Identifier does not change.
                  NOTE: It appears that the VSD is silent on the impact of non-definitional element changes on the Value Set Definition Version identifier (section It was also identified that a typo exists in the aforementioned section usage notes (Value Set Defintion should be replaced with Value Set Definition Version).
        1. Definitional elements include:
          1. Content Logical Definition (FHIR valueset.compose)
        2. Non-Definitional elements that would not trigger a Version change (per VSD)
          1. Activity Status
          2. Activity Status Date
          3. Workflow Status
          4. Steward, Author, Comments, CommentString, CommentTimeStamp, TrustedValueSetExpansionSource, Type

              Major = Any change to the Content Logical Definition (CLD) - Note, underlying concept status changes in the code system do NOT inherently change the CLD, only the expansion
              Minor = Any non-definitional element changes to either the Value Set Definition or Value Set Definition Version, typo in definitional elements
              Technical Correction = Encoding changes, typos in non-definitional elements
              Need to distinguish when change to CLD should result in new Value Set, need to consider changes in scope
              Scope change = new Value Set
  3. Semantic Versioning - major (new CS, VS, etc.), minor (metadata changes), and patch (fixing misspelling, bad character) - see for an example
    1. Advantages
      1. VS and CM fit well into major/minor
      2. Can instantly tell end-user how severe the change is
    2. Disadvantages
      1. More aligned with code development than knowledge representation - minor would indicate backwards compatibility
      2. For CS, VS, CM, NS it's  hard to make rules consistent to distinguish between major, minor, and patch
        1. New CS would be major version change, so would new CS version
      3. VS expansion does not fit well into major/minor
      4. Difficult to figure out all three levels for these artifacts
      5. Each updated object would require manual review to determine type of change and result in versioning

Existing Examples of Versioning

This section will contain examples of versioning that can be considered for UTG. Please add other examples that should be considered. 

  • SemVer in Australia (Reuben):, excerpt below:

    Given a version number MAJOR.MINOR.PATCH, increment the:

    1. MAJOR version when you make incompatible API changes,
    2. MINOR version when you add functionality in a backwards compatible manner, and
    3. PATCH version when you make backwards compatible bug fixes.

    Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

    • Reuben Daniels  - please align typical authoring and terminology maintenance activities with major/minor versioning


  1. 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.
  2. 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)

  • No labels

1 Comment

  1. Jessica Bota  Please do the following:

    1) update the top of this page to include a link to the Vocab meeting in which Option #2 was proposed and approved by Vocab WG.

    2) Move the official information regarding the UTG Versioning approach to a cleaned up page. We need to keep this one for historical reasons to show what other options we considered, but I'd rather not mix the actual implementation of UTG versioning with the initial thoughts and discussion. Thus, Ted's section on Execution should be moved. In addition to what ted has outlined here in text format, please create a summary table of Major, Minor and Technical triggers so we can see them all in a table format. Please use their formal naming convention from VSD (example: ValueSetVersion.Comments, not just Comments).