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

Summary

Details

Page properties
Content
... ... @@ -35,7 +35,7 @@
35 35  
36 36  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.
37 37  
38 -==== a. Description of backward/forward compatibility ====
38 +== a. Description of backward/forward compatibility ==
39 39  
40 40  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.
41 41  
... ... @@ -47,71 +47,64 @@
47 47  * MINOR version when changes are backward but not forward compatible;
48 48  * PATCH version when minor changes (e.g. text clarifications, correction of typos) are both backward and forward compatible.
49 49  
50 -**// //**b. Cost-benefit analysis for a major version change
50 +== **// //**b. Cost-benefit analysis for a major version change ==
51 51  
52 52  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.
53 53  
54 -| |**//c. Synthesis based on the above syntax and criterion//**|
55 -|(% colspan="2" %)**Change SeverityVersion ImpactDescription**|**Example**
56 -|(% colspan="2" %)**Major +.0 Neither** backward **nor** forward compatibility|**1.2 2.0**
57 -|(% colspan="2" %)**Minor N.+ **Backward **but not** forward compatibility|**1.0 1.1**
58 -|(% colspan="2" %)**Patch N.M.+ **Backward **and** forward compatibility|**1.2 1.2.1**
54 +== c. Synthesis based on the above syntax and criterion ==
59 59  
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 +
60 60  === 4. Types of artefact changes and their versioning impact ===
61 61  
62 62  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.**+**).
63 63  
64 -| |(% colspan="2" %)**CODE LIST (CL)**
65 -|**Type of Change**|**Impact**|**Comments**
66 -|(((
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" %)(((
67 67  **Addition into an existing CL of one or more new codes not having the**
68 68  
69 69  **CodeList:Code:ParentCode attribute**
70 -)))|**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
71 -|(((
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" %)(((
72 72  **Addition of one or more new hierarchies represented using the**
73 73  
74 74  **CodeList:Code:ParentCode attribute (not using the Hierarchical Code List artefact)**
75 -)))|**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
76 -|**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
77 -|**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
78 78  
79 79  
80 80  
81 81  |(% colspan="3" %)**HIERARCHICAL CODE LIST (HCL)**
82 -|**Type of Change**|**Impact**|**Comments**
83 +|**Type of Change**|(% style="width:150px" %)**Impact**|(% style="width:1045px" %)**Comments**
83 83  |(((
84 -**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
85 85  
86 -**Existing hierarchies are unaffected**
87 -)))|**Minor**: **N.,,+,,**^^(3)^^|Data represented using the old HCL can still be represented using the new HCL
88 -|**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
89 -|**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
90 -|**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
91 -
92 -
93 -
94 94  |(% colspan="3" %)**CONCEPT SCHEME (CS)**
95 -|**Type of change**|**Impact**|**Comments**
96 -|**Addition of one or more new concepts in an existing CS**|**Minor**: **N.+**|(((
97 -Data exchanged/disseminated using the old version of the
98 -
99 -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
100 100  )))
101 -|**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
102 102  
103 -
104 -
105 105  |(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)**
106 -|**Type of change**|**Impact**|**Comments**
107 -|**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
108 -|**Addition of a mandatory attribute**|**Major**: **+.0**|If the attribute is mandatory, the situation is the same as under point “Addition of a dimension”
109 -|**Addition of a conditional attribute**|**Minor**: **N.+**|If the attribute is conditional backward compatibility is maintained
110 -|**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
111 111  
112 112  For concrete examples, see the Appendix.
113 113  
114 -=== 5. How versioning works for inter-dependent artefacts ===
107 += 5. How versioning works for inter-dependent artefacts =
115 115  
116 116  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.
117 117  
... ... @@ -134,51 +134,40 @@
134 134  The replacement of a reference with a different reference has the same impact for every artefact.
135 135  
136 136  |(% colspan="3" %)**ALL ARTEFACTS**
137 -|**Type of change**|**Impact**|**Comments**
138 -|(((
139 -**Replacement of a child artefact having a different version, but same id and**
140 -
141 -**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**
142 142  )))|(((
143 -**The child artefact version change is replicated in the**
144 -
145 -**parent artefact**
146 -)))|(((
147 147  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.
148 -
149 149  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
150 150  )))
151 -|(((
152 -**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)
153 153  
154 -**different id or Agency**
155 -)))|**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)
156 -
157 157  ==== b. Addition or removal of referenced artefacts ====
158 158  
159 -| |(% colspan="2" %)**CONCEPT SCHEME (CS)**
160 -|**Type of change**|**Impact**|**Comments**
161 -|(((
162 -**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
163 163  
164 -**Code List**
165 -)))|**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
166 166  
167 167  
168 -
169 -| |(% colspan="2" %)**DATA STRUCTURE DEFINITION (DSD)**
153 +|(% colspan="3" %)**DATA STRUCTURE DEFINITION (DSD)**
170 170  |**Type of change**|**Impact**|**Comments**
171 171  |**Addition or removal of a child Code List**|(((
172 -**If same id and Agency, then the child artefact version change is replicated in the parent artefact.**
173 -
174 -**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**
175 175  )))|(((
176 176  If a child Code List has a minor version change, then the DSD should also have a minor version change.
177 -
178 178  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
179 179  )))
180 180  
181 -=== 6. Appendix - Examples ===
163 += 6. Appendix - Examples =
182 182  
183 183  **Example 1 – Change to a Code List name, for clarification purposes**. **Patch Impact: N.M.+**
184 184  
... ... @@ -199,36 +199,29 @@
199 199  
200 200  |(% colspan="2" %)**AGGREGATION OF EXISTING CODES**
201 201  |**Old version**|**New version**
202 -|**2011** Heifers (female bovine that never calved), live **2012** Cows, live|**2010** Heifers and cows, live
203 -|(% 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.
204 204  
205 -
206 -
207 207  |(% colspan="2" %)**DISAGGREGATION OF EXISTING CODES**
208 208  |**Old version**|**New version**
209 209  |**1010** Live horses|(((
210 -1. Pure bred breeding horses, live
211 -1. Other horses, live
191 +1011 Pure bred breeding horses, live
192 +1012 Other horses, live
212 212  )))
213 -|(% 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.
214 214  
215 -
216 -
217 217  |(% colspan="2" %)**REORGANISATION OF EXISTING CODES**
218 218  |**Old version**|**New version**
219 219  |(((
220 220  **3010** Fowls, weighing ≤ 185 g
221 -
222 222  **3020** Ducks, , weighing ≤ 185 g
223 -
224 224  **3030** Other poultry, weighing ≤ 185 g
225 -
226 226  **3040** Fowls, weighing > 185 g
227 -
228 228  **3050** Ducks, , weighing > 185 g
229 -
230 230  **3060** Other poultry, weighing > 185 g
231 -)))|**3025** Poultry, weighing ≤ 175 g **3045** Poultry, weighing > 175 g
205 +)))|**3025** Poultry, weighing ≤ 175 g
206 +**3045** Poultry, weighing > 175 g
232 232  |(% 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
233 233  
234 234  **Example 5 – Changes to hierarchies in a Code List. Major impact: +.0**
... ... @@ -235,7 +235,8 @@
235 235  
236 236  |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – CODE LIST**
237 237  |**Old version**|**New version**
238 -|• 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 +|• 0213 - Beer o02131 - Lager beer o02132 - Other alcoholic beer|0213 - Beer o02131 - Lager beer o 02132 - Other alcoholic beer
214 +**02133 - Low and non-alcoholic beer**
239 239  |(% colspan="2" %)Code 02133 has been added to hierarchy 0213
240 240  
241 241  **Example 6 – Changes to hierarchies in a Hierarchical Code List. Major impact: +.0**
... ... @@ -243,17 +243,17 @@
243 243  |(% colspan="2" %)**ADDING A NEW CODE IN AN EXISTING HIERARCHY – HIERARCHICAL CODE LIST**
244 244  |**Old version**|**New version**
245 245  |(((
246 -• A1 - World (codelist ref. ECB@CL_AREAS@1.0) o E1 - Europe (ECB@CL_COUNTRIES@1.0)
222 + A1 - World (codelist ref. ECB@CL_AREAS@1.0) o E1 - Europe (ECB@CL_COUNTRIES@1.0)
247 247  
248 - ES - Spain FR - France
224 +ES - Spain FR - France
249 249  
250 250  GR - Greece
251 251  
252 252  IT - Italy o E4 - Africaetc.
253 253  )))|(((
254 -• A1=World (codelist ref. ECB@CL_AREAS@1.0) o E1 =Europe (ECB@CL_COUNTRIES@1.0)
230 +A1=World (codelist ref. ECB@CL_AREAS@1.0) o E1 =Europe (ECB@CL_COUNTRIES@1.0)
255 255  
256 - ES = Spain FR = FranceGR = Greece
232 +ES = Spain FR = FranceGR = Greece
257 257  
258 258  IT = Italy
259 259  
© Semantic R&D Group, 2026