Skip to Content
Last modified by Artur K. on 2026/05/29 14:28
From version 1.1
edited by Helena K.
on 2026/01/15 15:01
Change comment: There is no comment for this version
To version 1.8
edited by Helena K.
on 2026/01/15 15:12
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -22,19 +22,20 @@
22 22  
23 23  The proposed versioning system is based on the Semantic Versioning 2.0 specification{{footnote}}http://www.semver.org{{/footnote}}, namely:
24 24  
25 -==== MAJOR.MINOR.PATCH{{footnote}}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.{{/footnote}} ====
25 +(% class="wikigeneratedid" id="HMAJOR.MINOR.PATCH" %)
26 +MAJOR.MINOR.PATCH{{footnote}}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.{{/footnote}}
26 26  
27 -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).
28 +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).
28 28  
29 29  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.
30 30  
31 31  When an artefact is published in production for the first time, the version number of the artefact should be 1.0.
32 32  
33 -=== 3. Criterion for incrementing the version number ===
34 += 3. Criterion for incrementing the version number =
34 34  
35 35  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.
36 36  
37 -==== a. Description of backward/forward compatibility ====
38 +== a. Description of backward/forward compatibility ==
38 38  
39 39  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.
40 40  
... ... @@ -46,71 +46,64 @@
46 46  * MINOR version when changes are backward but not forward compatible;
47 47  * PATCH version when minor changes (e.g. text clarifications, correction of typos) are both backward and forward compatible.
48 48  
49 -**// //**b. Cost-benefit analysis for a major version change
50 +== **// //**b. Cost-benefit analysis for a major version change ==
50 50  
51 51  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.
52 52  
53 -| |**//c. Synthesis based on the above syntax and criterion//**|
54 -|(% colspan="2" %)**Change SeverityVersion ImpactDescription**|**Example**
55 -|(% colspan="2" %)**Major +.0 Neither** backward **nor** forward compatibility|**1.2 2.0**
56 -|(% colspan="2" %)**Minor N.+ **Backward **but not** forward compatibility|**1.0 1.1**
57 -|(% colspan="2" %)**Patch N.M.+ **Backward **and** forward compatibility|**1.2 1.2.1**
54 +== c. Synthesis based on the above syntax and criterion ==
58 58  
56 +|(% colspan="2" %)**Change Severity**|**Version Impact**|**Description**|**Example**
57 +|(% colspan="2" %)**Major**|**+.0**|__**Neither**__ backward __**nor**__ forward compatibility|**1.2 **→**2.0**
58 +|(% colspan="2" %)**Minor**|**N.+**|Backward __**but not**__ forward compatibility|**1.0 **→**1.1**
59 +|(% colspan="2" %)**Patch**|**N.M.+**|Backward __**and**__ forward compatibility|**1.2 1.**→**2.1**
60 +
59 59  === 4. Types of artefact changes and their versioning impact ===
60 60  
61 61  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.**+**).
62 62  
63 -| |(% colspan="2" %)**CODE LIST (CL)**
64 -|**Type of Change**|**Impact**|**Comments**
65 -|(((
65 +|(% colspan="3" %)**CODE LIST (CL)**
66 +|(% style="width:877px" %)**Type of Change**|(% style="width:161px" %)**Impact**|(% style="width:1034px" %)**Comments**
67 +|(% style="width:877px" %)(((
66 66  **Addition into an existing CL of one or more new codes not having the**
67 67  
68 68  **CodeList:Code:ParentCode attribute**
69 -)))|**Minor**: **N.,,+,,**^^({{footnote}}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”.{{/footnote}})^^|Data exchanged/disseminated using the old CL can still be exchanged/disseminated using the new CL
70 -|(((
71 +)))|(% style="width:161px" %)**Minor**: **N.,,+,,**^^({{footnote}}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”.{{/footnote}})^^|(% style="width:1034px" %)Data exchanged/disseminated using the old CL can still be exchanged/disseminated using the new CL
72 +|(% style="width:877px" %)(((
71 71  **Addition of one or more new hierarchies represented using the**
72 72  
73 73  **CodeList:Code:ParentCode attribute (not using the Hierarchical Code List artefact)**
74 -)))|**Minor**: **N.,,+,,^^(^^**^^3)^^|Data exchanged/disseminated using the old CL can still be exchanged/disseminated using the new CL as already existing hierarchies still represent the same aggregations
75 -|**Addition of one or more new codes into existing hierarchies represented using the CodeList:Code:ParentCode attribute (not using the Hierarchical Code List artefact)**|**Major**: **+.0**|After the change, the parent code for the changed hierarchy does not represent the same aggregation any more, thus resulting in a break in backward compatibility
76 -|**Aggregation, disaggregation, reorganisation or removal of one or more codes**|**Major**: **+.0**|Data exchanged/disseminated using an old version of the CL can no longer be exchanged/disseminated using the new version of the CL
76 +)))|(% style="width:161px" %)**Minor**: **N.,,+,,^^(^^**^^{{footnote}}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”.{{/footnote}})^^|(% style="width:1034px" %)Data exchanged/disseminated using the old CL can still be exchanged/disseminated using the new CL as already existing hierarchies still represent the same aggregations
77 +|(% style="width:877px" %)**Addition of one or more new codes into existing hierarchies represented using the CodeList:Code:ParentCode attribute (not using the Hierarchical Code List artefact)**|(% style="width:161px" %)**Major**: **+.0**|(% style="width:1034px" %)After the change, the parent code for the changed hierarchy does not represent the same aggregation any more, thus resulting in a break in backward compatibility
78 +|(% style="width:877px" %)**Aggregation, disaggregation, reorganisation or removal of one or more codes**|(% style="width:161px" %)**Major**: **+.0**|(% style="width:1034px" %)Data exchanged/disseminated using an old version of the CL can no longer be exchanged/disseminated using the new version of the CL
77 77  
78 78  
79 79  
80 80  |(% colspan="3" %)**HIERARCHICAL CODE LIST (HCL)**
81 -|**Type of Change**|**Impact**|**Comments**
83 +|**Type of Change**|(% style="width:150px" %)**Impact**|(% style="width:1045px" %)**Comments**
82 82  |(((
83 -**Addition of new hierarchies in the HCL.**
85 +**Addition of new hierarchies in the HCL. Existing hierarchies are unaffected**
86 +)))|(% style="width:150px" %)**Minor**: **N.,,+,,**^^({{footnote}}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”.{{/footnote}})^^|(% style="width:1045px" %)Data represented using the old HCL can still be represented using the new HCL
87 +|**Addition of codes into existing hierarchies in the HCL. Existing hierarchies are thus affected**|(% style="width:150px" %)**Major**: **+.0**|(% style="width:1045px" %)The HCL resulting from this change does not represent the same aggregation any more, thus breaking backward compatibility
88 +|**Removal of one or more codes in the HCL or removal of one or more codes in the referenced code lists**|(% style="width:150px" %)**Major**: **+.0**|(% style="width:1045px" %)Data represented using the old HCL can no longer be represented using the new HCL, thus resulting in a break in backward compatibility
89 +|**Addition, modification or removal of one or more hierarchical levels**|(% style="width:150px" %)**Major: +.0**|(% style="width:1045px" %)The reorganisation of codes within hierarchies has a significant impact on the code aggregations
84 84  
85 -**Existing hierarchies are unaffected**
86 -)))|**Minor**: **N.,,+,,**^^(3)^^|Data represented using the old HCL can still be represented using the new HCL
87 -|**Addition of codes into existing hierarchies in the HCL. Existing hierarchies are thus affected**|**Major**: **+.0**|The HCL resulting from this change does not represent the same aggregation any more, thus breaking backward compatibility
88 -|**Removal of one or more codes in the HCL or removal of one or more codes in the referenced code lists**|**Major**: **+.0**|Data represented using the old HCL can no longer be represented using the new HCL, thus resulting in a break in backward compatibility
89 -|**Addition, modification or removal of one or more hierarchical levels**|**Major: +.0**|The reorganisation of codes within hierarchies has a significant impact on the code aggregations
90 -
91 -
92 -
93 93  |(% colspan="3" %)**CONCEPT SCHEME (CS)**
94 -|**Type of change**|**Impact**|**Comments**
95 -|**Addition of one or more new concepts in an existing CS**|**Minor**: **N.+**|(((
96 -Data exchanged/disseminated using the old version of the
97 -
98 -CS can still be exchanged/disseminated using the new CS
92 +|(% style="width:874px" %)**Type of change**|(% style="width:154px" %)**Impact**|(% style="width:1044px" %)**Comments**
93 +|(% style="width:874px" %)**Addition of one or more new concepts in an existing CS**|(% style="width:154px" %)**Minor**: **N.+**|(% style="width:1044px" %)(((
94 +Data exchanged/disseminated using the old version of the CS can still be exchanged/disseminated using the new CS
99 99  )))
100 -|**Removal of one or more existing concepts**|**Major: +.0**|Data exchanged/disseminated using the old version of the CS can no longer be exchanged/disseminated using the new version with less concepts
96 +|(% style="width:874px" %)**Removal of one or more existing concepts**|(% style="width:154px" %)**Major: +.0**|(% style="width:1044px" %)Data exchanged/disseminated using the old version of the CS can no longer be exchanged/disseminated using the new version with less concepts
101 101  
102 -
103 -
104 104  |(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)**
105 -|**Type of change**|**Impact**|**Comments**
106 -|**Addition of a dimension**|**Major**: **+.0**|Adding a new dimension has a strong impact because a dimension represents the identifier of a dataset, thus requiring a remodelling of the data as existing structural validation will fail
107 -|**Addition of a mandatory attribute**|**Major**: **+.0**|If the attribute is mandatory, the situation is the same as under point “Addition of a dimension”
108 -|**Addition of a conditional attribute**|**Minor**: **N.+**|If the attribute is conditional backward compatibility is maintained
109 -|**Removal of a dimension or attribute**|**Major**: **+.0**|Whatever the type of component, the change does not guarantee backward compatibility
99 +|(% style="width:868px" %)**Type of change**|(% style="width:159px" %)**Impact**|(% style="width:1045px" %)**Comments**
100 +|(% style="width:868px" %)**Addition of a dimension**|(% style="width:159px" %)**Major**: **+.0**|(% style="width:1045px" %)Adding a new dimension has a strong impact because a dimension represents the identifier of a dataset, thus requiring a remodelling of the data as existing structural validation will fail
101 +|(% style="width:868px" %)**Addition of a mandatory attribute**|(% style="width:159px" %)**Major**: **+.0**|(% style="width:1045px" %)If the attribute is mandatory, the situation is the same as under point “Addition of a dimension”
102 +|(% style="width:868px" %)**Addition of a conditional attribute**|(% style="width:159px" %)**Minor**: **N.+**|(% style="width:1045px" %)If the attribute is conditional backward compatibility is maintained
103 +|(% style="width:868px" %)**Removal of a dimension or attribute**|(% style="width:159px" %)**Major**: **+.0**|(% style="width:1045px" %)Whatever the type of component, the change does not guarantee backward compatibility
110 110  
111 111  For concrete examples, see the Appendix.
112 112  
113 -=== 5. How versioning works for inter-dependent artefacts ===
107 += 5. How versioning works for inter-dependent artefacts =
114 114  
115 115  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.
116 116  
... ... @@ -410,5 +410,7 @@
410 410  |(% colspan="5" %)**Remark: **Since the change of a typo in a Concept of the Concept Scheme does not have a direct impact on the DSD itself (the link is by reference), there is strictly speaking no need to update the DSD. Both DSDs (1.0 and 1.0.1) will have exactly the same syntax. However, if maintainers want to highlight the correction for users of the DSD or for some other reason the DSD is updated anyway; it should reference the newer Concept Scheme.
411 411  
412 412  **~ **
413 -------
407 +
408 +----
409 +
414 414  {{putFootnotes/}}
© Semantic R&D Group, 2026