Skip to Content

Changes for page 10 Constraints

Last modified by Artur on 2025/09/10 11:19
From version 1.5
edited by Helena
on 2025/06/16 12:13
Change comment: There is no comment for this version
To version 1.1
edited by Helena
on 2025/06/16 12:03
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -2,7 +2,8 @@
2 2  {{toc/}}
3 3  {{/box}}
4 4  
5 -== 10.1 Introduction ==
5 +1.
6 +11. Introduction
6 6  
7 7  Constraints are used as a way to restrict what data can be reported, or to report what data exists in a given context.  There are three types of Constraint, which serve different purposes
8 8  
... ... @@ -18,7 +18,8 @@
18 18  
19 19  A Reporting Constraint is used to define the set of allowed and/or disallowed values that can be reported in a data or metadata set.
20 20  
21 -== 10.2 Availability Constraint ==
22 +1.
23 +11. Availability Constraint
22 22  
23 23  An Availability Constraint is not a maintained structure, instead it is generated dynamically as a response to the availability REST API. The purpose of the Availability Constraint is to define the distinct set of values that have data over 1 or more Dimensions.  Unlike a Data and Metadata Constraint, which can attach to multiple Constrainable structures (of the same type), an Availability Constraint can only attach to only one structure.  The attachment defines the context of the response (data exists for components in the context of).  The subset of Constrainable structures the Availability Constraint can attach to are:
24 24  
... ... @@ -25,18 +25,17 @@
25 25  * Data Structure Definition
26 26  * Dataflow
27 27  * Provision Agreement
30 +*1. Dimension Constraint
28 28  
29 -== 10.3 Dimension Constraint ==
30 -
31 31  A Dimension Constraint is a property of a Dataflow; its purpose is to explicitly list the Dimensions from the corresponding DSD that are being used by the Dataflow. 
32 32  
33 -Dimension Constraints were introduced in SDMX 3.1 and are not required for most Dataflows where the dataset must always contain the full complement of Dimensions as defined by the corresponding DSD. However, for some complex data collections, which may span long periods and where the full complement of required Dimensions are not necessarily known at design time, the DSD is subject to increasing its Dimensionality over time.  In this scenario it is possible to define the DSD as an evolving structure, this property tells the user that the DSD can have new Dimensions added without having to undergo a major version change; a DSD at version 1.0.0 for example would be able to add a new Dimension and move to version 1.1.0; a change that would not ordinarily be allowed.  A minor version change on the addition of a new Dimension is only possible if the DSD defines itself as an evolving structure.   This is a new property of the DSD introduced in version 3.1 to satisfy this use case.  The evolving structure  property is either true or false, defaulting to false if not specified.  Setting the evolving structure property to true requires a major version change, and therefore can only be introduced on an x.0.0 release (e.g. 1.0.0).  The evolving structure property can be set to false to indicate that there will be no additional Dimensions added to the Data Structure under the same major version number; setting the evolving structure property to false does not require require a major version change on the Data Structure.   
34 +Dimension Constraints were introduced in SDMX 3.1 and are not required for most Dataflows where the dataset must always contain the full complement of Dimensions as defined by the corresponding DSD. However, for some complex data collections, which may span long periods and where the full complement of required Dimensions are not necessarily known at design time, the DSD is subject to increasing its Dimensionality over time.  In this scenario it is possible to define the DSD as an evolving structure, this property tells the user that the DSD can have new Dimensions added without having to undergo a major version change; a DSD at version 1.0.0 for example would be able to add a new Dimension and move to version 1.1.0; a change that would not ordinarily be allowed.  A minor version change on the addition of a new Dimension is only possible if the DSD defines itself as an evolving structure.   This is a new property of the DSD introduced in version 3.1 to satisfy this use case.  The evolving structure  property is either true or false, defaulting to false if not specified.  Setting the evolving structure property to true requires a major version change, and therefore can only be introduced on an x.0.0 release (e.g. 1.0.0).  The evolving structure property can be set to false to indicate that there will be no additional Dimensions added to the Data Structure under the same major version number; setting the evolving structure property to false does not require require a major version change on the Data Structure.  
34 34  
35 35  When a Dataflow references a DSD, late binding on the minor release, and the DSD has the evolving structure property set to true, then the Dataflow must contain a Dimension Constraint to protect its Dimensionality from changing over time without a version change. 
36 36  
37 37  The Dimension Constraint provides the explicit list of Dimensions that the Dataflow uses from the DSD that it references.  This enables the DSD to evolve over time without breaking the compatibility of datasets against the Dataflow. 
38 38  
39 -__**Rules for a Dimension Constraint**__
40 +==== Rules for a Dimension Constraint ====
40 40  
41 41  * A Dataflow must contain a Dimension Constraint if the DSD which it uses states that it is an evolving structure and the Dataflow is late binding on the minor release (latest minor release of a given major version, e.g. 1.0+.0)
42 42  * The Dimension Constraint can only include Dimensions from the DSD that is referenced by the Dataflow.
... ... @@ -45,20 +45,23 @@
45 45  * When exporting data for the Dataflow, the dataset should only include the Dimensions specified by the Dimension Constraint.
46 46  * When exporting data for the DSD the dataset must contain the full set of Dimensions as specified by the DSD. The tilde ‘~~’ character is used to represent a value which is not present due to the Dimension not being included in the corresponding Dataflow.
47 47  
48 -__**Example Datasets with Evolving Structures**__
49 +==== Example Datasets with Evolving Structures ====
49 49  
50 -A dataset is built against a Data Structure Definition.  The dataset contains data for two Dataflows.  Dataflows ‘DF_POP’ uses a Dimension Constraint which fixes its Dimensions to  FREQ and REF_AREA.  Dataflow ‘DF_POP_SA’ does not reference a Dimension Constraint, and as such includes all Dimensions as specified by the DSD.  
51 +A dataset is built against a Data Structure Definition.  The dataset contains data for two Dataflows.  Dataflows ‘DF_POP’ uses a Dimension Constraint which fixes its Dimensions to  FREQ and REF_AREA.  Dataflow ‘DF_POP_SA’ does not reference a
51 51  
53 +Dimension Constraint, and as such includes all Dimensions as specified by the DSD.  
54 +
52 52  The resulting dataset contains values ‘~~’ for both the SEX and AGE Dimension for the series related to DF_POP.
53 53  
54 -(% style="width:758.294px" %)
55 -|(% style="width:119px" %)**Dataflow**|(% colspan="7" style="width:635px" %)**FREQ REF_AREA SEX AGE OBS_VALUE TIME_PERIOD UNIT**
56 -|(% style="width:119px" %)**DF_POP**|(% style="width:55px" %)A|(% style="width:103px" %)UK|(% style="width:79px" %)~~|(% style="width:92px" %)~~|(% style="width:93px" %)65|(% style="width:111px" %)2022|(% style="width:101px" %)6
57 -|(% style="width:119px" %)**DF_POP**|(% style="width:55px" %)A|(% style="width:103px" %)FR|(% style="width:79px" %)~~|(% style="width:92px" %)~~|(% style="width:93px" %)50|(% style="width:111px" %)2022|(% style="width:101px" %)6
58 -|(% style="width:119px" %)**DF_POP_SA**|(% style="width:55px" %)A|(% style="width:103px" %)UK|(% style="width:79px" %)M|(% style="width:92px" %)1|(% style="width:93px" %)1.2|(% style="width:111px" %)2022|(% style="width:101px" %)6
59 59  
60 -== 10.4 Reporting Constraints ==
58 +|**Dataflow**|(% colspan="7" %)**FREQ REF_AREA SEX AGE OBS_VALUE TIME_PERIOD UNIT**
59 +|**DF_POP**|A|UK|~~|~~|65|2022|6
60 +|**DF_POP**|A|FR|~~|~~|50|2022|6
61 +|**DF_POP_SA**|A|UK|M|1|1.2|2022|6
61 61  
63 +1.
64 +11. Reporting Constraints
65 +
62 62  A Reporting Constraint is a Maintainable Artefact which restricts the values that can be reported in a dataset or metadata set based on one or more inclusion or exclusion rules. 
63 63  
64 64  A reporting constraint is one of the following concrete types:
... ... @@ -65,9 +65,9 @@
65 65  
66 66  * Data Constraint
67 67  * Metadata Constraint
72 +*1.
73 +*11. Data Constraint
68 68  
69 -=== 10.4.1 Data Constraint ===
70 -
71 71  A Data Constraint is used to add additional restrictions to the allowable values reported in a dataset.  Data Constraints can be applied to the follow structures which are collectively known as Constrainable structures:
72 72  
73 73  * Data Structure Definition
... ... @@ -77,7 +77,9 @@
77 77  
78 78  **Note** regardless of the Constrainable structure, the restricted values relate to  the allowable content for the Component of the DSD to which the constrained object relates. 
79 79  
80 -=== 10.4.2 Metadata Constraint ===
84 +1.
85 +11.
86 +111. Metadata Constraint
81 81  
82 82  A Metadata Constraint is used to add additional restrictions to the allowable values reported in a metadataset.  Metadata Constraints can be applied to the follow structures which are collectively known as Constrainable structures:
83 83  
... ... @@ -88,7 +88,9 @@
88 88  
89 89  **Note** regardless of the Constrainable structure,  the restricted values relate to  the allowable content for the Component of the MSD to which the constrained object relates. 
90 90  
91 -=== 10.4.3 Scope of a Constraint ===
97 +1.
98 +11.
99 +111. Scope of a Constraint
92 92  
93 93  A Constraint is used specify the content of a data or metadata source in terms of the component values or the keys.
94 94  
... ... @@ -124,11 +124,13 @@
124 124  
125 125  In view of the flexibility of constraints attachment, clear rules on their usage are required. These are elaborated below.
126 126  
127 -=== 10.4.4 Multiple Constraints ===
135 +1.
136 +11.
137 +111. Multiple Constraints
128 128  
129 129  There can be many Constraints for any Constrainable Artefact (e.g., DSD), subject to the following restrictions:
130 130  
131 -==== 10.4.4.1 Cube Region ====
141 +**10.4.4.1 Cube Region**
132 132  
133 133  A Constraint can contain multiple Member Selections (e.g., Dimensions).
134 134  
... ... @@ -138,7 +138,7 @@
138 138  * A Member Selection may include wildcarding of values (using character ‘%’ to represent zero or more occurrences of any character), as well as cascading through hierarchic structures (e.g., parents in Codelist), or localised values (e.g., text for English only). Lack of locale means any language may match. Cascading values are mutual exclusive to localised values, as the former refer to coded values, while the latter refer to uncoded values.
139 139  * Any values included in a Member Selection for Components with an array data type (i.e., Measures, Attributes or Metadata Attributes), will be applied as single values and will not be assessed combined with other values to match all possible array values. For example, including the Code ‘A’ for an Attribute will allow any instance of the Attribute that includes ‘A’, like [‘A’, ‘B’] or [‘A’, ‘C’, ‘D’]. Similarly, if Code ‘A’ was excluded, all those arrays of values would also be excluded.
140 140  
141 -==== 10.4.4.2 Key Set ====
151 +**10.4.4.2 Key Set**
142 142  
143 143  Key Sets will be processed in the order they appear in the Constraint and wildcards can be used (e.g., any key position not reference explicitly is deemed to be "all values").
144 144  
... ... @@ -148,7 +148,9 @@
148 148  
149 149  Finally, a validity period may be specified per Key.
150 150  
151 -=== 10.4.4 Versioning ===
161 +1.
162 +11.
163 +111. Versioning
152 152  
153 153  When Data and Metadata Constraints are versioned, the latest version of the Constraint is used to generate the reporting restriction rules; all previous versions are for historical information only.
154 154  
... ... @@ -158,41 +158,41 @@
158 158  
159 159  Data Constraint 1.0.0
160 160  
161 -(% style="width:573.294px" %)
162 -|(% style="width:108px" %)Component|(% style="width:127px" %)Valid Value|(% style="width:150px" %)Valid from|(% style="width:185px" %)Valid to
163 -|(% rowspan="3" style="width:108px" %)COUNTRY|(% style="width:127px" %)UK|(% style="width:150px" %) |(% style="width:185px" %)
164 -|(% style="width:127px" %)FR|(% style="width:150px" %) |(% style="width:185px" %)
165 -|(% style="width:127px" %)DE|(% style="width:150px" %) |(% style="width:185px" %)
173 +|Component|Valid Value|Valid from|Valid to
174 +|(% rowspan="3" %)COUNTRY|UK| |
175 +|FR| |
176 +|DE| |
166 166  
167 167  Data Constraint 1.1.0
168 168  
169 -(% style="width:576.294px" %)
170 -|(% style="width:110px" %)Component|(% style="width:129px" %)Valid Value|(% style="width:145px" %)Valid from|(% style="width:189px" %)Valid to
171 -|(% rowspan="3" style="width:110px" %)COUNTRY|(% style="width:129px" %)UK|(% style="width:145px" %) |(% style="width:189px" %)
172 -|(% style="width:129px" %)FR|(% style="width:145px" %) |(% style="width:189px" %)2012
173 -|(% style="width:129px" %)DE|(% style="width:145px" %) |(% style="width:189px" %)
180 +|Component|Valid Value|Valid from|Valid to
181 +|(% rowspan="3" %)COUNTRY|UK| |
182 +|FR| |2012
183 +|DE| |
174 174  
175 175  When both versions of the Data Constraint are in a system, an observation value reported against COUNTRY FR for time period 2013 would be deemed invalid as the 1.1.0 rule would be applied.
176 176  
177 -=== 10.4.6 Inheritance ===
187 +1.
188 +11.
189 +111. Inheritance
178 178  
179 -==== 10.4.6.1 Attachment levels of a Constraint ====
191 +**10.4.6.1 Attachment levels of a Constraint**
180 180  
181 181  There are three levels of constraint attachment for which these inheritance rules apply:
182 182  
183 -* DSD/MSD – top level
184 -** Dataflow/Metadataflow – second level
185 -*** Provision Agreement – third level
195 +• DSD/MSD – top level o Dataflow/Metadataflow – second level
186 186  
197 +§ Provision Agreement – third level
198 +
187 187  It is not necessary for a Constraint to be attached to a higher level artefact. e.g., it is valid to have a Constraint for a Provision Agreement where there are no constraints attached the relevant Dataflow or DSD.
188 188  
189 -==== 10.4.6.2 Cascade rules for processing Constraints ====
201 +**10.4.6.2 Cascade rules for processing Constraints**
190 190  
191 191  The processing of the constraints on either Dataflow/Metadataflow or Provision Agreement must take into account the constraints declared at higher levels. The rules for the lower-level constraints (attached to Dataflow/ Metadataflow and Provision Agreement) are detailed below.
192 192  
193 193  Note that there can be a situation where a constraint is specified at a lower level before a constraint is specified at a higher level. Therefore, it is possible that a higher-level constraint makes a lower-level constraint invalid. SDMX makes no rules on how such a conflict should be handled when processing the constraint for attachment. However, the cascade rules on evaluating constraints for usage are clear – the higher-level constraint takes precedence in any conflicts that result in a less restrictive specification at the lower level.
194 194  
195 -==== 10.4.6.3 Cube Region ====
207 +**10.4.6.3 Cube Region**
196 196  
197 197  It is not necessary to have a Constraint on the higher-level artefact (e.g., DSD referenced by the Dataflow), but if there is such a Constraint at the higher level(s) then:
198 198  
... ... @@ -203,7 +203,7 @@
203 203  
204 204  Note that it is possible for a Constraint at a higher level to constrain, say, four Dimensions in a single Constraint, and a Constraint at a lower level to constrain the same four in two, three, or four Constraints.
205 205  
206 -==== 10.4.6.4 Key Set ====
218 +**10.4.6.4 Key Set**
207 207  
208 208  It is not necessary to have a Constraint on the higher-level artefact (e.g., DSD referenced by the Dataflow), but if there is such a Constraint at the higher level(s) then:
209 209  
... ... @@ -216,18 +216,16 @@
216 216  
217 217  The following logic explains how the inheritance mechanism works. Note that this is conceptual logic and actual systems may differ in the way this is implemented.
218 218  
219 -1. Determine all possible keys that are valid at the higher level.
220 -1. These keys are deemed to be inherited by the lower-level constrained object, subject to the Constraints specified at the lower level.
221 -1. Determine all possible keys that are possible using the Constraints specified at the lower level.
222 -1. At the lower level inherit all keys that match with the higher-level Constraint.
223 -1. If there are keys in the lower-level Constraint that are not inherited then the key is invalid (i.e., it is less restrictive).
231 +1.
232 +11. Determine all possible keys that are valid at the higher level.
233 +11. These keys are deemed to be inherited by the lower-level constrained object, subject to the Constraints specified at the lower level.
234 +11. Determine all possible keys that are possible using the Constraints specified at the lower level.
235 +11. At the lower level inherit all keys that match with the higher-level Constraint.
236 +11. If there are keys in the lower-level Constraint that are not inherited then the key is invalid (i.e., it is less restrictive).
237 +111. Constraints Examples
224 224  
225 -=== 10.4.7 Constraints Examples ===
239 +**10.4.7.1 Data Constraint and Cascading **The following scenario is used.
226 226  
227 -==== 10.4.7.1 Data Constraint and Cascading ====
228 -
229 -The following scenario is used.
230 -
231 231  A DSD contains the following Dimensions:
232 232  
233 233  * GEO – Geography
... ... @@ -270,6 +270,8 @@
270 270  * Restricts the codes for the GEO Dimension to IT and its children.
271 271  ** Inherits the constraints from Dataflow CENSUS_CUBE1 for the AGE and CAS Dimensions.
272 272  
283 +
284 +
273 273  Provision Agreement CENSUS_CUBE2_IT
274 274  
275 275  * Restricts the codes for the GEO Dimension to IT and its children.