Semantic versioning¶

Overview¶

Semantic versioning was introduced in SDMX 3.0 to make version numbers more informative and more predictable. Instead of a two-part version such as 1.0, a semantically versioned artefact uses a three-part version in the form major.minor.patch, for example 1.2.3. The three numbers indicate the scale of change: major versions signal breaking change, minor versions signal compatible but material change, and patch versions signal non-material change such as editorial corrections.

In FMR, semantic versioning does more than label artefacts. It determines whether a structure is considered stable or draft, enables wildcard cross-references such as "latest minor" or "latest patch", and allows FMR to enforce consistent versioning rules when structures are submitted or updated. Used well, semantic versioning makes change easier to manage for both maintainers and downstream consumers.

Semantic versioning principles¶

In SDMX 3.0+, semantic versioning provides a structured way to express both stability and compatibility. A version number is not simply an identifier: it also tells users what kind of change has occurred since the previous release and what level of migration effort they should expect.

The three version components have distinct meanings:

The major number changes when the new version is not backward compatible.
The minor number changes when the artefact evolves in a meaningful but backward-compatible way.
The patch number changes when the change is non-material, for example a corrected name, description, or annotation.

This matters particularly for SDMX structural metadata, where artefacts are linked together through references. A change to a Codelist, Concept Scheme, or DSD can affect data production, validation, dissemination, and constraint evaluation. Semantic versioning provides a shared language for managing those changes safely and for deciding when dependent artefacts can continue to follow newer versions automatically.

As with non-semantic versioning, the combination of artefact type, agency ID, artefact ID, and version uniquely identifies the artefact and forms part of its URN. The difference is that with semantic versioning the version now carries formal meaning rather than being just an incrementing label.

Stable and draft structures¶

A semantically versioned structure is considered stable when it has a normal three-part version such as 1.0.0 or 2.3.4 and no suffix or extension. Stable structures are immutable: once published, they must not be changed in place. If any change is needed, a new version must be created, and the version number must increase according to the semantic versioning rules described below.

Non-stable structures are usually identified using the -draft extension, for example 1.2.0-draft. In principle SDMX allows other extensions, but to support harmonisation and make intent immediately clear, the standard -draft suffix is generally recommended¹. Draft versions are useful during modelling and review because they can evolve before a stable release is published.

Version 0.y.z is also treated as non-stable even when no suffix is present. The SDMX specification² states that major version zero is intended for initial modelling, and that anything may change at any time. In practice, this means 0.4.1 should be treated as provisional in the same way as 1.0.0-draft: it may be shared for testing or early collaboration, but it should not be treated as a stable public contract.

Wildcard cross-referencing¶

Principles¶

References between artefacts can be either exact or wildcarded. An exact reference points to one specific version, such as 1.2.3. A wildcarded reference points to the latest version that matches a semantic pattern, allowing a parent artefact to follow compatible updates to the referenced child artefact without being changed every time a new eligible version appears.

This is one of the main practical benefits of semantic versioning in SDMX. For example, a DSD may reference a Codelist using a wildcard so that new compatible additions to the Codelist are picked up automatically, while breaking revisions are excluded. This helps data models evolve without unnecessarily breaking existing exchanges, validation logic, or downstream pipelines.

Wildcarded references use the + operator to indicate "latest stable version matching this pattern":

X.Y.Z+ resolves to the latest stable patch version.
X.Y+.Z resolves to the latest stable minor version.
X+.Y.Z resolves to the latest stable major version.

For example, 1.2+.0 means "the latest stable minor version within major version 1, starting from 1.2.0", while 1.2.3+ means "the latest stable patch release compatible with 1.2.3".

Important

The ~ operator matching the latest possibly unstable version of a structure is not supported in wildcard cross-references.

Stable structures may only reference other stable structures, thus only exact references or wildcards using the + operator are permitted. While in principle a draft structure could reference the latest non-stable version of another using the ~ operator, it's not meaningful since drafts are mutable and may evolve freely without version changes.

Working with wildcard cross-references in practice¶

When structures are maintained interactively, FMR simplifies these choices in the UI. Instead of asking users to enter wildcard operators directly, it offers the most common semantic reference patterns as:

Latest Minor
Latest Patch
Exact version

Latest Major is intentionally not offered in the UI because following the latest major version would allow breaking changes to be adopted automatically, which is rarely desirable in production modelling.

The example below shows how FMR presents these semantic reference options.

FMR's management of the structure reference graph¶

Semantic wildcarding means that the structure reference graph is no longer completely static. With non-semantic versioning, a structure usually references a fixed set of specific child artefacts. With semantic versioning, the resolved graph may change over time even when the parent artefact itself has not been edited, because one of its wildcard references may now resolve to a newer compatible version.

This becomes especially important when working with constraints and other indirect references. A reference may include both semantic version wildcards and property wildcards. For example, BIS:CL_FREQ(1.0.0).%A refers to any Code beginning with A in Codelist CL_FREQ version 1.0.0. These mechanisms can be combined, so BIS:CL_FREQ(1.0+.0).%A means any Code beginning with A in the latest stable minor version of that Codelist.

References can also be direct or indirect. A direct reference explicitly names the target artefact by URN. An indirect reference arises when the target can only be discovered by resolving another artefact first. For example, a Data Constraint that constrains REF_AREA to UK indirectly references the UK Code in a Codelist, but that relationship can only be determined by first resolving the DSD used by the constrained data.

FMR resolves this reference graph dynamically when needed. That includes standard tasks such as:

returning a structure and its dependencies through the SDMX REST structure API
determining the effective structures and constraints to apply during dataset validation

In addition to the standard SDMX REST structure API, FMR provides a custom Structure Reference Graph API for navigating and managing these resolved dependencies. In particular, GET https://registry.example.org/ws/registry/reference?urn=[urn] returns the fully resolved reference graph for the structure identified by the supplied urn.

This dynamic resolution can also be combined with metadata time travel, allowing FMR to resolve an artefact's references as they existed at a specific point in the past.

Structure versioning rules¶

The benefits of semantic versioning are only realised when version numbers are applied consistently. In practice, this means the next version must reflect the scope and impact of the change that has been made.

The general rule is straightforward. Breaking changes require a major version increment. Material but non-breaking changes require at least a minor increment. Non-material changes require at least a patch increment. In SDMX structural metadata, the distinction usually comes down to whether an existing implementation would fail, behave differently, or need redesign in order to work with the new version.

Typical examples are:

Breaking changes, such as deleting codes from a Codelist or adding a dimension to a DSD, require a major version change.
Material but non-breaking changes, such as adding codes to a Codelist or adding an optional attribute to a DSD, require at least a minor version change.
Non-material changes, such as correcting an artefact name or description, require at least a patch version change.

The SDMX specifications provide detailed guidance on these rules:

Note

FMR enforces these rules.

A structure submission is rejected if the proposed version does not meet or exceed the minimum version increase required by the scope of the changes made.

The rules are enforced both when working interactively through the UI and when structures are submitted via the REST API.

Querying structures by semantic version in the SDMX REST structure API¶

FMR supports the SDMX v2.0+ structure query REST API, including semantic wildcard queries for version selection.

Examples:

GET https://registry.example.org/sdmx/v2/structure/codelist/ACY/CL_REF_AREA/1.0+.0
GET https://registry.example.org/sdmx/v2/structure/datastructure/ACY/BOP/2.1.0~

The first query asks for the latest stable minor version compatible with 1.0.0 of the CL_REF_AREA Codelist. The second asks for the latest version of the BOP DSD starting from 2.1.0 irrespective of whether this is stable or unstable.

Note

If the version path parameter is omitted, it defaults to the ~ non-stable operator. This ensures that a query returns the latest available artefact whether stable or not, and is particularly important for non-semantically versioned artefacts which are treated as unstable. i.e. those with two-part version numbers like 1.0.

The SDMX REST API specifications provide complete guidance on the available query patterns.

Semantic versioning¶

Overview¶