Skip to Content

Wiki source code of 16 Annex 6: Worked Use Case

Version 1.2 by Artur on 2025/05/20 14:28
Show last authors
1 {{box title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 == 16.1 Scope ==
6
7 The scope of this Chapter is to show the SDMX-ML interactions with the Registry, database, and metadata repository for the use case scenario outlined in Chapter 3. The scenario is repeated below.
8
9 The SDMX-ML examples used are version 2.1.
10
11 == 16.2 Scenario ==
12
13 This scenario is the dissemination of data and related reference metadata using SDMX web services. It shows how the data, reference metadata, and structural metadata are used to build a web dissemination system.
14
15 (% style="text-align: center;" %)
16 [[image:image-20250318221512-1.jpeg||data-xwiki-image-style-alignment="center"]]
17
18 (% style="text-align: center;" %)
19 **{{id name="image_47"/}}Figure 47: Process flow of an SDMX Web Data Dissemination System**
20
21 (% style="width:753.446px" %)
22 |**Process**|(% style="width:670px" %)**Description**
23 |1|(% style="width:670px" %)Retrieve the DSD from a structural metadata source (e.g. an SDMX Registry), and create database tables.
24 |2|(% style="width:670px" %)Read an SDMX data set file and load the data into the database
25 |3|(% style="width:670px" %)Data discovery system continually synchronises its metadata with the structural metadata source. A user makes a data selection from choices built from the information held in an SDMX Registry (structural metadata such as category scheme, dataflow, DSD, data provider, provision agreements and data registration)
26 |3|(% style="width:670px" %)These choices are logical choices, built from the dimension selections.
27 |5|(% style="width:670px" %)The logical choice is formatted as an SDMX data query. This is passed to the Data Base which responds with an SDMX data set.
28 |6|(% style="width:670px" %)Reference metadata relevant to the data returned is retrieved from a metadata repository.
29 |7|(% style="width:670px" %)The data and metadata are passed to a visualization tool to display the data in tables, charts, graphs, maps etc. Often a download is offered in various formats. The download options often include also the DSD or MSD.
30
31 == 16.3 Structural Metadata ==
32
33 === 16.3.1 Schematic ===
34
35 The following structural metadata and provisioning metadata is used in the scenario.
36
37 (% style="text-align: center;" %)
38 [[image:image-20250318221512-2.jpeg||data-xwiki-image-style-alignment="center"]]
39
40 (% style="text-align: center;" %)
41 **{{id name="image_48"/}}Figure 48: Structural and Provisioning Metadata Used in the Scenario**
42
43 === 16.3.2 Data Structure Definition ===
44
45 For the reasons of clarity a sub set of the contents of the Code Lists and Concept Schemes are used in this example, and only a few of the DSD Attributes are used.
46
47 ===== **Dimensions** =====
48
49 (% style="text-align: center;" %)
50 [[image:image-20250318221512-3.jpeg]]** **
51
52 ===== **Attributes** =====
53
54 (% style="text-align: center;" %)
55 [[image:image-20250318221512-4.jpeg]]** **
56
57 ===== **Group** =====
58
59 (% style="text-align: center;" %)
60 [[image:image-20250318221512-5.jpeg]]** **
61
62 ===== **Primary Measure** =====
63
64 (% style="text-align: center;" %)
65 [[image:image-20250318221512-6.jpeg]]** **
66
67 == 16.4 Scenario Steps ==
68
69 === 16.4.1 Create Data Base ===
70
71 (% style="text-align: center;" %)
72 [[image:image-20250318221512-7.jpeg||data-xwiki-image-style-alignment="center"]]
73
74 (% style="text-align: center;" %)
75 **{{id name="image_49"/}}Figure 49: User Case - Create Database Tables from DSD**
76
77 The following SDMX-ML is extracted from the Registry using the REST query http:~/~/[ ws-entry-point]/DataStructure_ECB/ECB_EXR1
78
79 ===== Dimensions =====
80
81 (% style="text-align: center;" %)
82 [[image:image-20250318221512-8.jpeg||data-xwiki-image-style-alignment="center"]]
83
84 Note that for brevity only the XML of the FREQ and TIME_PERIOD are shown in full.
85
86 ===== **Notes** =====
87
88 1. A Dimension can state its position in the key, but the actual sequence is defined by the sequence in the <DimensionList> i.e. the inferred sequence in the <DimensionList> takes precedence over the value of the position attribute.
89 1. This DSD is converted from version 2.0. The version 2.0 Concepts were standalone in the form  <Concept agencyID=”ECB” version=”1.0”/>
90 1. The standalone concept is not supported in 2.1 and any standalone concept is placed in a Concept Scheme with the Id “STANDALONE_CONCEPT_SCHEME” of the version corresponding to the version of the original standalone concept.
91
92 ===== **Group** =====
93
94 (% style="text-align: center;" %)
95 [[image:image-20250318221512-9.jpeg]]** **
96
97 **Notes:**
98
99 1. A Group in version 2.1 plays the same role as it does in version 2.0 except that it does not group Series in the data set. The Group in version 2.1 is used solely as a mechanism to attach Attributes in the data set.
100 1. The Group in version 2.1 is retained for compatibility with version 2.0 and for avoiding repetition in the new Attribute Relationship construct which is introduced in version 2.1.
101
102 ===== Attributes =====
103
104 (% style="text-align: center;" %)
105 [[image:image-20250318221512-10.jpeg||data-xwiki-image-style-alignment="center"]]
106
107 (% style="text-align: center;" %)
108 [[image:image-20250318221512-11.jpeg||data-xwiki-image-style-alignment="center"]]
109
110 Note that for brevity only the XML of the DECIMALS (relationship to a group) COLLECTION (relationship to a set of Dimensions) and OBS_CONF (relationship to the Primary Measure) are shown in full.
111
112 ===== **Notes** =====
113
114 1. The Attribute has a relationship to either a data set of one or more Dimensions as described in Chapter 4.
115 1. DECIMALS has a relationship to a Group with the Id of Group.
116 1. COLLECTION has a relationship to a set of Dimensions – in this case this is, in reality, the series key as this has been converted from version 2.0. It is possible for an attribute to have a relationship with just one, a few, or all of the Dimensions.
117 1. OBS_CONF has a relationship with the Primary Measure.
118
119 ===== **Measure** =====
120
121 (% style="text-align: center;" %)
122 [[image:image-20250318221512-12.jpeg||data-xwiki-image-style-alignment="center"]]
123
124 A typical database schema that can be set up using this DSD is shown below.
125
126 ===== **Series Key Table** =====
127
128 (% style="text-align: center;" %)
129 [[image:image-20250318221902-34.png||data-xwiki-image-style-alignment="center"]]
130
131 (% style="text-align: center;" %)
132 **{{id name="image_50"/}}Figure 50: Relational Table Structure created from a DSD Dimensions and Related Attributes**
133
134 ===== **Group “Group” Table** =====
135
136 (% style="text-align: center;" %)
137 [[image:image-20250318221512-13.jpeg]]** **
138
139 (% style="text-align: center;" %)
140 **{{id name="image_51"/}}Figure 51: Relational Table Structure created from a DSD Group and Related Attributes**
141
142 ===== **Observation** =====
143
144 (% style="text-align: center;" %)
145 [[image:image-20250318221512-14.jpeg||data-xwiki-image-style-alignment="center"]]
146
147 (% style="text-align: center;" %)
148 **{{id name="image_52"/}}Figure 52: Relational Table Structure created from a DSD Primary Measure and Related Attributes**
149
150 === 16.4.2 Load Database ===
151
152 (% style="text-align: center;" %)
153 [[image:image-20250318221512-15.jpeg||data-xwiki-image-style-alignment="center"]]
154
155 (% style="text-align: center;" %)
156 **{{id name="image_53"/}}Figure 53: Loading an SDMX Dataset into a Database **
157
158 The following is an extract from the SDMX dataset.
159
160 (% style="text-align: center;" %)
161 [[image:image-20250319123255-1.png||data-xwiki-image-style-alignment="center"]]
162
163 (% style="text-align: center;" %)
164 [[image:image-20250319123339-2.png||data-xwiki-image-style-alignment="center"]]
165
166 Note that this is a sub set of the actual data message.
167
168 ===== **Notes** =====
169
170 1. The reference to the DSD is given in the message header and given a local structureId
171 1. The local structureId (DSD) is referenced from the DataSet
172 1. A Group does not contain Series in version 2.1: it is used solely to declare attributes
173 1. The first <Obs> in the first <Series> has an OBS_VALUE of “NaN”. This is an XML expression that declared a value of “not a number”, thus allowing a “missing value” to be declared.
174 1. A dataset can contain observations from different frequencies.
175
176 The diagrams below show the database content based on the schema created.
177
178 ===== **Series Key Table** =====
179
180 (% style="text-align: center;" %)
181 [[image:image-20250318221512-16.jpeg||data-xwiki-image-style-alignment="center"]]
182
183 ===== **Group Table** =====
184
185 (% style="text-align: center;" %)
186 [[image:image-20250318221512-17.jpeg||data-xwiki-image-style-alignment="center"]]
187
188 ===== **Observation Table** =====
189
190 (% style="text-align: center;" %)
191 [[image:image-20250318221512-18.jpeg]]** **
192
193 The database is now available for query.
194
195 === 16.4.3 Register Data Source ===
196
197 The following registration is submitted to the Registry.
198
199 (% style="text-align: center;" %)
200 [[image:image-20250318221512-19.jpeg||data-xwiki-image-style-alignment="center"]]
201
202 The SDMX web service of the database can now be searched for in the Registry.
203
204 === 16.4.4 Retrieve and Visualise Category Scheme and Dataflows ===
205
206 (% style="text-align: center;" %)
207 [[image:image-20250318221512-20.jpeg||data-xwiki-image-style-alignment="center"]]
208
209 (% style="text-align: center;" %)
210 **{{id name="image_54"/}}Figure 54: Building a Search Screen from Structural Metadata**
211
212 The following REST query will return the Category Scheme and Categorisations that reference any of the Categories in the scheme.
213
214 [[http:~~/~~/ ~[ws-entry-point~]/categoryscheme/ECB/SDW_ECONOMIC_CONCEPTS/1.0?references=parents>>http:// [ws-entry-point]/categoryscheme/ECB/SDW_ECONOMIC_CONCEPTS/1.0?references=parents||rel="noopener noreferrer" target="_blank"]]
215
216 (% style="text-align: center;" %)
217 [[image:image-20250318221512-21.jpeg||data-xwiki-image-style-alignment="center"]]
218
219 (% style="text-align: center;" %)
220 [[image:image-20250318221512-22.jpeg||data-xwiki-image-style-alignment="center"]]
221
222 The application will now retrieve the Dataflows in the list of Categorisations – in this case there is only one – effective exchange rates.
223
224 The following REST query will return the dataflow.
225
226 [[http:~~/~~/ ~[ws-entry-point~]/dataflow/ECB/2034482/1.0>>http:// [ws-entry-point]/dataflow/ECB/2034482/1.0||rel="noopener noreferrer" target="_blank"]]
227
228 (% style="text-align: center;" %)
229 [[image:image-20250318221512-23.jpeg||data-xwiki-image-style-alignment="center"]]
230
231 The actual choreography of the query application is dependent upon the implementation but the following is assumed for this example.
232
233 1. Query application queries the Registry for the Provision Agreement.
234 1. Query application queries the Registry for data Registrations.
235 1. If there is a data source registered then the dataflow is displayed and can be selected.
236
237 The following REST query will return any provision agreements referenced from the dataflow
238
239 [[http:~~/~~/~[ws-entry-point~]/dataflow/ECB/2034482/1.0?references=provisionagreement>>http://[ws-entry-point]/dataflow/ECB/2034482/1.0?references=provisionagreement||rel="noopener noreferrer" target="_blank"]]
240
241 (% style="text-align: center;" %)
242 [[image:image-20250318221512-24.jpeg||data-xwiki-image-style-alignment="center"]]
243
244 ===== **Notes** =====
245
246 ~1. The <URN> contains the same identification information as the individual attributes in the <Ref> tag in the context of the <Dataflow> and <Structure> tags (the <Dataflow> identifies that the <Structure> is a DataStructure).
247
248 The following REST query will return the Data Provider Scheme that contains the Data Provider connected to the Provision Agreement. Note that this is not necessary in order to query for the data unless the Data Provider contains information required by the query application (such as the name of the Data Provider).
249
250 [[http:~~/~~/~[ws-entry-point~]/dataprovider/ECB>>http://[ws-entry-point]/dataprovider/ECB||rel="noopener noreferrer" target="_blank"]]
251
252 ===== **Notes** =====
253
254 ~1. As an Agency can have only one Data Provider Scheme and this has a mandatory Id of DATA_PROVIDER_SCHEME and must be version 1.0 there is no need to specify any other parameters to the REST query.
255
256 This returns the following as part of the Data Provider Scheme.
257
258 (% style="text-align: center;" %)
259 [[image:image-20250318221512-25.jpeg||data-xwiki-image-style-alignment="center"]]
260
261 The following Registry query will return the REST data source referenced in a Registration for the Provision Agreement
262
263 (% style="text-align: center;" %)
264 [[image:image-20250318221512-26.jpeg||data-xwiki-image-style-alignment="center"]]
265
266 The response from this query is:
267
268 (% style="text-align: center;" %)
269 [[image:image-20250318221512-27.jpeg||data-xwiki-image-style-alignment="center"]]
270
271 The query application now has the details of the web service to call when making a query, and it also knows that the query expected uses the REST interface.
272
273 [[http:~~/~~/~[ws-entry-point~] /~[RESTParameters~]>>http://[ws-entry-point] /[RESTParameters||rel="noopener noreferrer" target="_blank"]]]
274
275 Where [ws-entry-point] is the URL of the SDMX web service and [RESTParameters] are the query parameters.
276
277 The application can now visualize the information it has retrieved from the Registry in a way that is meaningful to the user. An example visualization is shown below.
278
279 (% style="text-align: center;" %)
280 [[image:image-20250318221512-28.jpeg||data-xwiki-image-style-alignment="center"]]
281
282 (% style="text-align: center;" %)
283 **{{id name="image_55"/}}Figure 55: Example Query Screen Built from SDMX Category Scheme and Dataflows**
284
285 The user will select the Category and this then shows the Dataflows that are available and which have data available for query (i.e. there is a Registration). There can be many such Dataflows but in this example there is only one.
286
287 === 16.4.5 Build Dimension Selection and Logical Query ===
288
289 (% style="text-align: center;" %)
290 [[image:image-20250318221512-29.jpeg||data-xwiki-image-style-alignment="center"]]
291
292 Clicking on the Dataflow will cause the query application to query the Registry for the DSD associated to the Dataflow. The Dimensions and the relevant codes associated with the Dimensions are then shown for detailed data selections.
293
294 (% style="text-align: center;" %)
295 [[image:image-20250318221512-30.jpeg||data-xwiki-image-style-alignment="center"]]
296
297 (% style="text-align: center;" %)
298 **{{id name="image_56"/}}Figure 56: Selection Screen build from SDMX DSD**
299
300 The user can click on each of the Dimensions and the relevant code selections are displayed. Note that in the example above the application is assumed to have queries for all the keys so that it can process them in order to grey-out the Dimension selections for which there is no data. These are greyed-out based on the current selections in the other Dimensions. This shows the importance of content constraints in a web dissemination system, as they can be used to guide the user to make only the selections that will return data. The same result can be achieved if these constraints are available for query (e.g. in a Registry), but this is a less effective way of processing if the contenrts of the database are dynamic.
301
302 === 16.4.6 Query Database ===
303
304 (% style="text-align: center;" %)
305 [[image:image-20250318221512-31.jpeg||data-xwiki-image-style-alignment="center"]]
306
307 The logical query of the user is converted to an SDMX query and sent to the Data Web Service of the data publisher. The Data Web Service may also query the Metadata Repository in order to return both data and related metadata to the user application. The Data Web Service may also require structural metadata (DSD and MSD and related Code Lists and Concepts) from the structural metadata repository, in this example this an SDMX Registry.
308
309 ===== **Data Query Logical Selections** =====
310
311 (% style="width:551.446px" %)
312 |(% style="width:261px" %)**Dimension**|(% style="width:286px" %)**Values**
313 |(% style="width:261px" %)FREQ|(% style="width:286px" %)M
314 |(% style="width:261px" %)CURRENCY|(% style="width:286px" %)Z26,Z28
315 |(% style="width:261px" %)CURRENCY_DENOM|(% style="width:286px" %)EUR,CZK,DKK
316 |(% style="width:261px" %)EXR-TYPE|(% style="width:286px" %)DFCO,EN00
317 |(% style="width:261px" %)EXR_SUFFIX|(% style="width:286px" %)A
318 |(% style="width:261px" %)Time|(% style="width:286px" %)Jan 2008-Dec 2010
319
320 ===== **REST Query** =====
321
322 [[http:~~/~~/ws-entry-point/data/2034482/M.Z26+Z28.EUR+CZK+DKK.DFC0+EN00+A /ECB?startPeriod=2008-01&endPeriod=2010-12&detail=dataonly>>http://ws-entry-point/data/2034482/M.Z26+Z28.EUR+CZK+DKK.DFC0+EN00+A /ECB?startPeriod=2008-01&endPeriod=2010-12&detail=dataonly||rel="noopener noreferrer" target="_blank"]]
323
324 === 16.4.7 Visualise the Resultant Data Set ===
325
326 (% style="text-align: center;" %)
327 [[image:image-20250318221512-32.jpeg||data-xwiki-image-style-alignment="center" height="310" width="346"]]
328
329 The returned data and metadata can be presented to the user in many ways – tables, graphs, charts, maps etc. SDMX does not support visualization directly but it is possible to define roles for a Dimension and Attribute in the DSD. For instance, it is possible to assign a role of “Geography” or “Title” or “Measure Unit” etc. which will aid a data visualization service to present this information in a meaningful way to the user.
330
331 (% style="text-align: center;" %)
332 [[image:image-20250318221512-33.jpeg||data-xwiki-image-style-alignment="center"]]
333
334 (% style="text-align: center;" %)
335 **{{id name="image_57"/}}Figure 57: Example Graph Built from Data Returned from a Query**