Overall naming pattern

LOINC's versioning and labeling system is informed by the general principles of Semantic Versioning and the FHIR project’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. All archive and file names use Pascal Case.

Version subtypes

Major: Based on the file structure. The major version is incremented if there are structural changes to the release artifact, 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.).

Minor: Based on the file contents. The minor version is incremented if there are content changes, including those that occur with regular LOINC releases as well as less frequent “patch” or “fix” releases. Content changes do not require additional programming effort, but users are expected to update their implementation to include new content (the LOINC Committee recommends updating content within 90 days of a LOINC release).

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, when applicable, follows the version and is separated from the version by a hyphen:

<MajorVersion>.<MinorVersion>-<PreproductionLabel>

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.

NOTE 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.

Archive versus File name

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.

LOINC Version

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

The major version is incremented when there is a structural change to the LoincTableCore file, such as a change of field name, size, etc.

The minor version is incremented when there is a content change in the LoincTableCore file, such as edits to existing field contents or addition of new rows (i.e., new LOINC terms).

The LoincTableCore only has a LOINC version; it has no separate ArtifactVersion. 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 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, in addition to identifying the LOINC version that an artifact depends on, we also specify the version of the artifact itself using the following convention:

Loinc_<LoincVersion>_ArtifactName_<ArtifactVersion><-PreproductionLabel>.<Extension>

Like the LOINC major version, the artifact major version is incremented if there is a structural change in the release artifact format.

Likewise, the artifact minor version is incremented when there are edits to existing contents of fields or addition of new records.

NOTE The LOINC version and artifact version can evolve independently of each other.

Preproduction maturity artifacts

Artifacts that have not yet reached production maturity MAY be denoted by a preproduction label such as Alpha or Beta. We have not yet defined universal criteria for incrementing the preproduction status, but 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.

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 (e.g. LOINC Mapper's Guide to the Top 2000+ Lab Observations - US Version, Universal Lab Orders Value Set from LOINC) that already had their own independent version kept that version as their artifact version.

Example 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

LOINC License Version

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.

The major version of the LOINC license is incremented when artifacts are added or removed, external required attributions are added or removed, or any of the language other than the copyright end year is updated.

The minor version of the LOINC license is incremented when the copyright end year is updated.

Examples

Suppose these three files were in the December 2018 LOINC release:

Loinc_2.65_LoincTableCore.zip
Loinc_2.65_MultiaxialHierarchy_2.65.zip
Loinc_2.65_License_2.65.txt

For the June 2019 release, the following changes were made, and the archive names were updated as follows:

LoincTableCore content changes only: Loinc_2.66_LoincTableCore.zip

Multiaxial hierarchy structural and content changes: Loinc_2.66_MultiaxialHierarchy_3.0-Alpha.zip

License updates including the copyright end year as well as other text: Loinc_2.66_License_3.0.txt

For the December 2019 release, the following changes were made, and the archive names were updated as follows:

LoincTableCore content changes only: Loinc_2.67_LoincTableCore.zip

Multiaxial hierarchy content changes only, with no change in preproduction maturity level: Loinc_2.67_MultiaxialHierarchy_3.1-Alpha.zip

License updates to text other than the copyright end year: Loinc_2.67_License_4.0.txt

For the June 2020 release, if the following hypothetical changes are made, the archive names would be updated as follows:

LoincTableCore structural change for the addition of a column, plus content changes: Loinc_3.0_LoincTableCore.zip

Multiaxial hierarchy content changes and an increment in preproduction maturity level: Loinc_3.0_MultiaxialHierarchy_3.2-Beta.zip

License updated for copyright end year: Loinc_3.0_License_4.1.txt