Changes for page Guidelines on the Versioning of SDMX Artefacts
Last modified by Artur K. on 2026/05/29 14:28
Summary
-
Page properties (2 modified, 0 added, 0 removed)
Details
- Page properties
-
- Author
-
... ... @@ -1,1 +1,1 @@ 1 -xwiki:XWiki.he lena1 +xwiki:XWiki.arturkryazhev - Content
-
... ... @@ -88,29 +88,23 @@ 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 - 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 ... ... @@ -133,51 +133,40 @@ 133 133 The replacement of a reference with a different reference has the same impact for every artefact. 134 134 135 135 |(% colspan="3" %)**ALL ARTEFACTS** 136 -|**Type of change**|**Impact**|**Comments** 137 -|((( 138 -**Replacement of a child artefact having a different version, but same id and** 139 - 140 -** Agency**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** 141 141 )))|((( 142 -**The child artefact version change is replicated in the** 143 - 144 -**parent artefact** 145 -)))|((( 146 146 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. 147 - 148 148 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 149 149 ))) 150 -|((( 151 -**Replacement of a referenced child artefact having a** 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) 152 152 153 -**different id or Agency** 154 -)))|**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) 155 - 156 156 ==== b. Addition or removal of referenced artefacts ==== 157 157 158 -| |(% colspan="2" %)**CONCEPT SCHEME (CS)** 159 -|**Type of change**|**Impact**|**Comments** 160 -|((( 161 -**Addition or removal of a child** 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 162 162 163 -**Code List** 164 -)))|**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 165 165 166 166 167 - 168 -| |(% colspan="2" %)**DATA STRUCTURE DEFINITION (DSD)** 153 +|(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)** 169 169 |**Type of change**|**Impact**|**Comments** 170 170 |**Addition or removal of a child Code List**|((( 171 -**If same id and Agency, then the child artefact version change is replicated in the parent artefact.** 172 - 173 -**If different id or Agency, impact wil depend on the backward/forward compatibility as shown in the tables above** 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** 174 174 )))|((( 175 175 If a child Code List has a minor version change, then the DSD should also have a minor version change. 176 - 177 177 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 178 178 ))) 179 179 180 -= ==6. Appendix - Examples ===163 += 6. Appendix - Examples = 181 181 182 182 **Example 1 – Change to a Code List name, for clarification purposes**. **Patch Impact: N.M.+** 183 183 ... ... @@ -198,36 +198,29 @@ 198 198 199 199 |(% colspan="2" %)**AGGREGATION OF EXISTING CODES** 200 200 |**Old version**|**New version** 201 -|**2011** Heifers (female bovine that never calved), live **2012** Cows, live|**2010** Heifers and cows, live 202 -|(% 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. 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. 203 203 204 - 205 - 206 206 |(% colspan="2" %)**DISAGGREGATION OF EXISTING CODES** 207 207 |**Old version**|**New version** 208 208 |**1010** Live horses|((( 209 -1 .Pure bred breeding horses, live210 -1 .Other horses, live191 +1011 Pure bred breeding horses, live 192 +1012 Other horses, live 211 211 ))) 212 -|(% 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. 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. 213 213 214 - 215 - 216 216 |(% colspan="2" %)**REORGANISATION OF EXISTING CODES** 217 217 |**Old version**|**New version** 218 218 |((( 219 219 **3010** Fowls, weighing ≤ 185 g 220 - 221 221 **3020** Ducks, , weighing ≤ 185 g 222 - 223 223 **3030** Other poultry, weighing ≤ 185 g 224 - 225 225 **3040** Fowls, weighing > 185 g 226 - 227 227 **3050** Ducks, , weighing > 185 g 228 - 229 229 **3060** Other poultry, weighing > 185 g 230 -)))|**3025** Poultry, weighing ≤ 175 g **3045** Poultry, weighing > 175 g 205 +)))|**3025** Poultry, weighing ≤ 175 g 206 +**3045** Poultry, weighing > 175 g 231 231 |(% 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 232 232 233 233 **Example 5 – Changes to hierarchies in a Code List. Major impact: +.0** ... ... @@ -234,7 +234,16 @@ 234 234 235 235 |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – CODE LIST** 236 236 |**Old version**|**New version** 237 -|• 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** 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 +))) 238 238 |(% colspan="2" %)Code 02133 has been added to hierarchy 0213 239 239 240 240 **Example 6 – Changes to hierarchies in a Hierarchical Code List. Major impact: +.0** ... ... @@ -242,69 +242,58 @@ 242 242 |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – HIERARCHICAL CODE LIST** 243 243 |**Old version**|**New version** 244 244 |((( 245 - •A1 - World (codelist ref. ECB@CL_AREAS@1.0)o E1 - Europe (ECB@CL_COUNTRIES@1.0)246 - 247 - ES - Spain FR - France 248 - 249 - GR-Greece250 - 251 - IT- Italy o E4 - Africaetc.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. 252 252 )))|((( 253 -• A1=World (codelist ref. ECB@CL_AREAS@1.0) o E1 =Europe (ECB@CL_COUNTRIES@1.0) 254 - 255 - ES = Spain FR = FranceGR = Greece 256 - 257 -IT = Italy 258 - 259 -**DE= Germany** 260 - 261 -o E4 =Africaetc. 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. 262 262 ))) 263 263 |(% 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 264 264 265 265 **Example 7.1 – Dependencies between artefacts: Concept Scheme and Code List. Minor impact: N.+** 266 266 267 -|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|((( 268 -**New** 269 - 270 -**version** 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** 271 271 ))) 272 -|**CL_OBS_STATUS:Code List**|Addition of a new code X|**Minor: N.+**|**1.0**|**1.1** 273 -|**CS_TRADE:Concept Scheme: References CL_OBS_STATUS v1.0 above**|((( 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" %)((( 274 274 Adoption of new code X 275 275 276 -**//Change type//**: Replacement of a child artefact having a different version, but the same id and 277 - 278 -Agency 279 -)))|((( 257 +**//Change type//**: Replacement of a child artefact having a different version, but the same id and Agency 258 +)))|(% style="width:558px" %)((( 280 280 **Minor: N.+** 260 +The child version impact is replicated in the parent artefact 261 +)))|(% style="width:139px" %)**2.0**|(% style="width:151px" %)**2.1** 281 281 282 -The child version impact is replicated in the parent 283 - 284 -artefact 285 -)))|**2.0**|**2.1** 286 - 287 287 **Example 7.2 – Dependencies between artefacts: Concept Scheme and Code List. Major impact: +.0** 288 288 289 -|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|((( 290 -**New** 291 - 292 -**version** 265 +|(% style="width:489px" %)**Id:Artefact Type:Details**|(% style="width:734px" %)**Change type**|(% style="width:562px" %)**Version Impact**|**Old version**|((( 266 +**New version** 293 293 ))) 294 -|**CL_OBS_STATUS:Code List**|Removal of code U|**Major: +.0**|**1.0**|**2.0** 295 -|((( 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" %)((( 296 296 **CS_TRADE:Concept** 297 297 298 298 **Scheme:References** 299 299 300 300 **CL_OBS_STATUS v1.0 above** 301 -)))|((( 275 +)))|(% style="width:734px" %)((( 302 302 Adoption of new CL_OBS_STATUS without U. 303 303 304 304 **//Change type//**: Replacement of a child artefact having a different version, but the same id and 305 305 306 306 Agency 307 -)))|((( 281 +)))|(% style="width:562px" %)((( 308 308 **Major: +.0** 309 309 310 310 The child version impact is replicated in the parent artefact. ... ... @@ -312,51 +312,41 @@ 312 312 313 313 **Example 7.3 – Dependencies between artefacts: Concept Scheme and Code List. Variable impact (see below)** 314 314 315 -|**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|((( 316 -**New** 317 - 318 -**version** 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** 319 319 ))) 320 -|(% rowspan="3" %)**CL_XYZ: Code List**|((( 292 +|(% rowspan="3" style="width:489px" %)**CL_XYZ: Code List**|(% style="width:736px" %)((( 321 321 a) Maintenance agency changes from A to B for governance reasons. 322 - 323 323 Nothing else changes in the code list. 324 -)))|(% rowspan="3" %)**New artefact**|(% rowspan="3" %)((( 295 +)))|(% rowspan="3" style="width:555px" %)**New artefact**|(% rowspan="3" style="width:146px" %)((( 325 325 **CL_XYZ** 326 326 327 327 **(Agency A)** 328 -)))|(% rowspan="3" %)((( 299 +)))|(% rowspan="3" style="width:146px" %)((( 329 329 **CL_XYZ** 330 330 331 -**(Agency B)** 332 - 333 -**(new maintenance agency)** 302 +**(Agency B) 303 +(new maintenance agency)** 334 334 ))) 335 -|b) Maintenance agency changes from A to B and at the same time new codes are added 336 -|c) Maintenance agency changes from A to B. Since B has different coding rules, the code list itself changes as well. 337 -|(% rowspan="3" %)((( 338 -**CS_TRADE: Concept Scheme: References** 339 - 340 -**CL_XYZ (Agency A) ** 341 -)))|(% rowspan="3" %)((( 342 -Replacement of a child artefact having a different Agency. 343 - 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. 344 344 CL_XYZ (Agency A) changes to CL_XYZ (Agency B). 345 -)))|((( 312 +)))|(% style="width:555px" %)((( 346 346 **Case a): Patch: N.M.+** 347 - 348 348 There is no impact on data exchange 349 -)))|**2.0**|**2.0.1** 350 -|((( 315 +)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**2.0.1** 316 +|(% style="width:555px" %)((( 351 351 **Case b): Minor: N. +** 352 - 353 353 The impact is the same as a new minor version of the code list 354 -)))|**2.0**|**2.1** 355 -|((( 319 +)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**2.1** 320 +|(% style="width:555px" %)((( 356 356 **Case c) Major: +.0** 357 - 358 358 The impact is the same as a new major version of the code list. 359 -)))|**2.0**|**3.0** 323 +)))|(% style="width:146px" %)**2.0**|(% style="width:146px" %)**3.0** 360 360 361 361 **Example 7.4 – Dependencies between artefacts: Concept Scheme and DSD. Variable impact (see below)** 362 362 ... ... @@ -363,44 +363,36 @@ 363 363 |**Id:Artefact Type:Details**|**Change type**|**Version Impact**|**Old version**|**New version** 364 364 |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Addition of new Concept C4|**Minor: N.+**|**1.4**|**1.5** 365 365 |((( 366 -**TRADE: Data Structure Definition:** 367 - 368 -**references Concepts C1 and C2** 330 +**TRADE: Data Structure Definition: 331 +references Concepts C1 and C2** 369 369 )))|((( 370 370 None 371 - 372 372 Concept C3 is not used 373 373 )))|**None**|**1.0**|**1.0** 374 374 |** **| |** **|** **|** ** 375 375 |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Change of description in Concept C3 (typo)|**Patch: N.M.+**|**1.4**|**1.4.1** 376 376 |((( 377 -**TRADE: Data Structure Definition:** 378 - 379 -**references Concepts C1 and C2** 339 +**TRADE: Data Structure Definition: 340 +references Concepts C1 and C2** 380 380 )))|((( 381 381 None 382 - 383 383 Concept C3 is not used 384 384 )))|**None**|**1.0**|**1.0** 385 385 |(% colspan="5" %) 386 386 |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Removal of Concept C3|**Major: +.0**|**1.4**|**2.0** 387 387 |((( 388 -**TRADE: Data Structure Definition:** 389 - 390 -**references Concepts C1 and C2** 348 +**TRADE: Data Structure Definition: 349 +references Concepts C1 and C2** 391 391 )))|None concept C3 is not used|**None**|**1.0**|**1.0** 392 392 |(% 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. 393 393 |(% colspan="5" %) 394 394 |**CS_TRADE: Concept Scheme containing Concepts C1, C2, C3**|Change of description in Concept C2 (typo)|**Patch: N.M.+**|**1.4**|**1.4.1** 395 395 |((( 396 -**TRADE: Data Structure Definition:** 397 - 398 -**references Concepts C1 and C2** 355 +**TRADE: Data Structure Definition: 356 +references Concepts C1 and C2** 399 399 )))|Correction should be taken into account, concept C2 is used|((( 400 -**Patch: N.M.+** 401 - 402 -**//or//** 403 - 358 +**Patch: N.M.+ 359 +//or //** 404 404 **None** 405 405 )))|**1.0**|((( 406 406 **1.0.1 //or//** ... ... @@ -409,8 +409,6 @@ 409 409 ))) 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 -**~ ** 413 - 414 414 ---- 415 415 416 416 {{putFootnotes/}}