Skip to Content
Version 5.2 by Helena on 2025/07/03 11:28
Show last authors
1 {{box title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = 1 Introduction =
6
7 This document provides a brief overview of the SDMX-ML XML sample files.
8
9 All samples use the xsi:schemaLocation attribute to define the location of the XSD schema files for the relevant namespaces. The samples assume that the schemas are held locally in a directory called 'schemas' and are referenced as a relative file path. For example:
10
11 `xsi:schemaLocation="http://www.sdmx.org/resources/sdmxml/schemas/v3_1/message ../../schemas/SDMXMessage.xsd"`
12
13 Copies of the SDMX-ML XSD schemas files will need to be in the appropriate directory in order to validate correctly.
14
15 = 2 Structure Samples =
16
17 The Structure Samples provide examples of SDMX-ML messages within the *structure* namespace which is used for all structural metadata artefacts.
18
19 == Codelist ==
20
21 (% class="wikigeneratedid" id="Hcodelist.xml" %)
22 **codelist.xml**
23
24 A simple enumerated code list directly equivalent to those in version 2.1 and earlier.
25
26 This example shows the SDMX:CL_AGE 'Age' cross domain code list.
27
28 (% class="wikigeneratedid" id="Hcodelist-extended.xml" %)
29 **codelist - extended.xml**
30
31 Extended code list.
32
33 Illustration of the feature introduced in SDMX 3.0 allowing code lists to be defined as an extension of others. One use case envisaged is adding additional codes to standard cross domain code lists without needing to take and maintain an explicit copy.
34
35 The sample message has two codelists:
36
37 * SDMX:CL_AGE, a simple enumerated codelist; and
38 * EXAMPLE:CL_EXTENDED_AGE, an extension of SDMX:CL_AGE.
39
40 CL_EXTENDED_AGE defines two additional codes "I" and "S".
41
42 In addition, the ExclusiveCodeSelection option to exclude the "Y" code from the CL_AGE code list. The result is CL_AGE, minus "Y", plus "I" and "S". The InclusiveCodeSelection option could have been used if a specific set of codes were needed from CL_AGE.
43
44 (% class="wikigeneratedid" id="Hcodelist-discriminatedunion.xml" %)
45 **codelist - discriminated union.xml**
46
47 Discriminated union of code lists.
48
49 This sample illustrates the discriminated union of code lists use case where a classification or breakdown has multiple "variants" which are all valid or mutually exclusive.
50
51 Economic activity has been used with ISIC4 and NACE2 examples of two mutually exclusive variants.
52
53 In the sample:
54
55 * Code list extension is used to create a new EXAMPLE:CL_ACTIVITY code list consisting of both the SDMX:CL_ACTIVITY_NACE2 and SDMX:CL_ACTIVITY_ISIC4 codelists.
56 * The code list extension prefix feature has been used to prefix the NACE codes with "NACE2_", and similarly the ISIC codes with "ISIC4_". This ensures there is no ambiguity where the same code appear in both NACE and ISIC code lists.
57 * A data structure definition has been created with an enumerated ACTIVITY dimension using the EXAMPLE:CL_ACTIVITY code list.
58 * Two data flows are created referencing the data structure definition. One data flow has a data constraint attached with a CubeRegion for ACTIVITY and Value = "NACE2_%". The other has a similar data constraint with Value = "ISIC4_%". The "%" is the wildcard character for constraints introduced in version 3.0.
59
60 The discriminated unions are achieved by requesting either of the data flows with references="all" and detail="referencepartial". The result being CL_ACTIVITY with the extensions resolved and the relevant data constraint applied. Thus CL_ACTIVITY will only contain codes prefixed according to the data flow: either beginning "NACE2_" or "ISIC4_"
61
62 (% class="wikigeneratedid" id="Hvaluelist.xml" %)
63 **valuelist.xml**
64
65 A simple enumerated value list.
66
67 Value lists were introduced in version 3.0 to allow the definition of enumerations where the codes do not need to comply with the strict SDMX rules for identifiers. Thus a "value" can be any string of characters.
68
69 In SDMX-ML valuelists are treated as a class of enumeration so appear in the structure message under Codelists alongside simple and extended codelists, and specialised geospatial codelist variants.
70
71 Currency is used as the example with the values being currency symbols including "$", "£", "¥" and "﷼".
72
73 == Concept Scheme ==
74
75 (% class="wikigeneratedid" id="Hconceptscheme.xml" %)
76 **conceptscheme.xml**
77
78 The example illustrates a single concept scheme ECB:ECB_CONCEPTS containing multiple individual concepts.
79
80 ## Data Structure Definition##
81
82 **##ECB EXR.xml##**
83
84 The example illustrates a data structure definition (DSD) for ECB:EXR exchange rates. The concept of primary measure has been deprecated in SDMX 3.0 and the DSD's MeasureList can contain multiple measures. In this case, a single measure OBS_VALUE is defined.
85
86 ## Dataflow##
87
88 ##**dataflow.xml**##
89
90 A simple data flow for the ECB:EXR data set.
91
92 ## Geospatial##
93
94 **##geospatial geocomponents.xml ##**
95
96 An example of the use of the "GeospatialInformation" representation type. The GeospatialInformation type can be assigned to a Dimension, DataAttribute, MetadataAttribute or a Measure in conjunction with the "GEO" role. Values of are included directly in data messages or metadata reports and must conform to the Geo Feature Set syntax defined in Section 6 of the Technical Specifications.
97
98 In the sample:
99
100 * A simple illustrative data structure definition has been defined with IDENTIFIER and TIME_PERIOD dimensions, plus a series attribute AREA.
101 * The AREA attribute has the SDMX Concept Role "GEO" defined identifying it generally as a geospatial component following guidelines.
102 * The AREA attribute also carries a LocalRepresentation with textType="GeospatialInformation".
103
104 ### geospatial geographiccodelist.xml ##
105
106 An example of the definition of GeographicCodelists, a specialised form of code list introduced in SDMX 3.0. GeographicCodelists are used in the same was as simple code lists to assign a closed enumerated list of values to a component. The difference being that the definition of each GeoFeatureSetCode explicitly specifies the geospatial features to which it relates as a string expression using the Geo Feature Set syntax set out in Section 6 of the Technical Specifications. As with any other coded component, data sets only contain the codes and not the Feature Set information itself. Thus, GeoFeatureSetCodes act as pointers to the Geo Feature Set information held in the GeographicCodelist.
107
108 In the sample:
109
110 * A single illustrative GeographicCodelist has been defined which must be under Codelists in the structure message.
111 * The GeographicCodelist geoType attribute must be given the value of "GeographicCodelist".
112 * Three illustrative GeoFeatureSetCodes have been defined with IDs "A1", "A2" and "A3".
113 * The GeoFeatureSetCode Value attribute specifies the geospatial features to which the code relates as a string expression. Note that the values shown are conceptual examples and are not syntactically valid Geo Feature Set expressions.
114
115 ### geospatial geogridcodelist.xml ##
116
117 An example of the definition of GeoGridCodelists, the second specialised form of codelist for modelling gridded geographies.
118 Like GeographicCodelists, GeoGridCodelists act in the same way as simple code lists to assign a closed enumerated list of values to a component.
119 GeoGridCodelists define a geographical grid by setting the X and Y coordinates of a reference point, and the dimensions of each cell. In addition, each GeoGridCode specifies to which cell in the grid it relates using row and column numbers.
120
121 In the sample:
122
123 * A single illustrative GeoGridCodelist has been defined which must be under Codelists in the structure message.
124 * The GridDefinition element defines the grid for the code list using a string expression conforming to the Geo Grid syntax set out in Section 6 of the Technical Specifications.
125 * Each GeoGridCode has an ID and a Name in common with the codes of simple code lists, but also has a GeoCell element containing the row and column of the grid cell as a string expression using the Grid Cell syntax set out in Section 6 of the Technical Specifications.
126
127 ## VTL Transformations##
128
129 ### VTL Sample 1.xml ##
130
131 Illustrates the use of VTL Rulesets to validate an SDMX dataflow. The validation process adds additional identifiers and measures to the resulting VTL dataset indicating, on a row by row basis the validation rule applied and the outcome in terms of a valid / invalid. If invalid, details of the error found and its severity are added.
132
133 A second transformation takes the resulting dataset filtering out high-severity validation errors and persists the result back to a SDMX dataflow using VTL mappings.
134
135 ### VTL Sample 2.xml ##
136
137 Illustrates aggregation of an SDMX dataflow using VTL hierarchical rulesets, filtering and user defined operators.
138
139 After the initial aggregation, unaggregated observations removed are removed from the result dataset. A user defined operator is subsequently applied to calculate a percentage measure with the final persistent result mapped from VTL to a SDMX dataflow.
140
141 ### VTL Sample 3.xml ##
142
143 Illustrates the calculation of a GDP per capita dataset from an input mapped SDMX dataflow containing GDP and population indicators on a country by country basis.
144
145 = 3 Data Samples =
146
147 SDMX-ML 3.0 has a single format for data transmission - the Structure Specific Data message. Alternative formats from version 2.1 and earlier such as Generic, Utility and Cross Sectional are deprecated.
148
149 The Structure Specific Data message is characterised by the XML elements and attributes being derived from the data structure definition of the data set. This provides two main benefits:
150
151 1. The message content is relatively compact.
152 2. It is possible to use an XML schema to validate that the data set contains the correct values as defined by the data structure definition and any constraints attached to the dataflow, data structure definition or data provision agreement.
153
154 The samples therefore include both the Structure Specific Data XML, and a corresponding example validation schema XSD. Successful schema validation confirms that the XML is both a valid Structure Specific Data message, and the content is valid according to the SDMX structural metadata.
155
156 == Aggregated Time Series with Simple Data Attributes ==
157
158 ### ECB EXR.xml ##
159
160 Structure specific data message.
161
162 Excerpt from the ECB's Exchange Rates dataset.
163
164 In this example which is representative of aggregated time-series datasets with a single measure, observations are grouped together under series, which in turn are grouped under the dataset element.
165
166 The dimension values and those of series-level attributes are expressed as XML attributes on each series element. Similarly, the TIME_PERIOD, OBS_VALUE and any observation-level attributes are expressed as XML attributes on each obs element.
167
168 Note that a structure specific namespace ns1 is defined using xsi:schemalocation to reference the validation schema location, in this case ECB_EXR_Dataflow.xsd.
169
170 ### ECB EXR Dataflow.xsd ##
171
172 Structure-specific schema for validating the dataset.
173
174 The schema defines a complex type called DataSetType derived from the data set's data structure definition and constraints, in this case those attached to the dataflow.
175
176 ## Aggregated Time Series with Complex Data Attributes##
177
178 Complex attributes include those with multilingual text and arrays of values.
179
180 ### EXB EXR CA.xml ##
181
182 Structure specific data message.
183
184 A modification of the ECB's Exchange Rates dataset illustrating the following complex attribute use cases:
185
186 TITLE - multi-lingual series-level array attribute
187
188 SOURCE_AGENCY - coded series-level array attribute specifying a minimum of three values
189
190 SOURCE_PUB - uncoded string series-level array attribute with maximum length of 350 characters
191
192 OBS_STATUS - coded observation-level array attribute
193
194 Note that a structure specific namespace ns1 is defined using xsi:schemalocation to reference the validation schema location, in this case ECB_EXR_Dataflow.xsd.
195
196 ### ECB EXR CA Dataflow.xsd ##
197
198 Structure specific schema for validating the dataset.
199
200 The schema defines a complex type called DataSetType derived from the data set's data structure definition and constraints, in this case those attached to the dataflow.
201
202 Complex types based on the abstract dsd:CompType are defined for each complex attribute.
203
204 ### ECB EXR CA DSD.xml ##
205
206 Structure message describing the Data Structure Definition for the above dataflow illustrating, in particular, the definition of complex attributes:
207
208 The XML attribute isMultiLingual="true" on the \<str:TextFormat…\> element specifies a multi-lingual string representation.
209
210 Setting the maxOccurs XML attribute to a number greater than 1 (or unbounded) on the \<str:LocalRepresentation…\> element specifies an array.