v2+ Vocabulary - Local Development build (v0.3.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Versioning Policy for v2

Originally, i.e. during the v2 Tables Project we have used an integer to denote the version of a table with regard to its content. That implies, that incompatible next versions need to have a different base name respectively OID. However, it is hard to further argue in this direction.

From v2 Tables Project

Formerly, the project decided to use positive integers to version tables. Consequently, a new version is expressed by increasing this number by 1. Unfortunately, a version change does not tell anything about the type of change, i.e. whether it is major or only minor, or compatible or incompatible. Incompatible changes are introduced by new OIDs and symbolic names. This ia hard to maintain correctly.

SEMVER - semantic versioning

Versioning has to be independent from the base version of the standard. Therefore, semantic versioning semver.org seems to be reasonable, but it requires detailed inspection of all tables.

That implies changing the version information for tables from integer to major (integer) + minor (integer) + patch (string).

Standard translation from old to new:

old (integer + base name)		new (semver)	explanation
empty	->	0.0.0	is applicable for concept domains and (foreign) value sets
y	->	x.y-1.0	original integer value is moved to minor numbers, starting with zero
		x.y+1.0	increasing minor number depending on changes
different base, restarting with 1		x.0.0	x has to be redetermined

It is important to note that incompatible changes in a codesystem require a specific notation. Major changes in semver does that! TI/TSMG has to revise the policy to make that use clear. Otherwise we cannot trust in compatibility and have to reinvestigate all codes for updates on mappings.

New major version vs. new CS with new OID

A big question is about when to use a new major number (documenting incompatibilities) versus a completely new codesystem with a new OID and restarting with 1.0.0!?

• new major number: the codesystem is from it's content in principle the same but with new and incompatible values. For example, group names in messages
• new CS with new OID: the name and/or the content changes in such a way that the content is treated as different, For example, country code vs. citizenship.

Master Grid

The following master grid should provide an overview:

information	explanation	major	minor	patch
symbolic name	a short symbolic name for usings that a specific concept domain, value set or codesystem	a change of the symbolic name implies the next higher major version
OID	a unique identifier introducing the origin
namespace	useful?
title	title of the "table"
name	name of the "table" - same as title? Upper/lower case changes are adjusted during this project			could impace the patch?
description
concept code
concept description
concept usage	maintained as property
concept status	active/new/deprecated/..		implies minor changes
concept property		implies a major change if it has an impact on the semantic of a concept	implies minor changes

Use of Symbolic Names

• Is it necessary to have different symbolic names for a new major version for semantic incompatible changes?
• forbidden characters in symbolic names
  • "-" (problems with FHIR generation: computable names)

Use of Namespaces

• It is unclear what namespaces are good for in this project/endavour?

Use of OIDs

• Is the use of OIDs resp. their maintenance necessary?
• They can be added as additional identifier.
• are newly assigned when new codesystem is introduced

Properties to Codesystems

• What are the common properties to all tables?
  • version introduced
  • table number
  • …

Properties to Concepts

• It must be specified whether a property is informative, eg. chapter details, are normative and therefore implies semantics
• common properties to concepts
  • status (active, deprecated, ..)
  • comment

Problematic Tables

Some tables are tricky to convert to codesystems and tables:

• table name changes
  • 0078: Abnormal Flags -> Interpretation Codes
  • 0127: Allergy Type -> Allergen Type
  • 0163: Administrative Site -> Body Site
  • 0171: Country Code -> Citizenship
  • 0270: Report Type Code -> Document Type
  • 0347: Auto accident state -> State/province
  • 0371: Additive -> Additive/Preservative
• value sets only
  • 0125