1. Introduction

This document aims at providing guidelines on how to version SDMX artefacts inspired by "semantic versioning", i.e. a formal convention for specifying compatibility between the different versions of a “versionable” artefact (a SDMX artefact that has an associated version number). There are slight differences when compared to semantic versioning regarding the numbering and the definition of the criterion triggering the changes in numbering.

A three-component versioning system is proposed, with the third component being optional. The criterion for deciding which component is impacted is the severity of the change.

Versioning is central to SDMX because it guarantees the stability of references to SDMX artefacts. This is of the utmost importance given the sometimes strong dependencies between artefacts, especially in Data Structure Definitions (DSDs).

The document contains three main recommendations:

• numbering system and syntax; 
• types of artefact changes and their versioning impact;
• how versioning works for inter-dependent artefacts.

The document’s appendix contains examples of several types of changes and their versioning impact. 

2. Numbering system and syntax

The proposed versioning system is based on the Semantic Versioning 2.0 specification¹, namely:

MAJOR.MINOR.PATCH²

However, as the "patch" component will generally not be used extensively in SDMX, it is proposed to limit the coding to MAJOR.MINOR as long as no patches are implemented. Concretely, this means that version number 2.1.0 will be abridged to 2.1 as long as no patch is implemented. When a patch is implemented, the version number then becomes 2.1.1. At subsequent MAJOR change in the versioning the PATCH component will disappear (2.4.7 → 3.0). 

The most severe change has always precedence over other types of changes. For example, if the MAJOR and MINOR parts of the version number are impacted by changes, only the MAJOR component will be impacted. This means that version 3.2.1 will become 4.0.

When an artefact is published in production for the first time, the version number of the artefact should be 1.0.

3. Criterion for incrementing the version number

The criterion for deciding which component is impacted is the severity of the change, i.e. the possibility of maintaining backward and forward compatibility between the different versions of an artefact.

a. Description of backward/forward compatibility

Backward compatibility is defined as: An item (e.g. a data message) that was produced and validated with the previous version of an artefact (e.g. a DSD) can still be successfully validated using the newest version of the same artefact. For example, a data message produced and validated with a DSD version 1.1 is still valid against the same DSD (same id and Agency) upgraded to version 1.2.

Forward compatibility is defined as: An item (e.g. a data message) that is produced and validated with the new version of an artefact (e.g. a DSD) can also be validated using the previous version of the same artefact. For example, a data message produced and validated with a DSD version 1.1 is also valid against the same DSD (same id and Agency) having version 1.0 (an earlier version).

Given the syntax specified above, namely MAJOR.MINOR.PATCH, implementers should increment the:

• MAJOR version when changes are not backward compatible;
• MINOR version when changes are backward but not forward compatible;
• PATCH version when minor changes (e.g. text clarifications, correction of typos) are both backward and forward compatible. 

 b. Cost-benefit analysis for a major version change

The cost of imposing a “major” change should be balanced against the benefit of retaining backward compatibility, for example by not deleting codes used in existing data exchanges or by deleting or replacing codes only through a concerted effort of all data exchange partners.

c. Synthesis based on the above syntax and criterion

4. Types of artefact changes and their versioning impact

As a general rule insignificant changes (e.g. textual clarifications or typos) will result in an increment of the patch component of the versioning system (i.e. N.M.+).

For concrete examples, see the Appendix.

5. How versioning works for inter-dependent artefacts

This section describes how version changes to inter-dependent or parent/child artefacts affect each other. For example, how a Concept Scheme is affected when one of the Code Lists that it references changes version.

Some artefacts have references to other artefacts. For example:

• each of a Concept Scheme’s Concepts may reference a Code List;
• a DSD can reference one or more Concept Schemes;
• each of a DSD’s Concepts may reference a Code List. (Note that if a Concept-Code List reference exists both in a DSD and a Concept Scheme, the Concept-Code List reference in the DSD overrides the reference in the Concept Scheme);
• a Hierarchical Code List references one or more Code Lists whose codes are arranged in the hierarchical structure.

In the text below, the following concepts will be used:

• Parent artefact: an artefact that contains a reference to another artefact. For example, a Concept Scheme is a parent to a Code List that it references, and the Code List is the child;
• Child artefact: an artefact that is referenced by another artefact. For example, a Code List is a child of a Concept Scheme that contains a reference to it, and the Concept Scheme is the parent.

It is important to note that a new version of a child artefact does not automatically trigger a version update of the parent artefact. A version change to the parent artefact is made only if the new version of the child artefact is adopted by the parent artefact.

a. Impact on parent artefact when child artefact version changes

The replacement of a reference with a different reference has the same impact for every artefact.

b. Addition or removal of referenced artefacts

6. Appendix - Examples

Example 1 – Change to a Code List name, for clarification purposes. Patch Impact: N.M.+

Example 2 – Change to a Concept name, for clarification purposes. Patch impact: N.M.+

Example 3 – Change in the substance of codes. Major impact: +.0

Example 4 - Aggregation, disaggregation or reorganisation of codes. Major impact: +.0

Example 5 – Changes to hierarchies in a Code List. Major impact: +.0

Example 6 – Changes to hierarchies in a Hierarchical Code List. Major impact: +.0

Example 7.1 – Dependencies between artefacts: Concept Scheme and Code List. Minor impact: N.+

Example 7.2 – Dependencies between artefacts: Concept Scheme and Code List. Major impact: +.0

Example 7.3 – Dependencies between artefacts: Concept Scheme and Code List. Variable impact (see below)

Example 7.4 – Dependencies between artefacts: Concept Scheme and DSD. Variable impact (see below)

1. ^ http://www.semver.org
2. ^ It should be noted that the SDMX standard specifies no limitation as to the number of components in the versioning system. The option proposed here is thus nothing but a recommended convention.
3. ^ The overall impact on compatibility should be assessed when there are several “minor” version impact changes. For example, it may be that the effect of adding several new Code List or HCL codes results in an implicit change in the meaning of existing Code List or HCL codes which may not be completely backward compatible, therefore (depending on the analysis) the overall version impact may be “Major +.0”.
4. ^ The overall impact on compatibility should be assessed when there are several “minor” version impact changes. For example, it may be that the effect of adding several new Code List or HCL codes results in an implicit change in the meaning of existing Code List or HCL codes which may not be completely backward compatible, therefore (depending on the analysis) the overall version impact may be “Major +.0”.
5. ^ The overall impact on compatibility should be assessed when there are several “minor” version impact changes. For example, it may be that the effect of adding several new Code List or HCL codes results in an implicit change in the meaning of existing Code List or HCL codes which may not be completely backward compatible, therefore (depending on the analysis) the overall version impact may be “Major +.0”.
6. ^ i.e. without integration into or combination with another existing code.