Difference between revisions of "Versioning of structural metadata artefacts"
(→Overview) |
|||
| (22 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | [[Category:Concepts_Reference_V10]] | |
| + | [[Category:Concepts_Reference_V11]] | ||
=Overview= | =Overview= | ||
| − | All | + | All Maintainable structures have a mandatory version number of the form <strong>[major number].[minor number]</strong>. |
| + | |||
| + | Examples: 1.0, 1.1, 2.3 | ||
The version number defaults to 1.0. | 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]]. | + | The combination of the structure type, Agency ID, structure ID and version are used to uniquely identify any Maintainable structure using its [[URN V11]]. |
| − | <nowiki> | + | |
| − | + | Examples of URN illustrating the use of version numbers:<br> | |
| − | + | <code><nowiki>urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_TIME_PER_COLLECT(1.11)</nowiki></code><br> | |
| − | + | <code><nowiki>urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=IMF:ECOFIN_CONCEPTS(2.0).INDICATOR</nowiki></code><br> | |
| − | + | <code><nowiki>urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=IMF:ECOFIN_DSD(1.0)</nowiki></code><br> | |
| − | </ | + | <code><nowiki>urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=WB:WDI_ENVIRONMENT_WB_WB(1.0)</nowiki></code> |
| + | |||
| + | =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: | ||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! 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 <strong>not</strong> 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. | ||
Latest revision as of 06:08, 13 May 2024
Contents
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 V11.
Examples of URN 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.
