Versioning

This section last updated: 2023-08-15 (1 year ago)

Overall naming pattern

LOINC's versioning and labeling system is informed by the general principles of Semantic Versioning and the HL7® FHIR®'s adaptation of them. We have adopted two version subtypes based on the two kinds of expected actions users should take for each one; in addition, we may use a label to indicate preproduction status as described below.

Version subtypes

The following definitions are general purpose. Specific use of these subtypes for versions of LOINC, software, and the LOINC License are detailed below.

Major: Denotes significant changes such as file structure for the LOINC version.

Minor: Indicates incremental updates including the contents of LOINC files.

Major and minor versions are noted as follows:

<MajorVersion>.<MinorVersion>

Like the original Semantic Versioning approach, whenever a major version is incremented, the minor version will be reset to 0.

Preproduction designations

We use a preproduction label, Alpha or Beta, to identify any release artifact that is early in its development lifecycle and therefore is likely to change in its structure and/or contents in upcoming releases. See our interpretations of these preproduction statuses below.

The preproduction label is clearly identified in the artifact's corresponding ReadMe text as well as in the combined LOINC Release Notes.

Software and services provided by Regenstrief Institute for use with LOINC may also bear a preproduction label to indicate their maturity.

Alpha

The artifact is in a very preliminary state. It is expected that the files and the file structures will change substantially from release to release as the artifact is refined. This artifact is provided for evaluation and comment. It should not be used for any clinical or production purpose.

Beta

We have general consensus on the design of the artifact. The files and their columns are close to their final state but the contents of the files are still being enhanced and refined. We are confident enough in the file structure that you can begin planning for integration into your system. Beta files are still not ready for any clinical or production purpose.

Prior to the December 2019 release, the preproduction label was appended with an additional dot and number, such as Alpha.2 or Beta.1. As this additional designation did not have a clear purpose, we decided to remove it starting with the December 2019 release.

File naming pattern

All archive, file, and directory names use Pascal Case, also known as Upper Camel Case. A version number within a file name will be offset using an underscore character. A customary three-letter extension is appended to individual file names. For example:

Loinc_2.75.zip
LoincTableCore
LoincLicense_5.4.txt
MultiAxialHierarchy.csv
ImagingDocumentCodesReadMe.txt

Names for file exports

Some tools produced by LOINC (including SearchLOINC and Hierarchy Browser) allow users to export subsets of the database for their use. Given their dynamic nature, these adhoc exports follow a different naming convention. Generally they include the LOINC version and/or application name from which they are sourced. To prevent duplicate file names, they also include a UTC date/time stamp in YYYYMMDDHHMMSS format offset by an underscore. These exports are bundled with a copy of the LOINC License. They may or may not include a ReadMe file to describe the file contents.

Archive versus File name

LOINC version information is included in the name of the file archive (e.g., .zip file), but the individual files within do not include the version number so that loading scripts do not have to be updated with every version increment. The individual files do not include a preproduction label for this same reason.

LOINC version

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

The major version is incremented if there are structural changes to the LoincTableCore file, such as adding, deleting, or editing fields. These types of changes typically require additional programming effort by the user to implement (either in load scripts, database schemas, etc.).

The minor version subtype is incremented when there are only content changes in the LoincTableCore file, such as edits to existing field contents or addition of new rows (i.e., new LOINC terms). Content changes do not require additional programming effort, but users are expected to update their implementation to include new content. The minor version is incremented with regular LOINC releases as well as less frequent “patch” or “fix” releases.

Most LOINC releases would only see a minor version increment for the LOINC version because we expect the LoincTableCore structure to be quite stable over time.

Artifact versions

With the February 2022 release of LOINC 2.72, we decided to simplify the files published as part of each release. A single archive containing all LOINC table files and accessory files is now made available as opposed to each also being available as separate artifacts.

The various LOINC release artifacts (e.g. LOINC Part File, LOINC Group File, LOINC Document Ontology File) have their own development lifecycles but are only published as part of the unified LOINC release. Their structure (and content) can evolve independently of the underlying LOINC version but maintaining a separate version identifier became superfluous given the publishing schedule. Details of a given artifact's changes can be found in the corresponding ReadMe text and combined LOINC Release Notes.

The only file within the LOINC release archive to retain a separate version identifier is the LOINC License. See below for details regarding the versioning of the LOINC License.

Preproduction maturity artifacts

LOINC artifacts that have not yet reached production maturity MAY be denoted by a preproduction label such as Alpha or Beta. These changes are made following QA review and user feedback. Presently, we document the rationale for such changes in the ReadMe text and LOINC Release Notes.

Versioning for artifacts that existed prior to implementation of this versioning policy

Prior to implementation of this policy in 2017, most artifacts did not have their own independent version. For these, the initial artifact version was set to be the same as the LOINC version, with the understanding that moving forward, the LOINC and artifact versions could evolve separately.

The few release artifacts that already had their own independent version kept that version as their artifact version.

Example legacy file archive names for various artifacts:

Loinc_2.65_MultiaxialHierarchy_2.65.zip
Loinc_2.67_GroupFile_2.67-Beta.zip
Loinc_2.67_ChangeSnapshot_1.1-Alpha.zip

Software versions

Computer programs produced by Regenstrief Institute for use with the LOINC database, such as RELMA and the web-based SearchLOINC application, may maintain separate version numbers to indicate their development evolution. Semantic version subtypes indicate the significance of the given changes. An update to the major subtype means wholesale refactoring or impactful user interface changes while the minor subtype reflects only small feature additions and/or bug fixes.

Notable revisions to software versions will be documented in product release notes or change logs.

The version of the LOINC Terminology Service using HL7® FHIR® carries the underlying version(s) of FHIR the service supports.

LOINC License version

The LOINC License applies to, and is distributed with, each LOINC release. Revisions to the License can evolve independently of LOINC content. For this reason, the License (e.g. the current License text file and https://loinc.org/license) has a version identifier separate from the main LOINC version.

The versioning of the License follows the semantic major/minor subtypes. Substantive changes to the License are reflected in the major version number. Other revisions, e.g. a simple update of the copyright year, are noted by an increment of the minor version subtype. Major changes to the LOINC License will be documented in the Release Notes for a given release or a corresponding announcement.