Skip to Content
Last modified by Artur on 2025/09/10 11:19
From version 2.1
edited by Helena
on 2025/06/16 15:43
Change comment: There is no comment for this version
To version 1.1
edited by Helena
on 2025/06/16 15:34
Change comment: There is no comment for this version

Summary

Details

Page properties
Tags
... ... @@ -1,1 +1,0 @@
1 -Artefact|Statistical data and metadata exchange
Content
... ... @@ -4,17 +4,17 @@
4 4  
5 5  == 14.1 Introduction to Semantic Versioning ==
6 6  
7 -In the world of versioned data modelling exists a dreaded place called "dependency hell." The bigger your data model through organisational, national or international harmonisation grows and the more [[artefacts>>doc:sdmx:Glossary.Artefact.WebHome]] you integrate into your modelling, the more likely you are to find yourself, one day, in this pit of despair.
7 +In the world of versioned data modelling exists a dreaded place called "dependency hell." The bigger your data model through organisational, national or international harmonisation grows and the more artefacts you integrate into your modelling, the more likely you are to find yourself, one day, in this pit of despair.
8 8  
9 -In systems with many dependencies, releasing new [[artefact>>doc:sdmx:Glossary.Artefact.WebHome]] (% style="color:#e74c3c" %)versions(%%) can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of (% style="color:#e74c3c" %)version(%%) lock (the inability to upgrade an [[artefact>>doc:sdmx:Glossary.Artefact.WebHome]] without having to release new (% style="color:#e74c3c" %)versions(%%) of every dependent [[artefact>>doc:sdmx:Glossary.Artefact.WebHome]]). If dependencies are specified too loosely, you will inevitably be bitten by (% style="color:#e74c3c" %)version(%%) promiscuity (assuming compatibility with more future (% style="color:#e74c3c" %)versions(%%) than is reasonable). Dependency hell is where you are when (% style="color:#e74c3c" %)version(%%) lock and/or (% style="color:#e74c3c" %)version(%%) promiscuity prevent you from easily and safely moving your data modelling forward.
9 +In systems with many dependencies, releasing new artefact versions can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade an artefact without having to release new versions of every dependent artefact). If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable). Dependency hell is where you are when version lock and/or version promiscuity prevent you from easily and safely moving your data modelling forward.
10 10  
11 -As a very successful solution to the similar problem in software development, "Semantic Versioning" [[semver.org>>https://xwiki: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:sdmx:Glossary.Statistical data and metadata exchange.WebHome]]. [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 applies thus the Semantic Versioning rules on all versioned [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] [[artefacts>>doc:sdmx:Glossary.Artefact.WebHome]]. Once you release a versioned [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] [[artefact>>doc:sdmx:Glossary.Artefact.WebHome]], you communicate changes to it with specific increments to your (% style="color:#e74c3c" %)version(%%) number.
11 +As a very successful solution to the similar problem in software development, "Semantic Versioning" [[semver.org>>url:http://semver.org/]][[ >>url:http://semver.org/]]proposes a simple set of rules and requirements that dictate how 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 versions of SDMX. SDMX 3.0 applies thus the Semantic Versioning rules on all versioned SDMX artefacts. Once you release a versioned SDMX artefact, you communicate changes to it with specific increments to your version number.
12 12  
13 -**This [[SDMX>>doc:sdmx: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:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] structural [[artefacts>>doc:sdmx: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 3.0(.0) specification inherits the original **[[**semver.org**>>url:https://semver.org/]][[** **>>url:https://semver.org/]]**2.0.0 wording (license: **[[**Creative Commons **>>url:http://creativecommons.org/licenses/by/3.0/]][[**- **>>url:http://creativecommons.org/licenses/by/3.0/]][[**CC BY 3.0**>>url:http://creativecommons.org/licenses/by/3.0/]][[**)**>>url:http://creativecommons.org/licenses/by/3.0/]]** and applies it to versioned SDMX structural artefacts.** Under this scheme, version numbers and the way they change convey meaning about the underlying data structures and what has been modified from one version to the next.
14 14  
15 15  == 14.2 Semantic Versioning Specification for SDMX 3.0(.0) ==
16 16  
17 -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
17 + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
18 18  
19 19  In the following, "versioned" artefacts are understood to be semantically versioned SDMX structural artefacts, and X, Y, Z and EXT are understood as placeholders for the version parts MAJOR, MINOR, PATCH, and EXTENSION, as defined in chapter 4.3.
20 20  
... ... @@ -40,24 +40,121 @@
40 40  1.0.0-prerelease.11 < 1.0.0-rc.1 < 1.0.0.
41 41  
42 42  * The reasons for version changes MAY be documented in brief form in an artefact's annotation of type "CHANGELOG".
43 +*1. Backus–Naur Form Grammar for Valid SDMX 3.0(.0) Semantic Versions
43 43  
44 -== 14.3 Backus–Naur Form Grammar for Valid SDMX 3.0(.0) Semantic Versions ==
45 +|(((
46 +**<valid semver> ::= <version core>**
45 45  
46 -[[image:1750077413040-228.png]]
48 +**~ | <version core> "-" <extension>**
47 47  
48 -[[image:1750077431756-519.png]]
50 +**<version core> ::= <major> "." <minor> "." <patch>**
49 49  
50 -== 14.4 Dependency Management in SDMX 3.0(.0): ==
52 +**~ **
51 51  
54 +**<major> ::= <numeric identifier>**
55 +
56 +**~ **
57 +
58 +**<minor> ::= <numeric identifier>**
59 +
60 +**~ **
61 +
62 +**<patch> ::= <numeric identifier>**
63 +
64 +**~ **
65 +
66 +**<extension> ::= <dot-separated extension identifiers>**
67 +
68 +**~ **
69 +
70 +**<dot-separated extension identifiers> ::= <extension identifier>**
71 +
72 +**~ | <extension identifier> "." <dotseparated extension identifiers>**
73 +
74 +**~ **
75 +
76 +**<extension identifier> ::= <alphanumeric identifier>**
77 +
78 +**~ | <numeric identifier>**
79 +
80 +**~ **
81 +
82 +**<alphanumeric identifier> ::= <non-digit>**
83 +
84 +**~ | <non-digit> <identifier characters>**
85 +
86 +**~ | <identifier characters> <non-digit>**
87 +
88 +**~ | <identifier characters> <non-digit> <identifier characters>**
89 +
90 +**~ **
91 +
92 +**<numeric identifier> ::= "0"**
93 +
94 +**~ | <positive digit>**
95 +
96 +**~ | <positive digit> <digits>**
97 +
98 +**~ **
99 +
100 +**<identifier characters> ::= <identifier character>**
101 +
102 +**~ | <identifier character> <identifier characters>**
103 +)))
104 +
105 +**<identifier character> ::= <digit>**
106 +
107 +**~ | <non-digit>**
108 +
109 +**~ **
110 +
111 +**<non-digit> ::= <letter>**
112 +
113 +**~ | "-"**
114 +
115 +**~ **
116 +
117 +**<digits> ::= <digit>**
118 +
119 +**~ | <digit> <digits>**
120 +
121 +**~ **
122 +
123 +**<digit> ::= "0"**
124 +
125 +**~ | <positive digit>**
126 +
127 +**~ **
128 +
129 +**<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"**
130 +
131 +**<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"**
132 +
133 +**~ | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"**
134 +
135 +**~ | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"**
136 +
137 +**~ | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"**
138 +
139 +**~ | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"**
140 +
141 +**~ | "y" | "z"**
142 +
143 +1.
144 +11. Dependency Management in SDMX 3.0(.0):
145 +
52 52  MAJOR, MINOR or PATCH version parts in SDMX 3.0 artefact references CAN be wildcarded using "+" as extension:
53 53  
54 -* X+.Y.Z means the currently latest available version >= X.Y.Z
55 -** Example: "2+.3.1" means the currently latest available version >="2.3.1" (even if not backwards compatible)
56 -** Typical use case: references in SDMX Categorisations
57 -* X.Y+.Z means the currently latest available backwards compatible version >=X.Y.Z
58 -** Example: "2.3+.1" means the currently latest available version >= "2.3.1" and < "3.0.0" (all backwards compatible versions >="2.3.1")
59 -** Typical use case: references in SDMX DSD
148 +* X+.Y.Z means the currently latest available version >= X.Y.Z o Example: "2+.3.1" means the currently latest available version >=
60 60  
150 +"2.3.1" (even if not backwards compatible) o Typical use case: references in SDMX Categorisations
151 +
152 +* X.Y+.Z means the currently latest available backwards compatible version >=
153 +
154 +X.Y.Z o Example: "2.3+.1" means the currently latest available version >= "2.3.1" and < "3.0.0" (all backwards compatible versions >=
155 +
156 +"2.3.1") o Typical use case: references in SDMX DSD
157 +
61 61  * X.Y.Z+ means the currently latest available forwards and backwards compatible version >= X.Y.Z o Example: "2.3.1+" means the currently latest available version >= "2.3.1" and < "2.4.0" (all forwards and backwards compatible versions >= "2.3.1")
62 62  * Non-versioned and 2-digit version SDMX structural artefacts CAN reference any other non-versioned or versioned (whether SemVer or not) SDMX structural artefacts.
63 63  * Semantically versioned artefacts MUST only reference other semantically versioned artefacts.
... ... @@ -74,7 +74,8 @@
74 74  
75 75  ~* means all available versions
76 76  
77 -== 14.5 Upgrade and conversions of artefacts defined with previous SDMX standard versions to Semantic Versioning ==
174 +1.
175 +11. Upgrade and conversions of artefacts defined with previous SDMX standard versions to Semantic Versioning
78 78  
79 79  Because SDMX standardises the interactions between statistical systems, which cannot all be upgraded at the same time, the new versioning rules cannot be applied to existing artefacts in EDIFACT, SDMX 1.0, 2.0 or 2.1. SemVer can only be applied to structural artefacts that are newly modelled with the SDMX 3.0 Information Model. Migrating to SemVer means migrating to the SDMX 3.0 Information Model, to its new API version and new versions of its exchange message formats.
80 80  
... ... @@ -84,11 +84,11 @@
84 84  
85 85  If artefact versioning is required and SDMX 3.0.0 Semantic Versioning is available within the tools and processes used, then it is recommended to switch to Semantic Versioning with the following steps:
86 86  
87 -~1. Complement the missing version parts with 0s to make the version number SemVer-compliant using the MAJOR.MINOR.PATCH-EXTENSION syntax:
185 +1. Complement the missing version parts with 0s to make the version number SemVer-compliant using the MAJOR.MINOR.PATCH-EXTENSION syntax:
88 88  
89 89  Example: Version 2 becomes version 2.0.0 and version 3.1 becomes version 3.1.0.
90 90  
91 -2. Replace the "isFinal=false" property by the version extensions "-draft" (or alternatively "-unstable" or "-nonfinal" depending on the use case).
189 +1. Replace the "isFinal=false" property by the version extensions "-draft" (or alternatively "-unstable" or "-nonfinal" depending on the use case).
92 92  
93 93  Example: Version 1.3 with isFinal=true becomes version 1.3.0 and version 1.3 with isFinal=false becomes version 1.3.0-draft.
94 94  
... ... @@ -96,7 +96,8 @@
96 96  
97 97  Note: Like for other not fully backwards compatible SDMX 3.0 features, also some cases of semantically versioned SDMX 3.0 artefacts cannot be converted back to earlier SDMX versions. This is the case when one or more extensions have been created in parallel to the corresponding stable version. In this case, only the stable version SHOULD be converted to a final version (e.g., 3.2.1 becomes 3.2.1 final, and 3.2.1-draft cannot be converted back).
98 98  
99 -== 14.6 FAQ for Semantic Versioning ==
197 +1.
198 +11. FAQ for Semantic Versioning
100 100  
101 101  **My organisation is new to SDMX and starts to implement 3.0 or starts to implement a new process fully based on SDMX 3.0. Which versioning scheme should be used?**
102 102  
... ... @@ -153,16 +153,24 @@
153 153  
154 154  One with named groups for those systems that support them (PCRE [Perl Compatible Regular Expressions, i.e. Perl, PHP and R], Python and Go).
155 155  
156 -Reduced version (without original SemVer "build metadata") from: [[https:~~/~~/regex101.com/r/Ly7O1x/3/>>url:https://regex101.com/r/Ly7O1x/3/]]
255 +Reduced version (without original SemVer "build metadata") from: [[https:~~/~~/regex101.com/r/Ly7O1x/3/>>url:https://regex101.com/r/Ly7O1x/3/]][[url:https://regex101.com/r/Ly7O1x/3/]]
157 157  
158 -> ^(?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-]*))*))?$
257 +^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-
159 159  
259 +9]\d*)(?:-(?P<extension>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-
260 +
261 +]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$
262 +
160 160  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.
161 161  
162 -Reduced version (without original SemVer "build metadata") from: [[https:~~/~~/regex101.com/r/vkijKf/1>>url:https://regex101.com/r/vkijKf/1/]]
265 +Reduced version (without original SemVer "build metadata") from: [[https:~~/~~/regex101.com/r/vkijKf/1/>>url:https://regex101.com/r/vkijKf/1/]][[url:https://regex101.com/r/vkijKf/1/]]
163 163  
164 -> ^(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-]*))*))?$
267 +^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-
165 165  
269 +9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-
270 +
271 +][0-9a-zA-Z-]*))*))?$
272 +
166 166  **Must I adopt semantic versioning rules when switching to SDMX 3.0?**
167 167  
168 168  No. If backwards compatibility with pre-existing tools and processes is required, then it is possible to continue using the previous versioning scheme (with up to two version parts MAJOR.MINOR). Semantic versioning is indicated only for those use cases where a proper artefact versioning is required. If versioning does not apply to some or all of your artefacts, then rather migrate to non-versioned SDMX 3.0 artefacts.
1750077413040-228.png
Author
... ... @@ -1,1 +1,0 @@
1 -xwiki:XWiki.helena
Size
... ... @@ -1,1 +1,0 @@
1 -70.3 KB
Content
1750077431756-519.png
Author
... ... @@ -1,1 +1,0 @@
1 -xwiki:XWiki.helena
Size
... ... @@ -1,1 +1,0 @@
1 -33.3 KB
Content