Skip to Content
Last modified by Artur K. on 2026/05/29 14:28
From version 2.1
edited by Artur K.
on 2026/05/29 14:28
Change comment: Copied from sdmxsrlocalization:Methodology.Guidelines on the Versioning of SDMX Artefacts.WebHome
To version 1.7
edited by Helena K.
on 2026/01/15 15:12
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.arturkryazhev
1 +xwiki:XWiki.helena
Content
... ... @@ -88,6 +88,8 @@
88 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 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
90 90  
91 +
92 +
91 91  |(% colspan="3" %)**CONCEPT SCHEME (CS)**
92 92  |(% style="width:874px" %)**Type of change**|(% style="width:154px" %)**Impact**|(% style="width:1044px" %)**Comments**
93 93  |(% style="width:874px" %)**Addition of one or more new concepts in an existing CS**|(% style="width:154px" %)**Minor**: **N.+**|(% style="width:1044px" %)(((
... ... @@ -95,16 +95,18 @@
95 95  )))
96 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
97 97  
100 +
101 +
98 98  |(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)**
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
103 +|**Type of change**|**Impact**|**Comments**
104 +|**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
105 +|**Addition of a mandatory attribute**|**Major**: **+.0**|If the attribute is mandatory, the situation is the same as under point “Addition of a dimension”
106 +|**Addition of a conditional attribute**|**Minor**: **N.+**|If the attribute is conditional backward compatibility is maintained
107 +|**Removal of a dimension or attribute**|**Major**: **+.0**|Whatever the type of component, the change does not guarantee backward compatibility
104 104  
105 105  For concrete examples, see the Appendix.
106 106  
107 -= 5. How versioning works for inter-dependent artefacts =
111 +=== 5. How versioning works for inter-dependent artefacts ===
108 108  
109 109  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.
110 110  
... ... @@ -127,40 +127,51 @@
127 127  The replacement of a reference with a different reference has the same impact for every artefact.
128 128  
129 129  |(% colspan="3" %)**ALL ARTEFACTS**
130 -|(% style="width:492px" %)**Type of change**|(% style="width:441px" %)**Impact**|**Comments**
131 -|(% style="width:492px" %)(((
132 -**Replacement of a child artefact having a different version, but same id and Agency**
133 -)))|(% style="width:441px" %)(((
134 -**The child artefact version change is replicated in the parent artefact**
134 +|**Type of change**|**Impact**|**Comments**
135 +|(((
136 +**Replacement of a child artefact having a different version, but same id and**
137 +
138 +**Agency**
135 135  )))|(((
140 +**The child artefact version change is replicated in the**
141 +
142 +**parent artefact**
143 +)))|(((
136 136  If a child artefact (e.g. a Code List) has a minor version change, then the parent artefact (e.g. a Concept Scheme) should also have a minor version change.
145 +
137 137  If there are several child artefact version changes, the most severe impact is replicated in the parent artefact. For example, if two Code Lists have minor changes, and one Code List has a major change at the same time, the parent Concept Scheme has a major version change
138 138  )))
139 -|(% style="width:492px" %)(((
140 -**Replacement of a referenced child artefact having a different id or Agency**
141 -)))|(% style="width:441px" %)**The parent artefact version impact depends on the backward/ forward compatibility as shown in the tables above**|Technically, the child artefact is not considered to be related to the previous child artefact. It needs to be checked whether exchange contracts can still be guaranteed (backward/forward compatibility principle)
148 +|(((
149 +**Replacement of a referenced child artefact having a**
142 142  
151 +**different id or Agency**
152 +)))|**The parent artefact version impact depends on the backward/ forward compatibility as shown in the tables above**|Technically, the child artefact is not considered to be related to the previous child artefact. It needs to be checked whether exchange contracts can still be guaranteed (backward/forward compatibility principle)
153 +
143 143  ==== b. Addition or removal of referenced artefacts ====
144 144  
145 -|(% colspan="3" style="width:876px" %)**CONCEPT SCHEME (CS)**
146 -|(% style="width:845px" %)**Type of change**|(% style="width:156px" %)**Impact**|(% style="width:1071px" %)**Comments**
147 -|(% style="width:845px" %)(((
148 -**Addition or removal of a child Code List**
149 -)))|(% style="width:156px" %)**Minor: N.+**|(% style="width:1071px" %)The child Code Lists in a Data Structure Definition have priority over those referenced in a Concept Scheme. Child Code Lists added to or removed from a Concept Scheme do not have a direct impact on the data exchange. Backward/forward compatibility depends on the way Code Lists are referenced in Data Structure Definitions referencing the concept scheme. This needs to be taken into account when creating a new version of a DSD accordingly
156 +| |(% colspan="2" %)**CONCEPT SCHEME (CS)**
157 +|**Type of change**|**Impact**|**Comments**
158 +|(((
159 +**Addition or removal of a child**
150 150  
161 +**Code List**
162 +)))|**Minor: N.+**|The child Code Lists in a Data Structure Definition have priority over those referenced in a Concept Scheme. Child Code Lists added to or removed from a Concept Scheme do not have a direct impact on the data exchange. Backward/forward compatibility depends on the way Code Lists are referenced in Data Structure Definitions referencing the concept scheme. This needs to be taken into account when creating a new version of a DSD accordingly
151 151  
152 152  
153 -|(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)**
165 +
166 +| |(% colspan="2" %)**DATA STRUCTURE DEFINITION (DSD)**
154 154  |**Type of change**|**Impact**|**Comments**
155 155  |**Addition or removal of a child Code List**|(((
156 -**If same id and Agency, then the child artefact version change is replicated in the parent artefact.
157 -If different id or Agency, impact wil depend on the backward/forward compatibility as shown in the tables above**
169 +**If same id and Agency, then the child artefact version change is replicated in the parent artefact.**
170 +
171 +**If different id or Agency, impact wil depend on the backward/forward compatibility as shown in the tables above**
158 158  )))|(((
159 159  If a child Code List has a minor version change, then the DSD should also have a minor version change.
174 +
160 160  If there are several Code List version changes, the most severe impact is replicated in the DSD. For example, if two Code Lists have minor changes, and one Code List has a major change at the same time, the parent DSD has a major version change
161 161  )))
162 162  
163 -= 6. Appendix - Examples =
178 +=== 6. Appendix - Examples ===
164 164  
165 165  **Example 1 – Change to a Code List name, for clarification purposes**. **Patch Impact: N.M.+**
166 166  
... ... @@ -181,29 +181,36 @@
181 181  
182 182  |(% colspan="2" %)**AGGREGATION OF EXISTING CODES**
183 183  |**Old version**|**New version**
184 -|**2011** Heifers (female bovine that never calved), live
185 -**2012** Cows, live|**2010** Heifers and cows, live
186 -|(% colspan="2" %)Codes **2011** and **2012** are fully{{footnote}}i.e. without integration into or combination with another existing code.{{/footnote}} __**removed**__ and replaced with one __**brand new**__ code. In this case there is a many to 1 correspondence between the codes.
199 +|**2011** Heifers (female bovine that never calved), live **2012** Cows, live|**2010** Heifers and cows, live
200 +|(% colspan="2" %)Codes **2011** and **2012** are fully{{footnote}}i.e. without integration into or combination with another existing code.{{/footnote}} **removed** and replaced with one **brand new** code. In this case there is a many to 1 correspondence between the codes.
187 187  
202 +
203 +
188 188  |(% colspan="2" %)**DISAGGREGATION OF EXISTING CODES**
189 189  |**Old version**|**New version**
190 190  |**1010** Live horses|(((
191 -1011 Pure bred breeding horses, live
192 -1012 Other horses, live
207 +1. Pure bred breeding horses, live
208 +1. Other horses, live
193 193  )))
194 -|(% colspan="2" %)Code **1010** is fully __**removed**__ and replaced with two __**brand new**__ codes. In this case there is a 1 to m correspondence between the codes.
210 +|(% colspan="2" %)Code **1010** is fully **removed** and replaced with two **brand new** codes. In this case there is a 1 to m correspondence between the codes.
195 195  
212 +
213 +
196 196  |(% colspan="2" %)**REORGANISATION OF EXISTING CODES**
197 197  |**Old version**|**New version**
198 198  |(((
199 199  **3010** Fowls, weighing ≤ 185 g
218 +
200 200  **3020** Ducks, , weighing ≤ 185 g
220 +
201 201  **3030** Other poultry, weighing ≤ 185 g
222 +
202 202  **3040** Fowls, weighing > 185 g
224 +
203 203  **3050** Ducks, , weighing > 185 g
226 +
204 204  **3060** Other poultry, weighing > 185 g
205 -)))|**3025** Poultry, weighing ≤ 175 g
206 -**3045** Poultry, weighing > 175 g
228 +)))|**3025** Poultry, weighing ≤ 175 g **3045** Poultry, weighing > 175 g
207 207  |(% colspan="2" %)Codes **3010**, **3020**, **3030**, **3040**, **3050** and **3060** are fully removed and replaced with two brand new codes; furthermore the criterion for the classification used in the old version has been changed in the new version (185 g criterion versus 175 g criterion), so that it is not possible to exactly aggregate the codes from the old version to the codes of the new version (e.g. a part of **3010** goes to **3025**, another part to **3045**). In this case there is a m to n correspondence between the two sets of codes
208 208  
209 209  **Example 5 – Changes to hierarchies in a Code List. Major impact: +.0**
... ... @@ -210,16 +210,7 @@
210 210  
211 211  |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – CODE LIST**
212 212  |**Old version**|**New version**
213 -|(((
214 -* 0213 - Beer
215 -** 02131 - Lager beer
216 -** 02132 - Other alcoholic beer
217 -)))|(((
218 -* 0213 - Beer
219 -** 02131 - Lager beer
220 -** 02132 - Other alcoholic beer
221 -* **02133 - Low and non-alcoholic beer**
222 -)))
235 +|• 0213 - Beer o02131 - Lager beer o02132 - Other alcoholic beer|• 0213 - Beer o02131 - Lager beer o 02132 - Other alcoholic beer o **02133 - Low and non-alcoholic beer**
223 223  |(% colspan="2" %)Code 02133 has been added to hierarchy 0213
224 224  
225 225  **Example 6 – Changes to hierarchies in a Hierarchical Code List. Major impact: +.0**
... ... @@ -227,58 +227,69 @@
227 227  |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – HIERARCHICAL CODE LIST**
228 228  |**Old version**|**New version**
229 229  |(((
230 -* A1 - World (codelist ref. ECB@CL_AREAS@1.0)
231 -** E1 - Europe (ECB@CL_COUNTRIES@1.0)
232 -*** ES - Spain FR - France
233 -*** GR - Greece
234 -*** IT - Italy
235 -** E4 - Africa
236 -*** etc.
243 +• A1 - World (codelist ref. ECB@CL_AREAS@1.0) o E1 - Europe (ECB@CL_COUNTRIES@1.0)
244 +
245 + ES - Spain FR - France
246 +
247 +GR - Greece
248 +
249 +IT - Italy o E4 - Africaetc.
237 237  )))|(((
238 -* A1=World (codelist ref. ECB@CL_AREAS@1.0)
239 -** E1 =Europe (ECB@CL_COUNTRIES@1.0)
240 -** ES = Spain FR = FranceGR = Greece
241 -** IT = Italy
242 -** **DE= Germany**
243 -* E4 =Africa
244 -** etc.
251 +• A1=World (codelist ref. ECB@CL_AREAS@1.0) o E1 =Europe (ECB@CL_COUNTRIES@1.0)
252 +
253 + ES = Spain FR = FranceGR = Greece
254 +
255 +IT = Italy
256 +
257 +**DE= Germany**
258 +
259 +o E4 =Africaetc.
245 245  )))
246 246  |(% colspan="2" %)The id of the hierarchical codes are assumed to be equal to those of the code lists referenced. The code DE has been added to hierarchy E1
247 247  
248 248  **Example 7.1 – Dependencies between artefacts: Concept Scheme and Code List. Minor impact: N.+**
249 249  
250 -|(% style="width:492px" %)**Id:Artefact Type:Details**|(% style="width:732px" %)**Change type**|(% style="width:558px" %)**Version Impact**|(% style="width:139px" %)**Old version**|(% style="width:151px" %)(((
251 -**New version**
265 +|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|(((
266 +**New**
267 +
268 +**version**
252 252  )))
253 -|(% style="width:492px" %)**CL_OBS_STATUS:Code List**|(% style="width:732px" %)Addition of a new code X|(% style="width:558px" %)**Minor: N.+**|(% style="width:139px" %)**1.0**|(% style="width:151px" %)**1.1**
254 -|(% style="width:492px" %)**CS_TRADE:Concept Scheme: References CL_OBS_STATUS v1.0 above**|(% style="width:732px" %)(((
270 +|**CL_OBS_STATUS:Code List**|Addition of a new code X|**Minor: N.+**|**1.0**|**1.1**
271 +|**CS_TRADE:Concept Scheme: References CL_OBS_STATUS v1.0 above**|(((
255 255  Adoption of new code X
256 256  
257 -**//Change type//**: Replacement of a child artefact having a different version, but the same id and Agency
258 -)))|(% style="width:558px" %)(((
274 +**//Change type//**: Replacement of a child artefact having a different version, but the same id and
275 +
276 +Agency
277 +)))|(((
259 259  **Minor: N.+**
260 -The child version impact is replicated in the parent artefact
261 -)))|(% style="width:139px" %)**2.0**|(% style="width:151px" %)**2.1**
262 262  
280 +The child version impact is replicated in the parent
281 +
282 +artefact
283 +)))|**2.0**|**2.1**
284 +
263 263  **Example 7.2 – Dependencies between artefacts: Concept Scheme and Code List. Major impact: +.0**
264 264  
265 -|(% style="width:489px" %)**Id:Artefact Type:Details**|(% style="width:734px" %)**Change type**|(% style="width:562px" %)**Version Impact**|**Old version**|(((
266 -**New version**
287 +|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|(((
288 +**New**
289 +
290 +**version**
267 267  )))
268 -|(% style="width:489px" %)**CL_OBS_STATUS:Code List**|(% style="width:734px" %)Removal of code U|(% style="width:562px" %)**Major: +.0**|**1.0**|**2.0**
269 -|(% style="width:489px" %)(((
292 +|**CL_OBS_STATUS:Code List**|Removal of code U|**Major: +.0**|**1.0**|**2.0**
293 +|(((
270 270  **CS_TRADE:Concept**
271 271  
272 272  **Scheme:References**
273 273  
274 274  **CL_OBS_STATUS v1.0 above**
275 -)))|(% style="width:734px" %)(((
299 +)))|(((
276 276  Adoption of new CL_OBS_STATUS without U.
277 277  
278 278  **//Change type//**: Replacement of a child artefact having a different version, but the same id and
279 279  
280 280  Agency
281 -)))|(% style="width:562px" %)(((
305 +)))|(((
282 282  **Major: +.0**
283 283  
284 284  The child version impact is replicated in the parent artefact.
... ... @@ -286,41 +286,51 @@
286 286  
287 287  **Example 7.3 – Dependencies between artefacts: Concept Scheme and Code List. Variable impact (see below)**
288 288  
289 -|(% style="width:489px" %)**Id:Artefact Type:Details**|(% style="width:736px" %)**Change type**|(% style="width:555px" %)**Version Impact**|(% style="width:146px" %)**Old version**|(% style="width:146px" %)(((
290 -**New version**
313 +|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|(((
314 +**New**
315 +
316 +**version**
291 291  )))
292 -|(% rowspan="3" style="width:489px" %)**CL_XYZ: Code List**|(% style="width:736px" %)(((
318 +|(% rowspan="3" %)**CL_XYZ: Code List**|(((
293 293  a) Maintenance agency changes from A to B for governance reasons.
320 +
294 294  Nothing else changes in the code list.
295 -)))|(% rowspan="3" style="width:555px" %)**New artefact**|(% rowspan="3" style="width:146px" %)(((
322 +)))|(% rowspan="3" %)**New artefact**|(% rowspan="3" %)(((
296 296  **CL_XYZ**
297 297  
298 298  **(Agency A)**
299 -)))|(% rowspan="3" style="width:146px" %)(((
326 +)))|(% rowspan="3" %)(((
300 300  **CL_XYZ**
301 301  
302 -**(Agency B)
303 -(new maintenance agency)**
329 +**(Agency B)**
330 +
331 +**(new maintenance agency)**
304 304  )))
305 -|(% style="width:736px" %)b) Maintenance agency changes from A to B and at the same time new codes are added
306 -|(% style="width:736px" %)c) Maintenance agency changes from A to B. Since B has different coding rules, the code list itself changes as well.
307 -|(% rowspan="3" style="width:489px" %)(((
308 -**CS_TRADE: Concept Scheme: References CL_XYZ (Agency A) **
309 -)))|(% rowspan="3" style="width:736px" %)(((
310 -Replacement of a child artefact having a different Agency.
333 +|b) Maintenance agency changes from A to B and at the same time new codes are added
334 +|c) Maintenance agency changes from A to B. Since B has different coding rules, the code list itself changes as well.
335 +|(% rowspan="3" %)(((
336 +**CS_TRADE: Concept Scheme: References**
337 +
338 +**CL_XYZ (Agency A) **
339 +)))|(% rowspan="3" %)(((
340 +Replacement of a child artefact having a different Agency.
341 +
311 311  CL_XYZ (Agency A) changes to CL_XYZ (Agency B).
312 -)))|(% style="width:555px" %)(((
343 +)))|(((
313 313  **Case a): Patch: N.M.+**
345 +
314 314  There is no impact on data exchange
315 -)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**2.0.1**
316 -|(% style="width:555px" %)(((
347 +)))|**2.0**|**2.0.1**
348 +|(((
317 317  **Case b): Minor: N. +**
350 +
318 318  The impact is the same as a new minor version of the code list
319 -)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**2.1**
320 -|(% style="width:555px" %)(((
352 +)))|**2.0**|**2.1**
353 +|(((
321 321  **Case c) Major: +.0**
355 +
322 322  The impact is the same as a new major version of the code list.
323 -)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**3.0**
357 +)))|**2.0**|**3.0**
324 324  
325 325  **Example 7.4 – Dependencies between artefacts: Concept Scheme and DSD. Variable impact (see below)**
326 326  
... ... @@ -327,36 +327,44 @@
327 327  |**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|**New version**
328 328  |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Addition of new Concept C4|**Minor: N.+**|**1.4**|**1.5**
329 329  |(((
330 -**TRADE: Data Structure Definition:
331 -references Concepts C1 and C2**
364 +**TRADE: Data Structure Definition:**
365 +
366 +**references Concepts C1 and C2**
332 332  )))|(((
333 333  None
369 +
334 334  Concept C3 is not used
335 335  )))|**None**|**1.0**|**1.0**
336 336  |** **| |** **|** **|** **
337 337  |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Change of description in Concept C3 (typo)|**Patch: N.M.+**|**1.4**|**1.4.1**
338 338  |(((
339 -**TRADE: Data Structure Definition:
340 -references Concepts C1 and C2**
375 +**TRADE: Data Structure Definition:**
376 +
377 +**references Concepts C1 and C2**
341 341  )))|(((
342 342  None
380 +
343 343  Concept C3 is not used
344 344  )))|**None**|**1.0**|**1.0**
345 345  |(% colspan="5" %)
346 346  |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Removal of Concept C3|**Major: +.0**|**1.4**|**2.0**
347 347  |(((
348 -**TRADE: Data Structure Definition:
349 -references Concepts C1 and C2**
386 +**TRADE: Data Structure Definition:**
387 +
388 +**references Concepts C1 and C2**
350 350  )))|None concept C3 is not used|**None**|**1.0**|**1.0**
351 351  |(% colspan="5" %)**Remark: **Once a new version of the DSD is needed for some other reasons (e.g. a change in a code list), it is recommended to update all concept references to the newest available concept scheme if possible: i.e. DSD version 1.1 would then update its concept scheme references from 1.4 to 2.0.
352 352  |(% colspan="5" %)
353 353  |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Change of description in Concept C2 (typo)|**Patch: N.M.+**|**1.4**|**1.4.1**
354 354  |(((
355 -**TRADE: Data Structure Definition:
356 -references Concepts C1 and C2**
394 +**TRADE: Data Structure Definition:**
395 +
396 +**references Concepts C1 and C2**
357 357  )))|Correction should be taken into account, concept C2 is used|(((
358 -**Patch: N.M.+
359 -//or //**
398 +**Patch: N.M.+**
399 +
400 +**//or//**
401 +
360 360  **None**
361 361  )))|**1.0**|(((
362 362  **1.0.1 //or//**
... ... @@ -365,6 +365,8 @@
365 365  )))
366 366  |(% 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.
367 367  
410 +**~ **
411 +
368 368  ----
369 369  
370 370  {{putFootnotes/}}
© Semantic R&D Group, 2026