LOINC Versioning

Background

For many years, Regenstrief has been using numeric version numbers for LOINC (e.g. 2.61) and RELMA (e.g. 6.12) in the <major>.<minor> style. Our approach had some important limitations. We hadn't described our approach to incrementing version numbers and hadn't defined what constitutes a major/minor (or patch) change. We also didn’t clearly identify content versus file structure changes. Lastly, many Accessory Files have their own development path apart from the LOINC release version, but this wasn't clearly expressed.

After several drafts, in December 2017, the LOINC Committee approved a new policy for identifying versions of LOINC release artifacts.

Approach to versioning LOINC release artifacts

Version 2.2 | 2017 12 14

NOTE This new versioning convention will go into effect with the June 2018 LOINC release.

Overall naming pattern
LOINC Version
Artifact Version
LOINC License Version

Overview

LOINC's versioning and labeling system is informed by the general principles of Semantic Versioning and the FHIR project’s adaptation of them. Our goal is to adopt a similar strategy that identifies versions and their potential impact for users. Rather than the three part (major, minor, patch) style of Semantic Versioning, we define only two subtypes based on the two kinds of expected actions users should take.

Version subtypes

We define two major version subtypes for LOINC artifacts.

Structural changes of the release artifact, such as adding or editing fields, typically require additional programming effort to implement (either in load scripts, database schemas, etc) and thus deserve special attention.

Content changes of the release artifact occur in regular updates, published each June and December. Content changes may potentially occur in “patch” or “fix” releases, though this is relatively rare. Yet, the intended user behavior for both kinds of releases is the same: users should update to the new content.

Pre-release designations

Historically, we have distributed “beta” versions of RELMA (and the LOINC Table inside) at Laboratory LOINC workshops and Committee meetings that take place a few weeks before the official LOINC releases in June and December. We will use pre-release version type labels to more clearly label any release artifact early in its development lifecycle where structural changes are expected.

Following the conventions of Semantic Versioning, pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility and stability requirements as denoted by its associated normal version.

Accessory files

To make clearer the development lifecycle for Accessory Files, we separately identify the “version of LOINC” that these files depend on from the version of the Accessory File artifact itself.

Other key points

Like the original Semantic Versioning approach, whenever a structural (major) change is incremented in the version numbering, the content (minor) version number will be reset to 0.

To clearly communicate the versioning information, we will include it in the artifact names.

Overall naming pattern

In this pattern, both LoincVersion and ArtifactVersion use the explicit versioning style (and “prerelease” labels). LOINC and artifact labels use the Pascal Case capitalization pattern.

Loinc_<LoincVersion>_<ArtifactLabel>_<ArtifactVersion>.<Extension>

LOINC Version

Overall, the LOINC release version is determined by the contents and format of the LoincTableCore.

Structural (Major)

A structural change to the LoincTableCore file. For example, a change of field name, size, etc.

Content (Minor)

Edits to existing contents of fields in the LoincTableCore
New LOINC terms added (to LoincTableCore)

The LoincTableCore uses only this as its version; it has no separate ArtifactVersion. Most LOINC releases would only see an increment in the Content (Minor) subtype of the version because we expect the LoincTableCore structure to be quite stable over time.

Example versions in file names:

Loinc_2.63_LoincTableCore.zip
Loinc_3.0_LoincTableCore.zip

Artifact Version

Many LOINC release artifacts (e.g. LOINC Part File, LOINC Group File, LOINC Document Ontology File) have their own development lifecycles. Their structure (and content) can evolve independently of the underlying LOINC version. Therefore, we identify artifact versions separately from the main LOINC version they depend on.

Structural (Major)

A structural change the release artifact format.

Content (Minor)

Edits to existing contents of fields
New records added

Pre-release VersionType and Increment

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the Content (Minor) version. (e.g. -Alpha.1). We use Pascal Case for specifying VersionType, and expect that they can be compared lexically in ASCII sort order. Such that Alpha < Beta, etc.

The “significance” of changes in pre-release VersionType may vary by artifact. We have not yet defined universal criteria for moving, from Alpha to Beta to Production types, for example. In general, these changes are made following QA review and user feedback. Presently, we document the rationale for such changes in the artifact release notes.

Inaugural ArtifactVersion numbers in the new style

A few release artifacts (e.g. LOINC Mapper's Guide to the Top 2000+ Lab Observations - US Version, Universal Lab Orders Value Set from LOINC) have been published in versions independent from the main LOINC version. But many release artifacts were not (until this policy came into effect). For previously published artifacts being labeled with an ArtifactVersion for the first time, we will set the initial ArtifactVersion identical to the main LoincVersion being published at that time.

After that first publication with the new naming, the LoincVersion and ArtifactVersion could evolve independently.

Putting the pattern together with some hypothetical examples

Beta RELMA release at LOINC meeting

Loinc_2.64-Beta.1_Relma_6.23-Beta.1.zip

Official LOINC release a few weeks after the meeting (partial file listing)

Loinc_2.64_LoincTableCore.zip
Loinc_2.64_Relma_6.23.zip
Loinc_2.64_DocumentOntology_2.64.zip
Loinc_2.64_PanelsAndForms_2.64.zip
Loinc_2.64_GroupFile_1.0-Beta.1.zip

A hypothetical subsequent “Patch” release (change only in content of this artifact but not LoincTableCore)

Loinc_2.64_PanelsAndForms_2.65.zip

Next official release

Now, imagine that in the subsequent release there were structure (and content) changes to LoincTableCore file, structure (and content) changes to some accessory files, while only content changes to the DocumentOntology file.

Structure and content changes
Loinc_3.0_LoincTableCore.zip
Loinc_3.0_PanelsAndForms_3.0.zip
Loinc_3.0_GroupFile_2.0-Beta.1.zip

Content only changes
Loinc_3.0_DocumentOntology_2.65.zip

LOINC License ArtifactVersion

The LOINC License applies to, and is distributed with, each LOINC release. But, revisions to the License can also evolve independently of the LOINC content. We use a similar versioning style for the LOINC License (e.g. the current License.txt file and http://loinc.org/license) as with other distributed LOINC artifacts. The naming shows both the version of LOINC that the License applies to and was distributed with, but also signals its own changes as an artifact. Thus, the ArtifactVersion for the LOINC License will be designated as:

Major

New artifacts added
New external required attributions added
Changes to other clauses, attributions needed, etc

Minor

Updates to copyright end year only

Inaugural LOINC License ArtifactVersion in the new style

The LOINC License has not previously been published with a specific version number (other than perhaps the date when it was published) despite having many iterations in its 20+ year history. To avoid the confusion of labelling the first version in this new style as “1.0”, we propose to identify the initial License version labeled in this new style with an artifact version identical to that LOINC version. After that first publication with the new naming, the LOINC version and License artifact version could evolve independently.

Hypothetical example of first publication of LOINC License with new versioning name:

Loinc_3.1_License_3.1.txt

Hypothetical subsequent publication of License with a major change in the LOINC version 3.2 release:

Loinc_3.2_License_4.0.txt