Skip to content

Non-semantic versioning

Overview

All Versionable structures require a version number.

Non-semantic versioning which was the standard approach prior to SDMX 3.0 is characterised by two part version numbers [major version].[minor version].

For example 1.0, 2.1, 3.5 .

The combination of structure type, agency ID, structure ID, and version combine to uniquely identify an artefact and together form its URN.

Examples:

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)

Semantic versioning was introduced in SDMX 3.0 and is characterised by three-part version numbers and stricter rules.

Note

FMR support both semantic and non-semantic versioning.

Choose non-semantic versioning where a lightweight versioning policy is sufficient and the additional precision of semantic versioning is not needed

Important considerations for non-semantic versioning in FMR

  • Non-semantically versioned artefacts must use a two-part version numbers (e.g. 1.0,2.4).
  • Artefacts with three-part numbers are treated as semantically versioned (e.g. 1.0.0,3.1.2).
  • An FMR instance can hold both semantically versioned and non-semantically versioned artefacts.
  • A non-sementically versioned artefact may reference others that are sementically-versioned (e.g. a DSD version 1.0 may reference a Codelist version 1.3.2).
  • However, a semantically-versioned artefact with a three-part number may not reference non-semantically versioned artefacts with a two-part numbers. The reason for this is that the referenced artefact must be unconditionally stable which a non-semantically versioned artefact cannot guarantee since it is not subject to the semantic versioning rules.
  • Non-semantically versioned artefacts are considered 'draft' or unstable. Thus a REST structure API query must use ~ to retrieve the latest version rather than +. For instance https://registry.sdmx.io/sdmx/v2/structure/codelist/OECD/CL_ADJUSTMENT/~/?format=sdmx-3.0. The SDMX REST specifications explain how the + and ~ operators work when querying for the latest versions of artefacts.

Mutability and the SDMX 2.1 isFinal flag

When working with SDMX 2.1 structures, the isFinal flag indicates that an artefact should be treated as final and should no longer change.

Note

  1. The isFinal flag was removed in the SDMX 3.0 information and replaced with semantic versioning to distinguish between draft and final structures. For instance, 1.1.0 is an immutable final version, whereas 1.2.0-draft is not and may be changed as required.
  2. Although FMR uses the SDMX 3.0 information model, the isFinal flag state is preserved when artefacts modelled in SDMX 2.1 are loaded and retrieved. However, the flag is not visible or editable in the UI.
  3. FMR does not respect the isFinal flag thus structures where isFinal=true may still be changed.

Non-semantic versioning strategies

Two alternative strategies are commonly used for for non-semantic versioning:

Option 1: Keep all structures at 1.0

The simplest approach is to keep structures at version 1.0 and make changes in place.

This minimises administrative overhead and can be appropriate where:

  • structures are managed by a small group
  • downstream users are informed of changes through other governance processes
  • formal compatibility signalling is not required

The trade-off is that consumers may not realise that a structure has changed. This can be particularly problematic where breaking changes are made. For instance, adding or removing components from a DSD can change how data must be produced, validated, or interpreted.

Option 2: Change the version when the structure changes materially

A more informative approach is to use the two-part version number to signal the scale of change.

This is often useful for structures such as DSDs and Dataflows, where users benefit from a visible indication that the artefact has changed in a meaningful way.

One possible policy for a DSD is shown below.

Change Suggested version action
Change only the DSD description No version change, because the way the structure is used has not changed materially
Add a new non-mandatory attribute Increment the minor version, for example 1.0 to 1.1
Redesign the DSD by adding and removing multiple dimensions or attributes Increment the major version, for example 1.1 to 2.0

Practical guidance for non-semantic versioning

  • Start an artefact at version 1.0 when it is first published for production use.
  • Treat compatibility as the main criterion for deciding whether the version should change.
  • Use a major version increment when a change is not backward compatible. In other words, content produced against the older version can no longer be validated or interpreted correctly using the new one.
  • Use a minor version increment when the change remains backward compatible but is not fully forward compatible. Typical examples include adding new optional content that older consumers may not recognise.
  • The practice note uses a patch increment for clarifications, typo fixes, and other changes that are both backward and forward compatible. Because non-semantic versioning in FMR does not have a patch component, those changes normally either leave the version unchanged or, if local governance requires a visible signal, use a minor increment.

It's important to balance technical purity with operational cost. In theory, some changes justify a major increment because they break compatibility, but maintainers should also consider the disruption that forcing a new major version causes for data providers and consumers. For code lists in particular, this means avoiding removals, replacements, or restructurings unless the benefit clearly outweighs the migration cost.

For common SDMX artefacts, the practical effect is broadly as follows:

  • For code lists, adding new flat codes is usually a minor change.
  • For code lists, removing, regrouping, disaggregating, or redefining codes is usually a major change.
  • For code lists, changing an existing hierarchy can also be major, because it changes the meaning of aggregate nodes.
  • For concept schemes, adding concepts is usually a minor change.
  • For concept schemes, removing concepts is usually a major change.
  • For DSDs, adding a dimension is major.
  • For DSDs, adding a mandatory attribute is major.
  • For DSDs, adding a conditional attribute is often minor.
  • For DSDs, removing a dimension or attribute is major.

Dependencies matter. A new version of a referenced child artefact does not automatically force a new version of the parent artefact. The parent version should change only when it adopts the new child version. When it does, the parent normally reflects the most severe adopted change. For example, if a Concept Scheme adopts a minor change to a referenced Code List, the Concept Scheme should normally also move by a minor increment; if it adopts a major child change, the parent should normally move by a major increment.

Taken together, a good approach for non-semantic versioning is to adopt a small, explicit policy and apply it consistently. Even without a patch component, version numbers are most useful when users can reliably infer whether a change is editorial, additive, or breaking.

References