Skip to Content
Last modified by Helena on 2025/09/10 11:19
From version 17.2
edited by Artur
on 2025/06/06 12:55
Change comment: Update document after refactoring.
To version 12.1
edited by Artur
on 2025/05/22 14:56
Change comment: There is no comment for this version

Summary

Details

Page properties
Parent
... ... @@ -1,1 +1,1 @@
1 -Methodology.SDMX 3\.0 Standards\. Section 6\. Technical Notes.WebHome
1 +Methodology.SDMX 3\.0 Standards\. Section 6\. Technical notes.WebHome
Content
... ... @@ -10,7 +10,7 @@
10 10  
11 11  As a very successful solution to the similar problem in software development, "Semantic Versioning" [[__semver.org__>>https://semver.org/]] proposes a simple set of rules and requirements that dictate how (% style="color:#e74c3c" %)version(%%) numbers are assigned and incremented. These rules make also perfect sense in the world of versioned data modelling and help to solve the "dependency hell" encountered with previous (% style="color:#e74c3c" %)versions(%%) of [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]]. [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 applies thus the Semantic Versioning rules on all versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:Glossary.Artefact.WebHome]]. Once you release a versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:Glossary.Artefact.WebHome]], you communicate changes to it with specific increments to your (% style="color:#e74c3c" %)version(%%) number.
12 12  
13 -**This [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0(.0) specification inherits the original **[[__**semver.org**__>>https://semver.org]]** 2.0.0 wording (license: [[__Creative Commons - CC BY 3.0__>>https://creativecommons.org/licenses/by/3.0/]]) and applies it to versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]].** Under this scheme, (% style="color:#e74c3c" %)version(%%) numbers and the way they change convey meaning about the underlying data structures and what has been modified from one (% style="color:#e74c3c" %)version(%%) to the next.
13 +**This [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0(.0) specification inherits the original **[[__**semver.org**__>>https://xwiki:semver.org]]** 2.0.0 wording (license: [[__Creative Commons - CC BY 3.0__>>https://creativecommons.org/licenses/by/3.0/]]) and applies it to versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:Glossary.Artefact.WebHome]].** Under this scheme, (% style="color:#e74c3c" %)version(%%) numbers and the way they change convey meaning about the underlying data structures and what has been modified from one (% style="color:#e74c3c" %)version(%%) to the next.
14 14  
15 15  == 14.2 Semantic Versioning Specification for SDMX 3.0(.0) ==
16 16  
... ... @@ -53,12 +53,12 @@
53 53  * Semantically versioned [[artefacts>>doc:Glossary.Artefact.WebHome]] MUST only reference other semantically versioned [[artefacts>>doc:Glossary.Artefact.WebHome]].
54 54  * Wildcarded references in a stable [[artefact>>doc:Glossary.Artefact.WebHome]] implicitly target only future stable (% style="color:#e74c3c" %)versions(%%) of the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]] within the defined wildcard scope.
55 55  ** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.4.3)" if that was currently the latest available stable (% style="color:#e74c3c" %)version(%%).
56 -* Wildcarded references in a version-extended [[artefact>>doc:Glossary.Artefact.WebHome]] implicitly target future stable and version-extended (% style="color:#e74c3c" %)versions(%%) of the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]] within the defined wildcard scope.
56 +* Wildcarded references in a (% style="color:#e74c3c" %)version(%%)-extended [[artefact>>doc:Glossary.Artefact.WebHome]] implicitly target future stable and (% style="color:#e74c3c" %)version(%%)-extended (% style="color:#e74c3c" %)versions(%%) of the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]] within the defined wildcard scope.
57 57  ** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1-draft)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)" if that was currently the latest available (% style="color:#e74c3c" %)version(%%).
58 -* References to specific version-extended [[artefacts>>doc:Glossary.Artefact.WebHome]] MAY be used, but those cannot be combined with a wildcard.
58 +* References to specific (% style="color:#e74c3c" %)version(%%)-extended [[artefacts>>doc:Glossary.Artefact.WebHome]] MAY be used, but those cannot be combined with a wildcard.
59 59  ** Example: The reference to "AGENCY_ID:CODELIST_ID(2.5.0draft)" in an [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:DSD_ID(2.2.1)" resolves to [[artefact>>doc:Glossary.Artefact.WebHome]] "AGENCY_ID:CODELIST_ID(2.5.0-draft)", which might be subject to continued backwards compatible changes.
60 60  
61 -Because both, wildcarded references and references to version-extended [[artefacts>>doc:Glossary.Artefact.WebHome]], allow for changes in the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]], care needs to be taken when choosing the appropriate references in order to achieve the required limitation in the allowed scope of changes.
61 +Because both, wildcarded references and references to (% style="color:#e74c3c" %)version(%%)-extended [[artefacts>>doc:Glossary.Artefact.WebHome]], allow for changes in the referenced [[artefacts>>doc:Glossary.Artefact.WebHome]], care needs to be taken when choosing the appropriate references in order to achieve the required limitation in the allowed scope of changes.
62 62  
63 63  For references to non-dependent [[artefacts>>doc:Glossary.Artefact.WebHome]], MAJOR, MINOR or PATCH (% style="color:#e74c3c" %)version(%%) parts in [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefact>>doc:Glossary.Artefact.WebHome]] references CAN alternatively be wildcarded using "*" as replacement:
64 64  
... ... @@ -82,7 +82,7 @@
82 82  
83 83   Example: (% style="color:#e74c3c" %)Version(%%) 1.3 with isFinal=true becomes (% style="color:#e74c3c" %)version(%%) 1.3.0 and (% style="color:#e74c3c" %)version(%%) 1.3 with isFinal=false becomes (% style="color:#e74c3c" %)version(%%) 1.3.0-draft.
84 84  
85 -If [[artefact>>doc:Glossary.Artefact.WebHome]] versioning is required but semantic versioning cannot be applied, then (% style="color:#e74c3c" %)version(%%) strings used in previous (% style="color:#e74c3c" %)versions(%%) of the Standard (e.g., version=1.2) may continue to be used.
85 +If [[artefact>>doc:Glossary.Artefact.WebHome]] versioning is required but semantic versioning cannot be applied, then (% style="color:#e74c3c" %)version(%%) strings used in previous (% style="color:#e74c3c" %)versions(%%) of the Standard (e.g., (% style="color:#e74c3c" %)version(%%)=1.2) may continue to be used.
86 86  
87 87  Note: Like for other not fully backwards compatible [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 features, also some cases of semantically versioned [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 [[artefacts>>doc:Glossary.Artefact.WebHome]] cannot be converted back to earlier [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] (% style="color:#e74c3c" %)versions(%%). This is the case when one or more extensions have been created in parallel to the corresponding stable (% style="color:#e74c3c" %)version(%%). In this case, only the stable (% style="color:#e74c3c" %)version(%%) SHOULD be converted to a final (% style="color:#e74c3c" %)version(%%) (e.g., 3.2.1 becomes 3.2.1 final, and 3.2.1-draft cannot be converted back).
88 88  
... ... @@ -111,17 +111,17 @@
111 111  
112 112  This is a question of responsible modelling and foresight. Incompatible changes should not be introduced lightly to a data model that has a lot of dependencies. The cost that must be incurred to upgrade can be significant. Having to bump major (% style="color:#e74c3c" %)versions(%%) to release incompatible changes means you will think through the impact of your changes, and evaluate the cost/benefit ratio involved.
113 113  
114 -**Documenting the version changes in an artefact's annotation of type "CHANGELOG" is too much work!**
114 +**Documenting the (% style="color:#e74c3c" %)version(%%) changes in an artefact's annotation of type "CHANGELOG" is too much work!**
115 115  
116 116  It is your responsibility as a professional modeller to properly document the [[artefacts>>doc:Glossary.Artefact.WebHome]] that are intended for use by others. Managing data model complexity is a hugely important part of keeping a project efficient, and that's hard to do if nobody knows how to use your data model, or what [[artefacts>>doc:Glossary.Artefact.WebHome]] are safe to reuse. In the long run, [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning can keep everyone and everything running smoothly.
117 117  
118 118  However, refrain from overdoing. Nobody can and will read too long lists of changes. Thus, keep it to the absolute essence, and mainly use it for short announcements. You can even skip the changelog if the change is impact-less. For all complete reports, a new API feature could be more useful to automatically generate a log of differences between two (% style="color:#e74c3c" %)versions(%%).
119 119  
120 -**What do I do if I accidentally release a backwards incompatible change as a minor version?**
120 +**What do I do if I accidentally release a backwards incompatible change as a minor (% style="color:#e74c3c" %)version(%%)?**
121 121  
122 122  As soon as you realise that you've broken the [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 Semantic Versioning specification, fix the problem and release a new minor (% style="color:#e74c3c" %)version(%%) that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it's appropriate, document the offending (% style="color:#e74c3c" %)version(%%) and inform your users of the problem so that they are aware of the offending (% style="color:#e74c3c" %)version(%%).
123 123  
124 -**What if I inadvertently alter the public artefact in a way that is not compliant with the version number change (i.e. the modification incorrectly introduces a major breaking change in a patch release)?**
124 +**What if I inadvertently alter the public [[artefact>>doc:Glossary.Artefact.WebHome]] in a way that is not compliant with the (% style="color:#e74c3c" %)version(%%) number change (i.e. the modification incorrectly introduces a major breaking change in a patch release)?**
125 125  
126 126  Use your best judgement. If you have a huge audience that will be drastically impacted by changing the behaviour back to what the public [[artefact>>doc:Glossary.Artefact.WebHome]] intended, then it may be best to perform a major (% style="color:#e74c3c" %)version(%%) release, even though the property change could strictly be considered a patch release. Remember, [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0.0 Semantic Versioning is all about conveying meaning by how the (% style="color:#e74c3c" %)version(%%) number changes. If these changes are important to your users, use the (% style="color:#e74c3c" %)version(%%) number to inform them.
127 127  
... ... @@ -129,11 +129,11 @@
129 129  
130 130  Deprecating existing elements is a normal part of data modelling and is often required to make forward progress or follow history (changing classifications, evolving [[reference areas>>doc:Glossary.Reference area.WebHome]]). When you deprecate part of your stable [[artefact>>doc:Glossary.Artefact.WebHome]], you should issue a new minor (% style="color:#e74c3c" %)version(%%) with the deprecation in place (e.g. add the new country [[code>>doc:Glossary.Code.WebHome]] but still keep the old country [[code>>doc:Glossary.Code.WebHome]]) and with a "CHANGELOG" [[annotation>>doc:Glossary.Annotation.WebHome]] announcing the deprecation (e.g. the intention to remove the old country [[code>>doc:Glossary.Code.WebHome]] in a future (% style="color:#e74c3c" %)version(%%)) . Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new [[artefact>>doc:Glossary.Artefact.WebHome]].
131 131  
132 -**Does SDMX 3.0.0 Semantic Versioning have a size limit on the version string?**
132 +**Does SDMX 3.0.0 Semantic Versioning have a size limit on the (% style="color:#e74c3c" %)version(%%) string?**
133 133  
134 134  No, but use good judgement. A 255 character (% style="color:#e74c3c" %)version(%%) string is probably overkill, for example. In addition, specific [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] implementations may impose their own limits on the size of the string. Remember, it is generally recommended to use the standard extension "-draft".
135 135  
136 -**Is "v1.2.3" a semantic version?**
136 +**Is "v1.2.3" a semantic (% style="color:#e74c3c" %)version(%%)?**
137 137  
138 138  No, "v1.2.3" is not a semantic (% style="color:#e74c3c" %)version(%%). The semantic (% style="color:#e74c3c" %)version(%%) is "1.2.3".
139 139  
... ... @@ -143,13 +143,13 @@
143 143  
144 144  One with named groups for those systems that support them (PCRE [Perl Compatible Regular Expressions, i.e. Perl, PHP and R], Python and Go).
145 145  
146 -Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/Ly7O1x/3/__>>https://regex101.com/r/Ly7O1x/3/]]
146 +Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/Ly7O1x/3/__https:~~/~~/regex101.com/r/Ly7O1x/3/>>https://https:regex101.comrLy7O1x3https:regex101.comrLy7O1x3]]
147 147  
148 148  > ^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<extension>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$
149 149  
150 150  And one with numbered capture groups instead (so cg1 = major, cg2 = minor, cg3 = patch and cg4 = extension) that is compatible with ECMA Script (JavaScript), PCRE (Perl Compatible Regular Expressions, i.e. Perl, PHP and R), Python and Go.
151 151  
152 -Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/vkijKf/1/__>>https://regex101.com/r/vkijKf/1/]]
152 +Reduced (% style="color:#e74c3c" %)version(%%) (without original SemVer "build metadata") from: [[__https:~~/~~/regex101.com/r/vkijKf/1/__https:~~/~~/regex101.com/r/vkijKf/1/>>https://https:regex101.comrvkijKf1https:regex101.comrvkijKf1]]
153 153  
154 154  > ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$
155 155