Skip to Content

Wiki source code of 10 Constraints

Version 5.1 by Helena on 2025/05/15 15:48
Show last authors
1 = 10 Constraints =
2
3 == 10.1 Introduction ==
4
5 A Constraint is a Maintainable Artefact that can be associated to one or more of:
6
7 * Data Structure Definition
8 * Metadata Structure Definition
9 * Dataflow
10 * Metadataflow
11 * Provision Agreement
12 * Metadata Provision Agreement
13 * Data Provider or Metadata Provider (this is restricted to a Release Calendar Constraint)
14 * Simple or Queryable Data Sources
15 * Dataset
16 * Metadataset
17
18 Note that regardless of the Artefact to which the Constraint is associated, it is constraining the contents of code lists in the DSD to which the constrained object is related. This does not apply, of course, to a Metadata/Data Provider as the latter can be associated, via the (Metadata) Provision Agreement, to many MSDs/DSDs. Hence the reason for the restriction on the type of Constraint that can be attached to a Metadata/Data Provider.
19
20 == 10.2 Types of Constraint ==
21
22 The Constraint can be of one of two types:
23
24 * Data constraint
25 * Metadata constraint
26
27 The Data Constraint may serve two different perspectives, depending on the way the latter is retrieved. These are:
28
29 * Allowed constraint
30 * Actual constraint
31
32 The former (allowed – also valid for Metadata Constraint) is specified by a data or metadata provider or consumer for sharing the allowed data and metadata in the context of their DSD or MSD exchanges, e.g., only Monthly data for a specific Dataflow. The latter (actual) is a dynamic Constraint in response to an availability request (only possible for data).
33
34 For Actual Data Constraints, there a few characteristics that are worth noting:
35
36 * They can only be retrieved by the availability requests (as specified in the REST API).
37 * They depend on the data available in an SDMX Web Service and thus they can only be dynamically generated according to that data.
38 * Although they are Maintainable Artefacts, they cannot change independently of data; thus, they cannot be versioned (they are non-versioned, as explained in section 14).
39 * Their identifier may also be dynamically generated and thus there is no REST resource based on their identification.
40
41 == 10.3 Rules for a Constraint ==
42
43 === 10.3.1 Scope of a Constraint ===
44
45 A Constraint is used specify the content of a data or metadata source in terms of the component values or the keys.
46
47 In terms of data the components are:
48
49 * Dimension
50 * Time Dimension
51 * Data Attribute
52 * Measure
53 * Metadata Attribute
54 * DataKeySets: the keys are the content of the KeyDescriptor – i.e., the series keys composed, for each key, by a value for each Dimension.
55
56 In terms of reference metadata the components are:
57
58 * Metadata Attribute
59
60 For a Constraint based on a DSD the Constraint can reference one or more of:
61
62 * Data Structure Definition
63 * Dataflow
64 * Provision Agreement
65 * Data Provider
66
67 For a Constraint based on an MSD the Constraint can reference one or more of:
68
69 * Metadata Structure Definition
70 * Metadataflow
71 * Metadata Provision Agreement
72 * Metadata Provider
73 * Metadata Set
74
75 Furthermore, there can be more than one Constraint specified for a specific object e.g., more than one Constraint for a specific DSD.
76
77 In view of the flexibility of constraints attachment, clear rules on their usage are required. These are elaborated below.
78
79 === 10.3.2 Multiple Constraints ===
80
81 There can be many Constraints for any Constrainable Artefact (e.g., DSD), subject to the following restrictions:
82
83 **10.3.2.1 Cube Region**
84
85 A Constraint can contain multiple Member Selections (e.g., Dimensions).
86
87 * A specific Member Selection (e.g., Dimension FREQ) can only be contained in one Cube Region for any one attached object (e.g., a specific DSD or specific Dataflow).
88 * Component values within a Member Selection may define a validity period. Otherwise, the value is valid for the whole validity of the Cube Region.
89 * For partial reference resolution purposes (as per the SDMX REST API), the latest non-draft Constraint must be considered.
90 * 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.
91 * 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.
92
93 **10.3.2.2 Key Set**
94
95 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").
96
97 As the Key Sets can be "included" or "excluded" it is recommended that Key Sets with wildcards are declared before KeySets with specific series keys. This will minimize the risk that keys are inadvertently included or excluded.
98
99 In addition, Attribute, Measure and Metadata Attribute constraints may accompany KeySets, in order to specify the allowed values per Key. Those are expressed following the rules for Cube Regions, as explained above.
100
101 Finally, a validity period may be specified per Key.
102
103 === 10.3.3 Inheritance of a Constraint ===
104
105 **10.3.3.1 Attachment levels of a Constraint**
106
107 There are three levels of constraint attachment for which these inheritance rules apply:
108
109 • DSD/MSD – top level o Dataflow/Metadataflow – second level
110
111 ▪ Provision Agreement – third level
112
113 Note that these rules do not apply to the Simple Datasource or Queryable Datasource; the Constraint(s) attached to these artefacts are resolved for this artefact only and do not take into account Constraints attached to other artefacts (e.g., Provision Agreement, Dataflow, DSD).
114
115 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.
116
117 **10.3.3.2 Cascade rules for processing Constraints**
118
119 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.
120
121 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.
122
123 **10.3.3.3 Cube Region**
124
125 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:
126
127 * The lower-level Constraint cannot be less restrictive than the Constraint specified for the same Member Selection (e.g. Dimension) at the next higher level, which constrains that Member Selection. For example, if the Dimension FREQ is constrained to A, Q in a DSD, then the Constraint at the Dataflow or Provision Agreement cannot be A, Q, M or even just M – it can only further constrain A, Q.
128 * The Constraint at the lower level for any one Member Selection further constrains the content for the same Member Selection at the higher level(s).
129 * Any Member Selection, which is not referenced in a Constraint, is deemed to be constrained according to the Constraint specified at the next higher level which constraints that Member Selection.
130 * If there is a conflict when resolving the Constraint in terms of a lower-level Constraint being less restrictive than a higher-level Constraint, then the Constraint at the higher-level is used.
131
132 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.
133
134 **10.3.3.4 Key Set**
135
136 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:
137
138 * The lower-level Constraint cannot be less restrictive than the Constraint specified at the higher level.
139 * The Constraint at the lower level for any one Member Selection further constrains the keys specified at the higher level(s).
140 * Any Member Selection, which is not referenced in a Constraint, is deemed to be constrained according to the Constraint specified at the next higher level which constraints that Member Selection.
141 * If there is a conflict when resolving the keys in the Constraint at two levels, in terms of a lower-level constraint being less restrictive than a higher-level Constraint, then the offending keys specified at the lower level are not deemed part of the Constraint.
142
143 Note that a Key in a Key Set can have wildcarded Components. For instance, the Constraint may simply constrain the Dimension FREQ to "A", and all keys where the FREQ="A" are therefore valid.
144
145 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.
146
147 *
148 *1. Determine all possible keys that are valid at the higher level.
149 *1. These keys are deemed to be inherited by the lower-level constrained object, subject to the Constraints specified at the lower level.
150 *1. Determine all possible keys that are possible using the Constraints specified at the lower level.
151 *1. At the lower level inherit all keys that match with the higher-level Constraint.
152 *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).
153
154 === 10.3.4 Constraints Examples ===
155
156 **10.3.4.1 Data Constraint and Cascading **The following scenario is used.
157
158 A DSD contains the following Dimensions:
159
160 * GEO – Geography
161 * SEX – Sex
162 * AGE – Age
163 * CAS – Current Activity Status
164
165 In the DSD, common code lists are used and the requirement is to restrict these at various levels to specify the actual code that are valid for the object to which the Constraint is attached.
166
167 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_77bea5e.png||height="344" width="554"]]
168
169 **Figure 20: Example Scenario for Constraints **Constraints are declared as follows:
170
171 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_7c36c475.png||height="356" width="541"]]
172
173 **Figure 21: Example Constraints**
174
175 Notes:
176
177 AGE is constrained for the DSD and is further restricted for the Dataflow CENSUS_CUBE1.
178
179 * The same Constraint applies to both Provision Agreements.
180
181 The cascade rules elaborated above result as follows:
182
183 DSD
184
185 * Constrained by eliminating code 001 from the code list for the AGE Dimension.
186
187 Dataflow CENSUS_CUBE1
188
189 * Constrained by restricting the code list for the AGE Dimension to codes 002 and 003 (note that this is a more restrictive constraint than that declared for the DSD which specifies all codes except code 001).
190 ** Restricts the CAS codes to 003 and 004.
191
192 Dataflow CENSUS_CUBE2
193
194 * Restricts the code list for the CAS Dimension to codes TOT and NAP.
195 ** Inherits the AGE constraint applied at the level of the DSD.
196
197 Provision Agreement CENSUS_CUBE1_IT
198
199 * Restricts the codes for the GEO Dimension to IT and its children.
200 ** Inherits the constraints from Dataflow CENSUS_CUBE1 for the AGE and CAS Dimensions.
201
202 Provision Agreement CENSUS_CUBE2_IT
203
204 * Restricts the codes for the GEO Dimension to IT and its children.
205 ** Inherits the constraints from Dataflow CENSUS_CUBE2 for the CAS Dimension.
206 ** Inherits the AGE constraint applied at the level of the DSD.
207
208 The Constraints are defined as follows:
209
210 DSD Constraint
211
212 **<str:DataConstraint agencyID="SDMX" id="DATA_CONSTRAINT" version="1.0.0draft" type="Allowed">**
213
214 **<com:Name xml:lang="en">SDMX 3.0 Data Constraint sample</com:Name>**
215
216 **<str:ConstraintAttachment>**
217
218 **<str:DataStructure>urn:sdmx:org.sdmx.infomodel.datastructure.**
219
220 **DataStructure=CENSUSHUB:CENSUS(1.0.0)</str:DataStructure>**
221
222 **</str:ConstraintAttachment>**
223
224 **<str:CubeRegion include="true">**
225
226 **<!~-~- the ability to exclude values is illustrated – i.e., all values valid except this one ~-~->**
227
228 **<com:KeyValue id="AGE" include="false">**
229
230 **<com:Value>001</com:Value>**
231
232 **</com:KeyValue>**
233
234 **</str:CubeRegion>**
235
236 **</str:DataConstraint>**
237
238 Dataflow Constraints
239
240 **<str:DataConstraint agencyID="SDMX" id="DATA_CONSTRAINT_2" version="1.0.0draft" type="Allowed">**
241
242 **<com:Name xml:lang="en">SDMX 3.0 Data Constraint sample</com:Name>**
243
244 **<str:ConstraintAttachment>**
245
246 **<str:Dataflow>urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=**
247
248 **CENSUSHUB:CENSUS_CUBE1(1.0.0)</str:Dataflow>**
249
250 **</str:ConstraintAttachment>**
251
252 **<str:CubeRegion include="true">**
253
254 **<com:KeyValue id="AGE" include="true">**
255
256 **<com:Value>002</com:Value>**
257
258 **<com:Value>003</com:Value>**
259
260 **</com:KeyValue>**
261
262 **<com:KeyValue id="CAS">**
263
264 **<com:Value>003</com:Value>**
265
266 **<com:Value>004</com:Value>**
267
268 **</com:KeyValue>**
269
270 **</str:CubeRegion>**
271
272 **</str:DataConstraint>**
273
274 **<str:DataConstraint agencyID="SDMX" id="DATA_CONSTRAINT_3" version="1.0.0draft" type="Allowed">**
275
276 **<com:Name xml:lang="en">SDMX 3.0 Data Constraint sample</com:Name>**
277
278 **<str:ConstraintAttachment>**
279
280 **<str:Dataflow>urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=**
281
282 **CENSUSHUB:CENSUS_CUBE2(1.0.0)</str:Dataflow>**
283
284 **</str:ConstraintAttachment>**
285
286 **<str:CubeRegion include="true">**
287
288 **<com:KeyValue id="CAS" include="true">**
289
290 **<com:Value>TOT</com:Value>**
291
292 **<com:Value>NAP</com:Value>**
293
294 **</com:KeyValue>**
295
296 **</str:CubeRegion>**
297
298 **</str:DataConstraint>**
299
300 Provision Agreement Constraint
301
302 **<str:DataConstraint agencyID="SDMX" id="DATA_CONSTRAINT_4" version="1.0.0draft" type="Allowed">**
303
304 **<com:Name xml:lang="en">SDMX 3.0 Data Constraint sample</com:Name>**
305
306 **<str:ConstraintAttachment>**
307
308 **<str:ProvisionAgreement>urn:sdmx:org.sdmx.infomodel.registry.**
309
310 **ProvisionAgreement=CENSUSHUB:CENSUS_CUBE1_IT(1.0.0)**
311
312 **</str:ProvisionAgreement>**
313
314 **<str:ProvisionAgreement>urn:sdmx:org.sdmx.infomodel.registry.**
315
316 **ProvisionAgreement=CENSUSHUB:CENSUS_CUBE2_IT(1.0.0)**
317
318 **</str:ProvisionAgreement>**
319
320 **</str:ConstraintAttachment>**
321
322 **<str:CubeRegion include="true">**
323
324 **<com:KeyValue id="GEO" include="true">**
325
326 **<com:Value cascadeValues="true">IT</com:Value>**
327
328 **</com:KeyValue>**
329
330 **</str:CubeRegion>**
331
332 **</str:DataConstraint**
333
334 **10.3.4.2 Combination of Constraints**
335
336 The possible combination of constraining terms are explained in this section, following a few examples.
337
338 Let’s assume a DSD with the following Components:
339
340 |Dimension|FREQ
341 |Dimension|JD_TYPE
342 |Dimension|JD_CATEGORY
343 |Dimension|VIS_CTY
344 |TimeDimension|TIME_PERIOD
345 |Attribute|OBS_STATUS
346 |Attribute|UNIT
347 |Attribute|COMMENT
348 |MetadataAttribute|CONTACT
349 |Measure|MULTISELECT
350 |Measure|CHOICE
351
352 On the above, let’s assume the following use cases with their constraining requirements:
353
354 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_6b13e05d.png||height="12" width="62"]] //**Use Case 1: A Constraint on allowed values for some Dimensions**//
355
356 R1: Allow monthly and quarterly data
357
358 R2: Allow Mexico for vis-à-vis country
359
360 This is expressed with the following CubeRegion:
361
362 |FREQ|M, Q
363 |VIS_CTY|MX
364
365 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_18c3726e.png||height="12" width="64"]] //**Use Case 2: A Constraint on allowed combinations for some Dimensions**//
366
367 R1: Allow monthly data for Germany
368
369 R2: Allow quarterly data for Mexico
370
371 This is expressed with the following DataKeySet:
372
373 |(% rowspan="2" %)Key1|FREQ|M
374 |VIS_CTY|DE
375 |(% rowspan="2" %)Key2|FREQ|Q
376 |VIS_CTY|MX
377
378 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_8d48dc1a.png||height="12" width="64"]] //**Use Case 3: A Constraint on allowed values for some Dimensions combined with allowed values for some Attributes**//
379
380 R1: Allow monthly and quarterly data
381
382 R2: Allow Mexico for vis-à-vis country
383
384 R3: Allow present for status
385
386 This may be expressed with the following CubeRegion:
387
388 |FREQ|M, Q
389 |VIS_CTY|MX
390 |OBS_STATUS|A
391
392 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_a0d353e8.png||height="12" width="64"]] //**Use Case 4: A Constraint on allowed combinations for some**//
393
394 //**Dimensions combined with specific Attribute values**//
395
396 R1: Allow monthly data, for Germany, with unit euro
397
398 R2: Allow quarterly data, for Mexico, with unit usd
399
400 This is may be expressed with the following DataKeySet:
401
402 |(% rowspan="3" %)Key1|FREQ|M
403 |VIS_CTY|DE
404 |UNIT|EUR
405 |(% rowspan="3" %)Key2|FREQ|Q
406 |VIS_CTY|MX
407 |UNIT|USD
408
409 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_6e97b73c.png||height="12" width="64"]] //**Use Case 5: A Constraint on allowed values for some Dimensions together with some combination of Dimension values**//
410
411 R1: For annually and quarterly data, for Mexico and Germany, only A status is allowed
412
413 R2: For monthly data, for Mexico and Germany, only F status is allowed
414
415 Considering the above examples, the following CubeRegions would be created:
416
417 |(% rowspan="3" %)CubeRegion1|FREQ|Q, A
418 |VIS_CTY|MX, DE
419 |OBS_STATUS|A
420 |(% rowspan="3" %)CubeRegion2|FREQ|M
421 |VIS_CTY|MX, DE
422 |OBS_STATUS|F
423
424 The problem with this approach is that according to the business rule for Constraints, only one should be specified per Component. Thus, if a software would perform some conflict resolution would end up with empty sets for FREQ and OBS_STATUS (as they do not share any values).
425
426 Nevertheless, there is a much easier approach to that; this is the cascading mechanism of Constraints (as shown in 10.3.4.1). Hence, these rules would be expressed into two levels of Constraints, e.g., DSD and Dataflows:
427
428 DSD CubeRegion:
429
430 |FREQ|M, Q, A
431 |VIS_CTY|MX, DE
432 |OBS_STATUS|A, F
433
434 Dataflow1 CubeRegion:
435
436 |FREQ|Q, A
437 |VIS_CTY|MX, DE
438 |OBS_STATUS|F
439
440 Dataflow2 CubeRegion:
441
442 |FREQ|M
443 |VIS_CTY|MX, DE
444 |OBS_STATUS|A
445
446 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_b4693e0d.png||height="12" width="64"]] //**Use case 6: A Constraint on allowed values for some Dimensions combined with allowed values for Measures**//
447
448 R1: Allow monthly data, for Germany, with unit euro, and measure choice is 'A'
449
450 R2: Allow quarterly data, for Mexico, with unit usd, and measure choice is 'B' This is may be expressed with the following DataKeySet:
451
452 |(% rowspan="4" %)Key1|FREQ|M
453 |VIS_CTY|DE
454 |UNIT|EUR
455 |CHOICE|A
456 |(% rowspan="4" %)Key2|FREQ|Q
457 |VIS_CTY|MX
458 |UNIT|USD
459 |CHOICE|B
460
461 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_9818c7f7.png||height="12" width="64"]] //**Use Case 7: A Constraint with wildcards for Codes and removePrefix property**//
462
463 For this example, we assume that the VIS_CTY representation has been prefixed with prefix ‘AREA_’. In this Constraint, we need to remove the prefix.
464
465 R1: Allow monthly and quarterly data
466
467 R2: Allow vis-à-vis countries that start with M
468
469 R3: Remove the prefix ‘AREA_’
470
471 This may be expressed with the following CubeRegion:
472
473 |FREQ|M, Q
474 |VIS_CTY (removePrefix=’AREA_’)|M%
475
476 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_7df2eea7.png||height="12" width="64"]] //**Use Case 8: A Constraint with multilingual support on Attributes**//
477
478 R1: Allow monthly and quarterly data
479
480 R2: Allow Mexico for vis-à-vis country
481
482 R3: Allow a comment, in English, which includes the term adjusted for status
483
484 This may be expressed with the following CubeRegion:
485
486 |FREQ|M, Q
487 |VIS_CTY|MX
488 |COMMENT (lang=’en’)|%adjusted%
489
490 [[image:SDMX 3-0-0 SECTION 6 FINAL-1.0_en_7e57ad28.png||height="12" width="64"]] //**Use Case 9: A Constraint on allowed values for Dimensions combined with allowed values for Metadata Attributes**//
491
492 R1: Allow monthly and quarterly data
493
494 R2: Allow Mexico for vis-à-vis country
495
496 R3: Allow John Doe for contact
497
498 This may be expressed with the following CubeRegion:
499
500 |FREQ|M, Q
501 |VIS_CTY|MX
502 |CONTACT|John Doe
503
504 **10.3.4.3 Other constraining terms**
505
506 Beyond the cube regions and keysets, there is one more constraining term, i.e., the ReleaseCalendar.
507
508 The ReleaseCalendar is the only term that does not apply on Components; it specifies the schedule of publication or reporting of the dataset or metadataset.
509
510 For example, the ReleaseCalendar for Provider BIS, is specified in the three following terms:
511
512 * Periodicity: how often data should be reported, e.g., monthly
513 * Offset: the number of days between the 1^^st^^ of January and the first release of data, e.g., 10 days
514 * Tolerance: the maximum allowed of days that data may be considered, without being considered as late, e.g., 5 days
515
516 With the above terms, BIS would need to report data between the 10^^th^^ and 15^^th^^ of every month.
517
518 NOTE: The SDMX 2.1 constraining term ReferencePeriod has been deprecated in SDMX 3.0; thus, the TimeDimension and any Dimension with a time Representation can be constrained within a CubeRegion or MetadataTargetRegion, using the TimeRangeValue.