Skip to Content
Last modified by Helena on 2025/09/10 11:19
From version 3.2
edited by Helena
on 2025/05/16 10:57
Change comment: There is no comment for this version
To version 3.8
edited by Helena
on 2025/05/16 11:02
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -21,10 +21,7 @@
21 21  The following rules apply to versioned artefacts:
22 22  
23 23  * All versioned SDMX artefacts MUST specify a version number.
24 -* The version number of immutable versioned SDMX artefacts MUST take the form X.Y.Z where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the MAJOR version, Y is the MINOR version, and Z is the PATCH version. Each element MUST increase numerically. For instance:
25 -
26 -1.9.0 -> 1.10.0 -> 1.11.0.
27 -
24 +* The version number of immutable versioned SDMX artefacts MUST take the form X.Y.Z where X, Y, and Z are non-negative integers and MUST NOT contain leading zeroes. X is the MAJOR version, Y is the MINOR version, and Z is the PATCH version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
28 28  * Once an SDMX artefact with an X.Y.Z version has been shared externally or publicly released, the contents of that version MUST NOT be modified. That artefact version is considered stable. Any modifications MUST be released as a new version.
29 29  * MAJOR version zero (0.y.z) is for initial modelling. Anything MAY change at any time. The externally released or public artefact SHOULD NOT be considered stable.
30 30  * Version 1.0.0 defines the first stable artefact. The way in which the version number is incremented after this release is dependent on how this externally released or public artefact changes.
... ... @@ -31,50 +31,39 @@
31 31  * PATCH version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible property changes are introduced. A property change is defined as an internal change that does not affect the relationship to other artefacts. These are changes in the artefact's or artefact element's names, descriptions and annotations that MUST NOT alter their meaning.
32 32  * MINOR version Y (x.Y.z | x > 0) MUST be incremented if a new, backwards compatible element is introduced to a stable artefact. These are additional items in ItemScheme artefacts. It MAY be incremented if substantial new information is introduced within the artefact's properties. It MAY include PATCH level changes. PATCH version MUST be reset to 0 when MINOR version is incremented.
33 33  * MAJOR version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to a stable artefact. These often relate to deletions of items in ItemSchemes or to backwards incompatibility introduced due to changes in references to other artefacts. A MAJOR version change MAY also include MINOR and PATCH level changes. PATCH and MINOR version MUST be reset to 0 when MAJOR version is incremented.
34 -* A mutable version, e.g. used for externally released or public drafts or as prerelease, MUST be denoted by appending an EXTENSION that consists of a hyphen and a series of dot separated identifiers immediately following the PATCH version (x.y.z-EXT). Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. However, to foster harmonisation and general comprehension it is generally recommended to use the standard EXTENSION "**-draft**". Extended versions have a lower precedence than the associated stable version. An extended version indicates that the version is unstable and it might not satisfy the intended compatibility requirements as denoted by its associated stable version. When making changes to an SDMX artefact with an extended version number then one is not required to increment the version if those changes are kept within the allowed scope of the version increment from the previous version (if that existed), otherwise also here the before mentioned version increment rules for X.Y.Z apply. Concretely, a version X.0.0-EXT will allow for any changes, a version X.Y.0-EXT will allow only for MINOR changes and a version X.Y.Z-EXT will allow only for any PATCH changes, as defined above. EXTENSION examples:
35 -
36 -1.0.0-draft, 1.0.0-draft.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
37 -
38 -* Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into MAJOR, MINOR, PATCH and EXTENSION identifiers in that order. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: MAJOR, MINOR, and PATCH versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When MAJOR, MINOR, and PATCH are equal, an extended version has lower precedence than a stable version. Example: 1.0.0-draft < 1.0.0. Precedence for two extended versions with the same MAJOR, MINOR, and PATCH version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of EXTENSION fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-draft <
39 -
40 -1.0.0-draft.1 < 1.0.0-draft.prerelease < 1.0.0-prerelease < 1.0.0-prerelease.2 <
41 -
42 -1.0.0-prerelease.11 < 1.0.0-rc.1 < 1.0.0.
43 -
31 +* A mutable version, e.g. used for externally released or public drafts or as prerelease, MUST be denoted by appending an EXTENSION that consists of a hyphen and a series of dot separated identifiers immediately following the PATCH version (x.y.z-EXT). Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. However, to foster harmonisation and general comprehension it is generally recommended to use the standard EXTENSION "**-draft**". Extended versions have a lower precedence than the associated stable version. An extended version indicates that the version is unstable and it might not satisfy the intended compatibility requirements as denoted by its associated stable version. When making changes to an SDMX artefact with an extended version number then one is not required to increment the version if those changes are kept within the allowed scope of the version increment from the previous version (if that existed), otherwise also here the before mentioned version increment rules for X.Y.Z apply. Concretely, a version X.0.0-EXT will allow for any changes, a version X.Y.0-EXT will allow only for MINOR changes and a version X.Y.Z-EXT will allow only for any PATCH changes, as defined above. EXTENSION examples: 1.0.0-draft, 1.0.0-draft.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
32 +* Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into MAJOR, MINOR, PATCH and EXTENSION identifiers in that order. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: MAJOR, MINOR, and PATCH versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When MAJOR, MINOR, and PATCH are equal, an extended version has lower precedence than a stable version. Example: 1.0.0-draft < 1.0.0. Precedence for two extended versions with the same MAJOR, MINOR, and PATCH version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of EXTENSION fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-draft < 1.0.0-draft.1 < 1.0.0-draft.prerelease < 1.0.0-prerelease < 1.0.0-prerelease.2 < 1.0.0-prerelease.11 < 1.0.0-rc.1 < 1.0.0.
44 44  * The reasons for version changes MAY be documented in brief form in an artefact's annotation of type "CHANGELOG".
45 45  
46 46  == 14.3 Backus–Naur Form Grammar for Valid SDMX 3.0(.0) Semantic Versions ==
47 47  
37 +[[image:1747382317063-468.png]]
38 +[[image:1747382367401-937.png||height="321" width="637"]]
48 48  
49 49  == 14.4 Dependency Management in SDMX 3.0(.0): ==
50 50  
51 51  MAJOR, MINOR or PATCH version parts in SDMX 3.0 artefact references CAN be wildcarded using "+" as extension:
52 52  
53 -* X+.Y.Z means the currently latest available version >= X.Y.Z o Example: "2+.3.1" means the currently latest available version >=
54 -
55 -"2.3.1" (even if not backwards compatible) o Typical use case: references in SDMX Categorisations
56 -
57 -* X.Y+.Z means the currently latest available backwards compatible version >=
58 -
59 -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 >=
60 -
61 -"2.3.1") o Typical use case: references in SDMX DSD
62 -
63 -* 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")
44 +* X+.Y.Z means the currently latest available version >= X.Y.Z
45 +** Example: "2+.3.1" means the currently latest available version >="2.3.1" (even if not backwards compatible)
46 +** Typical use case: references in SDMX Categorisations
47 +* X.Y+.Z means the currently latest available backwards compatible version >=X.Y.Z
48 +** Example: "2.3+.1" means the currently latest available version >= "2.3.1" and < "3.0.0" (all backwards compatible versions >="2.3.1")
49 +** Typical use case: references in SDMX DSD
50 +* X.Y.Z+ means the currently latest available forwards and backwards compatible version >= X.Y.Z
51 +** 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")
64 64  * Non-versioned and 2-digit version SDMX structural artefacts CAN reference any other non-versioned or versioned (whether SemVer or not) SDMX structural artefacts.
65 65  * Semantically versioned artefacts MUST only reference other semantically versioned artefacts.
66 66  * Wildcarded references in a stable artefact implicitly target only future stable versions of the referenced artefacts within the defined wildcard scope.
67 -** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an artefact "AGENCY_ID:DSD_ID(2.2.1)" resolves to artefact
68 -
69 -"AGENCY_ID:CODELIST_ID(2.4.3)" if that was currently the latest available stable version.
70 -
71 -* Wildcarded references in a version-extended artefact implicitly target future stable and version-extended versions of the referenced artefacts within the defined wildcard scope. o Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an artefact "AGENCY_ID:DSD_ID(2.2.1-draft)" resolves to artefact "AGENCY_ID:CODELIST_ID(2.5.0-draft)" if that was currently the latest available version.
55 +** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an artefact "AGENCY_ID:DSD_ID(2.2.1)" resolves to artefact "AGENCY_ID:CODELIST_ID(2.4.3)" if that was currently the latest available stable version.
56 +* Wildcarded references in a version-extended artefact implicitly target future stable and version-extended versions of the referenced artefacts within the defined wildcard scope.
57 +** Example: The reference to "AGENCY_ID:CODELIST_ID(2.3+.1)" in an artefact "AGENCY_ID:DSD_ID(2.2.1-draft)" resolves to artefact "AGENCY_ID:CODELIST_ID(2.5.0-draft)" if that was currently the latest available version.
72 72  * References to specific version-extended artefacts MAY be used, but those cannot be combined with a wildcard.
73 73  ** Example: The reference to "AGENCY_ID:CODELIST_ID(2.5.0draft)" in an artefact "AGENCY_ID:DSD_ID(2.2.1)" resolves to artefact "AGENCY_ID:CODELIST_ID(2.5.0-draft)", which might be subject to continued backwards compatible changes.
74 74  
75 75  Because both, wildcarded references and references to version-extended artefacts, allow for changes in the referenced artefacts, care needs to be taken when choosing the appropriate references in order to achieve the required limitation in the allowed scope of changes.
76 76  
77 -For references to non-dependent artefacts, MAJOR, MINOR or PATCH version parts in SDMX 3.0 artefact references CAN alternatively be wildcarded using "*" as replacement:
63 +For references to non-dependent artefacts, MAJOR, MINOR or PATCH version parts in SDMX 3.0 artefact references CAN alternatively be wildcarded using "*" as replacement:
78 78  
79 79  ~* means all available versions
80 80  
... ... @@ -90,11 +90,11 @@
90 90  
91 91  1. Complement the missing version parts with 0s to make the version number SemVer-compliant using the MAJOR.MINOR.PATCH-EXTENSION syntax:
92 92  
93 -Example: Version 2 becomes version 2.0.0 and version 3.1 becomes version 3.1.0.
79 + Example: Version 2 becomes version 2.0.0 and version 3.1 becomes version 3.1.0.
94 94  
95 95  1. Replace the "isFinal=false" property by the version extensions "-draft" (or alternatively "-unstable" or "-nonfinal" depending on the use case).
96 96  
97 -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.
83 + 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.
98 98  
99 99  If artefact versioning is required but semantic versioning cannot be applied, then version strings used in previous versions of the Standard (e.g., version=1.2) may continue to be used.
100 100  
1747382317063-468.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.helena
Size
... ... @@ -1,0 +1,1 @@
1 +57.9 KB
Content
1747382367401-937.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.helena
Size
... ... @@ -1,0 +1,1 @@
1 +27.6 KB
Content