Versioning of structural metadata artefacts

Overview

All Maintainable structures have a mandatory version number of the form [major number].[minor number].

Examples: 1.0, 1.1, 2.3

The version number defaults to 1.0.

The combination of the structure type, Agency ID, structure ID and version are used to uniquely identify any Maintainable structure using its URN.

Examples of URNs illustrating the use of version numbers:
urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_TIME_PER_COLLECT(1.11)
urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=IMF:ECOFIN_CONCEPTS(2.0).INDICATOR
urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=IMF:ECOFIN_DSD(1.0)
urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=WB:WDI_ENVIRONMENT_WB_WB(1.0)

Versioning Guidance

SDMX does not mandate a versioning policy. Organisations maintaining their own structures are therefore free to choose how and when version numbers change.

There are two generally adopted approaches.

Option 1 - Keep all structures at version 1.0

A simple method is to keep all structures at version 1.0.

Changes are made as required without changing any version numbers, but users of structures like DSDs may be surprised to find components have been added or removed unless other metadata governance procedures are in place.

Option 2 - Change version numbers to indicate significant changes have been made

For structures like Data Structure Definitions and Dataflows, versioning can be used to indicate to users when changes have been made that impact how they are used.

Data Structure Definition example versioning policy:

Change	Version
Change the DSD's description	The version number is not modified because the change has no material impact on the way the structure is used.
Add a new Attribute	Increment the minor version number, for instance moving from 1.0 to 1.1
A significant redesign including adding and deleting multiple dimensions and attributes	Increment the major version number, for instance moving from 1.1 to 2.0

For Item Schemes such as Codelists and Concept Schemes, it is generally recommended not to increment the version number when new codes are added. The reason being that Codelists are linked to Data Structure Definitions at a particular version, for example CL_REF_AREA(1.0). If significant changes are made to a Codelist like a complete redesign of a classification scheme, consideration should be given to incrementing the minor or major version. Thus a user may infer that CL_REF_AREA(2.0) is significantly different to CL_REF_AREA(1.0), and not just because it carries some additional codes.