Skip to Content
Version 1.2 by Helena K. on 2026/01/15 23:02
Hide last authors
Helena K. 1.1 1 {{box title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = DOCUMENT HISTORY =
6
7 |**Version**|**Date**|**Comment**
8 |1.0|01/03/2021|Initial version.
9 |2.0|24/04/2025|Adapted to SDMX 3.0. Extensions to controlled vocabulary. Clarified text.
10
11 = Introduction =
12
13 According to the SDMX documentation, the Annotation is a construct that contains user or organisation-specific metadata. The Annotation construct in SDMX is available to most of the SDMX structural metadata artefacts. This facility is essentially a flexible extension mechanism allowing metadata to be added to an SDMX structural artefact. Annotations are often used to store metadata in artefacts when there is no specific place for that information in the SDMX information model. Presentation metadata is a prime example, such as a default presentation for a dataflow.
14
15 Note that whilst the SDMX Annotation has a specific structure (Title, Type, URL, Text) individual organisations are free to use these in any way and any combination they wish. However, an Annotation can only be processed in a meaningful way (i.e. other than viewing it) by systems that understand its semantics.
16
17 The main advantage of the Annotation is its flexibility as all properties can be tailor-made and there is no limit to their number. This can prove very useful for specific applications, such as dissemination tools. The main drawback is poor interoperability as Annotations convey no semantics and are not standardised. This means that organisations that want to exchange Annotations and process them automatically must agree upon, at least, a common naming syntax.
18
19 The aim of this guideline is to improve machine interactions by proposing a controlled vocabulary for the Type property of the SDMX Annotation construct and a recommended usage for the other properties that will greatly improve the interoperability of Annotations between SDMX-compliant organisations.
20
21 The Controlled Vocabulary referred to above will be maintained as a SDMX Concept Scheme stored in the SDMX Global Repository.
22
23 = SDMX Information Model for the Annotation construct =
24
25 === SDMX 2.1 ===
26
27 [[image:1768507168026-558.png]]
28
29 All classes derived from the abstract class AnnotableArtefact may have Annotations. The Annotation is used to convey extra information to describe SDMX constructs. This information may be in the form of a URL reference, a non-localised text, and/or multiple localised texts (represented by the one-to-many relationship to LocalisedString).
30
31 === SDMX 3.0 ===
32
33 [[image:1768507168030-780.png]]
34
35 The URL can be localised which gives the advantage of linking to different resources depending on the language. It also removes the complexity of having to use AnnotationText in SDMX 2.1 to do this.
36
37 = Properties of the Annotation construct =
38
39 The properties of the Annotation construct are listed below. This information is taken from the [[SDMX official technical documentation>>url:https://sdmx.org/?page_id=5008]].
40
Helena K. 1.2 41 |**Property**|(% style="width:823px" %)**Description**|(% style="width:710px" %)**Controlled vocabulary context**
42 |**id**|(% style="width:823px" %)Identifier for the Annotation. It can be used to disambiguate one Annotation from another where there are several Annotations for the same annotated object.|(% style="width:710px" %)Id is set to @SDMX to identify it as part of the controlled vocabulary
43 |**title**|(% style="width:823px" %)A title used to identify an Annotation.|(% style="width:710px" %)A non-localised value for the annotation. Used when localisation is irrelevant.
44 |**type**|(% style="width:823px" %)(((
Helena K. 1.1 45 Specifies how the Annotation is to be processed.
46 The **type** is often used as the usage context of the Annotation. The types are not enumerated[[~[1~]>>path:#_ftn1]], as these can be specified by the Annotation creator. The definitions and use of Annotation types should be documented by their creator.
Helena K. 1.2 47 )))|(% style="width:710px" %)Identifies the usage (e.g. images are type IMAGE) of the annotation. The type values are enumerated in the controlled vocabulary table.
48 |**url**|(% style="width:823px" %)(((
Helena K. 1.1 49 A link to external descriptive text.
50 The **url** is a URI - typically a URL - which points to a resource. If a specific behaviour is desired, an Annotation type should be defined which specifies the use of this field more exactly.
Helena K. 1.2 51 )))|(% style="width:710px" %)A non-localised URL reference to an external resource. Used when localisation is irrelevant.
52 |**+url**|(% style="width:823px" %)**SDMX 3.0 and later**. An annotation may have several localised URLs|(% style="width:710px" %)A localised URL reference to an external resource.
53 |**+text**|(% style="width:823px" %)(((
Helena K. 1.1 54 An International String that provides the multilingual text content of the Annotation.
55
56 **Text** holds a language-specific string containing the text of the Annotation.
Helena K. 1.2 57 )))|(% style="width:710px" %)A localised value for the annotation.
Helena K. 1.1 58
59 = Introducing Standard Annotations =
60
61 As stated earlier, a major drawback of the Annotation construct is the fact that they are not standardised for reuse when exchanging structural metadata. Annotations are containers for additional information relating to the object to which they are attached. This means that for an Annotation to be interpreted in the same way by exchange partners, a reference is needed that defines some standard behaviour and implementation.
62
63 This guideline proposes an Annotation controlled vocabulary and guidelines on their (re)use for SDMX implementers.
64
65 A standard Annotation can be defined as an Annotation that has an agreed definition in the SDMX community. Some of them, especially the general and display-related annotations also have a described behaviour. They allow diverse systems to parse the information and perform a specific action in response.
66
67 = How to Identify Standard Annotations? =
68
69 In order to be able to configure their applications to implement actions based upon standard Annotations, systems must know how to identify such Annotations. This is done by setting the Annotation **id** property to “@SDMX” which indicates that the Annotation is part of the controlled vocabulary described in the section List of Standard Annotations, and avoids using “@SDMX” for other usage contexts. For example, ORDER could be the order of codes (as described in this controlled vocabulary) or some kind of order number (a different usage).
70
71 The additional mandatory information to be provided is the **type** property that specifies the type of action to be implemented. There may be other mandatory property values depending on the type of the standard Annotation.
72
73 == Examples ==
74
75 The green columns in the table below show example usages of standard Annotations. The orange “ORDER” column is not a standard Annotation because the usage context is not the same as the standard Annotation “ORDER”, therefore the **id** should not be “@SDMX”.
76
Helena K. 1.2 77 |**id***|**@SDMX**|(% style="width:249px" %)**@SDMX**|(% style="width:209px" %)**@SDMX**|(% style="width:888px" %)(((
Helena K. 1.1 78 **Not @SDMX**
79
80 This is a “customer order no.” which is a different use case than the ORDER standard Annotation which is a list order
81 )))
Helena K. 1.2 82 |**title**| |(% style="width:249px" %) |(% style="width:209px" %) |(% style="width:888px" %)1934245
83 |**type***|NOT_DISPLAYED|(% style="width:249px" %)EXCLUDES|(% style="width:209px" %)ORDER|(% style="width:888px" %)ORDER
84 |(% rowspan="2" %)**+text**|(% rowspan="2" %) |(% rowspan="2" style="width:249px" %) |(% style="width:209px" %)en :10|(% rowspan="2" style="width:888px" %)
85 |(% style="width:209px" %)fr :20
Helena K. 1.1 86
87 ~* denotes a mandatory information for standard Annotations
88
89 = The Business value of Standard Annotations =
90
91 The following diagram explains the business value and decision process when deciding whether to use a standard Annotation. As can be seen, if they are used then a maximum reuse is made of the Annotation itself, tools and processes. If they are not used then bespoke Annotations, agreements, tools and processing are required to understand and make use of the information in the Annotation, and it (plus supporting tools, processes, etc.) is harder to reuse.
92
93 [[image:1768507168033-962.png]]
94
95 = List of Standard Annotations =
96
97 This section lists the standard Annotations with their typical usage contexts. This list will be expanded over time as new implementations and needs arise. When references to external standards are made (e.g. skos or xkos specifications), the reader is invited to consult the “References” section for more information.
98
99 The list of standard Annotations will be available from the SDMX Registry as artefact: SDMX:CS_ANNOT(*.*.*). Link: [[https:~~/~~/registry.sdmx.org/ws/public/sdmxapi/rest/conceptscheme/SDMX/CS_ANNOT/latest/?format=sdmx-2.1&detail=full&references=none>>url:https://registry.sdmx.org/ws/public/sdmxapi/rest/conceptscheme/SDMX/CS_ANNOT/latest/?format=sdmx-2.1&detail=full&references=none]]
100
101 **Note:** There are several Annotations that are types of name or label, e.g. FULL_NAME, SHORT_LABEL, ORIGINAL_LABEL. These Annotations have specific use cases that are described in the tables below and should not be used to replace an artefact’s or item scheme item’s Name and Description property.
102
103 == Relationships between Annotation properties ==
104
Helena K. 1.2 105 === Text value defaults and specific locale values ===
Helena K. 1.1 106
107 Some use cases may benefit from having a single, default value for all locales/languages but also to set the value for certain locales. An example is ORDER where there may be a default list order for all locales but two locales have a specific order which is different from the default. In order to avoid having to state an order for every locale, the Annotation Title property may be used to state the default value, whereas the text property is used for the localised values.
108
109 Consider this annotation //Example~:// An ORDER annotation type that is attached to a code item ACME. If both the Annotation Text and Annotation Title have values, then the Annotation Text value (e.g. en:10,es:20) is used for the localized values instead of the Annotation Title (e.g. 30) which would only be taken if the locale in the context is not found among the specified ones.
110
Helena K. 1.2 111 === URL value defaults and specific locale values ===
Helena K. 1.1 112
113 ===== SDMX 2.1 and earlier =====
114
115 In SDMX 2.1, the Annotation’s URL property is a single, non-localised value. There may be cases where different URLs are required for certain locales. In this case, it is recommended to use the Annotation text property and state the language and URL in an HTML fragment, for example:
116
117 fr:<a href=”https:~/~/someLink”>
118
119 When both a URL and text property for the locale exists, the text property overrides (is used instead of) the URL property.
120
121 ===== SDMX 3.0 and later =====
122
123 Multiple URL localised properties were introduced in SDMX 3.0. Therefore, the URL work-around in the above paragraph is not recommended. The URL property should be used as shown in the table.
124
125 == General and Display-related Annotation types ==
126
127 |Annotation Type|Use Case|Where to attach|(((
128 +Text
129
130 Blue is optional
131 )))|(((
132 Title
133
134 Blue is optional
135 )))|(((
136 SDMX 2.1:URL
137
138 SDMX >=3.0:+URL
139
140 Blue is optional
141 )))
142 |FULL_NAME|Alternative name to be displayed for items in Item Schemes (e.g. Codelists, Concept Schemes, Category Schemes) whenever the item is displayed without its parent. For example, if a code list that has a hierarchy is displayed as a flat list, then this annotation may be used to provide sufficient context for the code. Concatenation of code + heading in NACE Rev.2.1 
143 en: A0123 Growing of citrus fruits|Item in an Item Scheme|(((
144 <language>:<content>,
145
146 <language>:<content>,…
147
148 //Example~://
149
150 en:Labour force (Employment)
151 )))|<content>|
152 |REPLACE_NAME|Replace each code name in a component by the value of another component in an observation or series|A Dataflow or DSD| |(((
153 <component Id to replace name>:<component Id to use name>
154
155 //Example~://
156
157 CUST_BREAKDOWN:CUST_BREAKDOWN_LB
158 )))|
159 |REPLACE_CONTENT|Replace the content in a component by the value of another component in an observation or series|A Dataflow or DSD| |(((
160 <component Id to replace content>:<component Id to use content>
161
162 //Example~://
163
164 REF_AREA:M49_CODE
165 )))|
166 |COMPLEMENT|(((
167 Additional fixed text to be displayed in parenthesis after the code name.
168
169 E.g. Representation of Non-hazardous (NHAZW), hazardous waste (HAZW) in the European List of Wastes
170 en: 01 03 04* acid-generating tailings from processing of sulphide ore (HAZW)
171 en: 01 03 99 wastes not otherwise specified (NHAZW)
172 )))|Item in an Item Scheme|(((
173 <language>:<content>,
174
175 <language>:<content>,…
176
177 //Example~://
178
179 en:See reference metadata
180 )))|<content>|
181 |ORDER|Explicit indication of a localised order of items in Items Schemes or artefacts (e.g. Codelist, Concept Scheme, Category Scheme, Dataflow, etc.)|(((
182 Either:
183
184 * an artefact, or;
185 * an item in an Item Scheme
186 )))|(((
187 <language>:<content>,
188
189 <language>:<content>,…
190
191 //Example~://
192
193 en:10,es:20
194 )))|(((
195 <content>
196
197
198 )))|
199 |TOTAL|(((
200 Code Item that represents a total value. If the attachment is:
201
202 * to a Code, the Annotation Text is optional and may contain an explanatory text;
203
204 to a Codelist, the Annotation Title is mandatory and includes the code(s) that represent a total
205 )))|(((
206 Either:
207
208 * a Code Item that represents a total value, or;
209 * a Codelist to specify the code(s) with the total
210 )))|(((
211 <language>:<explanatory text>,
212
213 <language>:<explanatory text>,…
214 )))|(((
215 Attached to Code Item: <blank>
216
217 Attached to Codelist: <code>,<code>,…
218 )))|
219 |DRILLDOWN|Denotes the concept that specifies whether observations are at the aggregate level or a drilldown.|(((
220 Either:
221
222 * A Dataflow or DSD
223 )))| |(((
224 <concept Id>
225
226 //Example~://
227
228 DD_DIM (this concept should be hidden using the NOT_DISPLAYED Annotation below)
229 )))|
230 |DEPRECATED|(((
231 Indication that an Item in an Item Scheme or an artefact is deprecated.
232
233 For an item scheme item, the annotation value provides a replacement name for the code name.
234
235 For an artefact, the URL points to the replacement artefact. May be used in conjunction with SUPERSEED where the replacement artefact references the replaced artefact.
236
237 Suggestion to use a controlled vocabulary
238
239 url: <[[http:~~/~~/publications.europa.eu/resource/authority/concept-status/CURRENT>>url:http://publications.europa.eu/resource/authority/concept-status/CURRENT]]>
240 url: <[[http:~~/~~/publications.europa.eu/resource/authority/concept-status/DEPRECATED>>url:http://publications.europa.eu/resource/authority/concept-status/DEPRECATED]]>
241
242 or
243
244 TITLE: true (false)
245 )))|(((
246 Either:
247
248 * an artefact, or;
249 * an item in an Item Scheme
250 )))|(((
251 For item scheme item:
252
253 <language>:<content>,
254
255 <language>:<content>,…
256
257 //Example~://
258
259 en:deprecated,fr:obsolète
260 )))|<content>|(((
261 For artefact:
262
263 <see section URL value defaults and specific locale values>
264
265
266 )))
267 |DEFAULT|(((
268 Indication that an item in an Item Scheme or artefacts is to be selected by default.
269
270 The Annotation defines a selection so that a pre-defined default subset of data can be processed (e.g. visualised, extracted) instead of the entire dataset
271 )))|(((
272 * Item in ItemScheme, or;
273 * DSD, or;
274 * a Dataflow
275
276 Note: A DEFAULT Annotation attached to a later level in this list supersedes that attached to an earlier level. E.g., a DEFAULT Annotation attached to individual Codes in Codelists is only to be used when there is no DEFAULT Annotation attached to the Dataflow nor to the DSD, and those of DSDs are only to be used when there is no DEFAULT Annotation attached to the Dataflow.
277 )))| |(((
278 Attached to:
279
280 - DSD or Dataflow:
Helena K. 1.2 281 **<concept>=<code>+<code>+…,<concept>=<code>+<code>+…**
Helena K. 1.1 282
283 //Example~:// FREQ=A+Q,TIME_PERIOD_START=2013-01,TIME_PERIOD_END=2018-12
284 )))|
285 |IMAGE|A visual identity to associate to Item Scheme Items or artefacts|(((
286 Either:
287
288 * an artefact, or;
289 * an item in an item scheme
290 )))|(((
291 For localised content in SDMX 2.1
292
293 <language>:<HTML containing URL to the resource>,
294
295 <language>:<HTML containing URL to the resource>,…
296
297 //Example~://
298
299 en:<a href=”https:~/~/sdmx.org/wp-content/uploads/SDMX_map_small-220x220.jpg”>
300 )))| |(((
301 See section URL value defaults and specific locale values.
302
303 //Example~://
304
305 https:~/~/sdmx.org/wp-content/uploads/SDMX_map_small-220x220.jpg
306
307
308 )))
309 |DRILLDOWN_CONCEPTS|Concepts to be displayed in a drilldown operation|Dataflow or DSD| |(((
310 <concept Id>,<concept Id>,…
311
312 Example :
313
314 DONOR,RECIPIENT,YEAR,PROJECT_ID,OBS_VALUE,DESCRIPTION,OWNER
315 )))|
316 |NOT_DISPLAYED|Used to hide components or their values in the presentation|(((
317 Either:
318
319 * a Dataflow or DSD, or;
320 * an Item in an Item Scheme
321 )))| |(((
322 Attached to Item in Item Scheme: <blank>
323
324 Attached to Dataflow or DSD:
325
326 <concept Id>,<concept Id>,…
327
328 Example :
329
330 DD_DIM (to hide drilldown control concept)
331 )))|
332 |LAYOUT_ROW|Dimensions to be presented in rows (concepts on y-axis)|(((
333 Either:
334
335 * an artefact, or;
336 * a Dimension
337 )))| |(((
338 Attached to Dimension: <blank>
339
340 Attached to Dataflow or DSD: <dimension Id>,<dimension Id >,…
341
342 //Example~://
343
344 REF_AREA,MEASURE
345 )))|
346 |LAYOUT_COLUMN|Dimensions to be presented in columns (concepts on x-axis)|(((
347 Either:
348
349 * an artefact, or;
350 * a Dimension
351 )))| |(((
352 Attached to Dimension: <blank>
353
354 Attached to Dataflow or DSD: <dimension Id>,<dimension Id>,…
355
356 //Example~://
357
358 TIME_PERIOD
359 )))|
360 |LAYOUT_FLAG|Indication that an attribute and its attribute value should be presented as a flag|Dataflow| |(((
361 <concept Id>,<concept Id>,...
362
363 //Example~://
364
365 OBS_STATUS,CONF_STATUS
366 )))|
367 |LAYOUT_NOTE|Indication that an attribute and its attribute value should be presented as a note|Dataflow| |(((
368 <concept Id>,<concept Id>,...
369
370 //Example~://
371
372 OBS_STATUS,CONF_STATUS
373 )))|
374 |(((
375 METADATA
376
377
378 )))|Links an MSD directly to a DSD. Can be used to overcome the complexities of reference metadata linkage|DSD| |MSD URI, e.g. urn:sdmx:org.sdmx.infomodel.metadatastructure.MetadataStructure=OECD:MSD_REF_METADATA(1.0)|
379 |LAYOUT_ROW_SECTION|Dimension to be presented as a break-down concept at a third hierarchical level above columns and rows.|(((
380 Either:
381
382 * an artefact, or;
383
384 a Dimension
385 )))| |(((
386 Attached to Dimension: <blank>
387
388 Attached to Dataflow or DSD: <dimension Id>,<dimension Id>,…
389
390 //Example~://
391
392 SEX
393 )))|
394 |EXT_RESOURCE|(((
395 A localised link to an external resource associated to the annotated artefact. For example, an ontology item
396
397 //a methodology// en:<a href:"[[https:~~/~~/ec.europa.eu/eurostat/web/waste/methodology>>url:https://ec.europa.eu/eurostat/web/waste/methodology]]">
398 )))|Any SDMX object|(((
399 For localised content in SDMX 2.1
400
401 <language>:<HTML containing URL to the resource>,
402
403 <language>:<HTML containing URL to the resource>,…
404
405 //Example~://
406
407 en:<a href=”[[http:~~/~~/rdf-vocabulary.ddialliance.org/xkos#depth>>url:http://rdf-vocabulary.ddialliance.org/xkos#depth]]”>
408 )))| |(((
409 See section URL value defaults and specific locale values.
410
411 //Example~://
412
413 http:~/~/rdf-vocabulary.ddialliance.org/xkos#depth
414 )))
415 |COMBINED_CONCEPTS|(((
416 Comma-separated list of concept IDs to show as a concatenated label.
417
418 The listed concepts’ item contents may be concatenated to generate the target concept.
419
420 Multiple target concept combinations can be defined by separating the target concepts by ;
421 )))|Dataflow or DSD|(((
422 <language>:<display name>,
423
424 <language>:<display name>
425
426 e.g. COMBINED_UNIT_MEASURE:PRICE_BASE,UNIT_MEASURE;COMBINED_MEASURE:MEASURE,REF_SECTOR{(en):Combined unit of measure;Combined measure}{(fr):Unité de mesure combinée;Mesure combinée}
427 )))| |
428 |(deprecated) UNIT_MEASURE_CONCEPTS|(((
429 Comma-separated list of concept IDs that is used to define the full unit of measure. The concepts must be in the DSD.
430
431 The listed concepts’ item contents may be concatenated to generate the unit of measure label (unless the UNIT_MEASURE_LABEL annotation is present).
432 )))|Dataflow or DSD| |(((
433 <concept Id>,<concept Id>,…
434
435 //Example~:// UNIT_MEASURE,UNIT_MULT,TRANSFORMATION [could generate a value of Australian Dollar, Thousands, Non-transformed]
436 )))|
437 |(deprecated) UNIT_MEASURE_LABEL|(((
438 Indicates the concept that enumerates the full unit of measure labels.
439
440 The concept must be in the DSD. UNIT_MEASURE_LABEL overrides the UNIT_MEASURE_CONCEPTS if both are provided.
441
442 Also can be attached to items in item scheme, e.g.
443
444 Text en:Gram
445 fr: Gramme
446 url:** **[[**http:~~/~~/data.europa.eu/gzn/su/G**>>url:http://data.europa.eu/gzn/su/G]]
447 )))|Dataflow or DSD, Item in an Item Scheme|(((
448 This is optional, used if a freetext label is required.
449
450 <language>:<content>,
451
452 <language>:<content>,…
453
454 //Example~://
455
456 en:USD, thousands
457
458 fr:USD, milliers
459 )))|(((
460 This is optional, used if an enumerated list is required.
461
462 <concept Id>
463
464 //Example~://
465
466 UOM_ATTRIBUTE [This concept may contain the following items as units of measure:
467
468 * National Currency, thousands
469 * USD, thousands
470
471 Index, based on National Currency]
472 )))|
473 |(((
474 LAYOUT_TIME_PERIOD_DESC
475
476
477 )))|Indication that the display of the TIME_PERIOD dimension for a dataflow, or all dataflows of the same DSD, is to be done in descending sort order.|Dataflow, DSD| |(((
478 //Example~://
479
480 LAYOUT_TIME_PERIOD_DESC
481 )))|
482 |(((
483 LAYOUT_CELL_ALIGN
484
485
486 )))|Indication to force the data cell alignment to the left or to the right. This can be defined generically for all locales or per locale.|Dataflow, DSD, Dimension|(((
487 <language>:<content>,
488
489 <language>:<content>,…
490
491
492 <content> values:RIGHT or LEFT
493 )))|Content values:RIGHT or LEFT|
494 |(((
495 MAX_TABLE_DATA
496
497
498 )))|Increase the maximum preview table size above default maximum limits for the number of observations retrieved from the SDMX web service and for the number of table cells|Dataflow| |(((
499 <integer>
500
501 //Example~://
502
503 15000
504 )))|
505 |(((
506 MAXTEXTATTRIBUTELENGTH
507
508
509 )))|Increase the maximum length for textual attribute values|DSD| |(((
510 <integer>
511
512 //Example~://
513
514 500
515 )))|
516 |SEARCH_WEIGHT|Indication of localised boosted dataflows in the search results when ordered by relevance|Dataflow|(((
517 <language>:<integer>,...
518
519 //Example~://
520
521 "en":"3","es":"4","fr":"5"
522 )))|(((
523 <integer>
524
525 //Example~://
526
527 10
528 )))|
529
530 == Codelist and Statistical Classification-specific Annotations ==
531
532 The categories below are used widely, for example by the European Statistical System (ESS), and the United Nations Statistics Division for its central framework classifications ISIC4[[~[2~]>>path:#_ftn2]] and CPC[[~[3~]>>path:#_ftn3]].
533
534 |Annotation Type|Use Case|Where to attach|(((
535 +Text
536
537 Blue is optional
538 )))|(((
539 Title
540
541 Blue is optional
542 )))|(((
543 SDMX 2.1:URL
544
545 SDMX >=3.0:+URL
546
547 Blue is optional
548 )))
549 |ORIGINAL_CODE|Code as displayed in other representations, such as official or original documentation (i.e. possibly containing dots, spaces, etc.). Reference to external standard: skos:notation|Item in an Item Scheme| |(((
550 <original code>
551
552 //Examples~://
553
554 * 0105.13 [Harmonized System]
555 * 11.2.0.9 [COICOP classification]
556 )))|
557 |HIER_CONTEXT|(((
558 In SDMX 2.1, a reference between a usage context and a hierarchy (that may be contained in a Hierarchical Codelist (HCL)).
559
560 In SDMX 3.0, use the HierarchyAssociation artefact
561 )))|DSD or Dataflow| |(((
562 <component Id>:<HCL Id>.<hierarchy Id>
563
564 //Example~://
565
566 REF_AREA:OECD.EDU:HCL_REF_AREA(1.0).REF_AREA provides the link to the  reference area hierarchy for OECD education data
567 )))|
568 |HIER_LEVEL|(((
569 Explicit specification of the hierarchical level of a code item
570
571 Reference to external standard: xkos:ClassificationLevel - property: xkos:xdepth url: [[http:~~/~~/data.europa.eu/ux2/nace2.1/sections>>url:http://data.europa.eu/ux2/nace2.1/sections]]
572
573 text en:sections
574 )))|Code item| |(((
575 <hierarchical level>
576
577 //Example~://
578
579 1
580 )))|
581 |SHORT_LABEL|A short label, typically for dissemination purposes where long labels are sometimes not appropriate for presentation in tables where space is an important parameter (generally less than 40 or 50 characters)|Artefact, or Concept, or Item in an Item Scheme|(((
582 <language>:<content>,
583
584 <language>:<content>,…
585 )))|(((
586 //Example~://
587
588 [Official French label “Transformation et conservation de la viande de boucherie” is shortened to] fr:Transf. & conserv. viande de boucherie
589
590
591 In Codelist=IMF:CL_AREA(1.13)
592 Code 4J837 European Union Intellectual Property Office has a Short_Label
593
594 EN:EUIPO
595 )))|
596 |EXPLAN_LABEL|An explanatory text that specifies “other” and similar categories. An example is the Combined Nomenclature classification where the many codes labelled “other” are complemented by a verbose text describing in detail the content of the code item|Item in an Item Scheme, mapping to Representation Maps|(((
597 <language>:<content>,
598
599 <language>:<content>,…
600 )))|(((
601 //Example~://
602
603 [EU Combined Nomenclature official label for code 3824 99 57 reads “Other”, which is not very informative for the user; instead the EXPLAN_LABEL reads] en:Cartridges and refills, filled, for electronic cigarettes, and preparations for use in the cartridges and refills, not containing nicotine or its salts, ethers, esters or other derivatives thereof
604 )))|
605 |EXPLAN_CONSOL|Explanatory notes. An explanatory text to be used when objects included in and excluded from a classification position are consolidated, i.e. are presented together. Reference to external standard: skos:scopeNote|Item in an Item Scheme, mapping to Representation Maps|(((
606 <language>:<content>,
607
608 <language>:<content>,…
609 )))|(((
610 Example (from the US NAICS classification):
611
612 en:Industries in the Food Manufacturing subsector transform livestock and agricultural products into products for intermediate or final consumption. […] The food products manufactured in these establishments are typically sold to wholesalers or retailers for distribution to consumers, but establishments primarily engaged in retailing bakery and candy products made on the premises not for immediate consumption are included. Establishments primarily engaged in manufacturing beverages are classified in Subsector 312, Beverage and Tobacco Product Manufacturing.
613 )))|
614 |EXPLAN_INCLUDES|Explanatory notes. Description of those things known specifically to be included in the concept. Synonyms Typical labels for such explanatory notes: "This class includes", "This category includes", "This position includes", "Includes", etc. Reference to external standard: xkos:inclusionNote or xkos:coreContentNote (if EXPLAN_INCLUDES_ALSO available)|Item in an Item Scheme, mapping to Representation Maps|(((
615 <language>:<content>,
616
617 <language>:<content>,…
618 )))|(((
619 Example (from ISIC Rev. 4 explanatory notes to code 2520 - Manufacture of weapons and ammunition):
620
621 en: This class includes:
622
623 * manufacture of heavy weapons (artillery, mobile guns, rocket launchers, torpedo tubes, heavy machine guns)
624 * manufacture of small arms (revolvers, shotguns, light machine guns)
625 * manufacture of air or gas guns and pistols
626 * manufacture of war ammunition
627 )))|
628 |EXPLAN_CASELAW|Explanatory notes. Indication that a decision on the classification has been made by the ad hoc Committee (concept generally described as “ruling”, “classification opinion”, classification decision; caselaw). : Reference to external standardxkos:caseLaw. The difference between caselaws and traditional explanatory notes is that caselaws are adopted during the time period between two official versions of a specific classification and have thus a slightly different status (e.g. from a legal viewpoint)|Item in an Item Scheme|(((
629 <language>:<content>,
630
631 <language>:<content>,…
632
633 Example (from NACE Rev. 2 caselaw to code 01.62):
634
635 en:Automated egg hatching for poultry - Operation of livestock management systems]
636 )))| |
637 |EXPLAN_INCLUDES_ALSO|Explanatory notes. Description of those things which can be considered as borderline cases and are generally based on consensus rather than strict methodological principles (e.g. classifying wooden shoes as handicraft rather than shoes). Typical labels for such explanatory notes: "This class includes also", "This category includes also", "This position includes also ", "Includes also", etc. Reference to external standard: xkos:additionalContentNote|Item in an Item Scheme|(((
638 <language>:<content>,
639
640 <language>:<content>,…
641 )))|(((
642 Example (from ISIC Rev. 4 explanatory notes to code 2520 - Manufacture of weapons and ammunition):
643
644 en:This class also includes:
645
646 * manufacture of hunting, sporting or protective firearms and ammunition
647 * manufacture of explosive devices such as bombs, mines and torpedoes
648 )))|
649 |EXPLAN_EXCLUDES|Explanatory notes. Description of those things which are explicitly excluded from a category. Typical labels for such explanatory notes: "This class excludes", "This category excludes", "This position excludes", "Excludes", etc. Reference to external standards: xkos:exclusionNote|(((
650 Item in an Item Scheme
651
652
653 )))|(((
654 <language>:<content>,
655
656 <language>:<content>,…
657 )))|(((
658 Example (from ISIC Rev. 4 explanatory notes to code 2520 - Manufacture of weapons and ammunition):
659
660 en:This class excludes:
661
662 * manufacture of percussion caps, detonators or signalling flares, see 2029
663 * manufacture of cutlasses, swords, bayonets etc., see 2593
664 )))|
665 |MAP_REFER|A reference to a classification mapping or transformation, e.g. an SDMX Structure Map. Reference to external standard: skos:mappingRelation (skos:broadMatch, skos:narrowMatch, skos:closeMatch, skos:exactMatch or skos:relatedMatch)|Codelist, Concept Scheme, or another Item Scheme| |Id of an ItemSchemeMap returned by the Annotation URL|(((
666 See section URL value defaults and specific locale values.
667
668
669 )))
670 |COMP_RULE|Code item composition rule. For example, for code A the composition rule may be “A1+A2” where A1 and A2 are other codes in the same Codelist|An Item in an Item Scheme| |(((
671 <content>
672
673 //Example~://
674
675 A1+A2
676 )))|
677 |FOLLOWS|(((
678 A reference used to express the succession in time of Item Schemes.
679
680 For example, NACE Rev. 2 is the successor of NACE Rev. 1.1
681
682 Reference to external standard: skos:ConceptScheme - property: xkos:follows
683 )))|Codelist or Item Scheme| | |(((
684 See section URL value defaults and specific locale values.
685
686 //Example~://
687
688 (CL_REGIONAL 3.1.1 follows CL_REGIONAL 3.1):
689
690 [[https:~~/~~/registry.sdmx.org/ws/public/sdmxapi/rest/codelist/ESTAT/CL_REGIONAL/3.1>>url:https://registry.sdmx.org/ws/public/sdmxapi/rest/codelist/ESTAT/CL_REGIONAL/3.1]]
691 )))
692 |HAS_VARIANT|(((
693 A reference used to express the relation between an Item Scheme and its variant(s).
694
695 Reference to external standard: skos:ConceptScheme - property: xkos:variant
696
697
698 For //Example~:// CL_AREA has a variant CL_GEO
699 )))|Codelist or Item Scheme| | |(((
700 See section URL value defaults and specific locale values.
701
702
703 )))
704 |SUPERSEED|(((
705 A reference to a previous version, if the current version obsoleted the previous one.
706
707 May be used in conjunction with DEPRECATED.
708
709 Reference to external standard: skos:ConceptScheme - property: xkos:supersedes
710 )))|Codelist or Item Scheme, or an artefact| | |(((
711 See section URL value defaults and specific locale values.
712
713
714 )))
715 |FAMILY_LABEL|(((
716 Label of the Classification Family (e.g. NACE, ISIC)
717
718 Reference to external standard: skos:ConceptScheme - property: xkos:belongsTo
719
720 label of the classification
721 )))|Codelist or Item Scheme|(((
722 <language>:<content>,
723
724 <language>:<content>,…
725
726 //Example~://
727
728 en:NACE
729 )))| |(((
730 See section URL value defaults and specific locale values.
731
732
733 )))
734 |COVERAGE_LABEL|(((
735 Label(s) of the item scheme’s coverage (e.g. National Accounts, Products, Activities, Occupations)
736
737 Reference to external standard: skos:ConceptScheme - property: xkos:covers
738
739 //Examples~://
740
741 URL <http:~/~/eurovoc.europa.eu/56> (National accounts)
742
743 URL <http:~/~/publications.europa.eu/resource/authority/data-theme/REGI> (Regions and Cities)
744 )))|Codelist or Item Scheme|(((
745 <language>:<content>,
746
747 <language>:<content>,…
748
749 //Example~://
750
751 En:national accounts
752 )))| |(((
753 See section URL value defaults and specific locale values.
754
755
756 )))
757 |GEO_FEATURE_SET|(((
758 In Codelists, transmits GeoFeature values.
759
760 Example for NUTS ID BE23
761 url:[[http:~~/~~/data.europa.eu/nuts/geometry/2xr1qiv9>>url:http://data.europa.eu/nuts/geometry/2xr1qiv9]]
762 )))|Code in a Codelist. The Codelist must have an annotation attached with AnnotationType=GEO_TYPE_GEOGRAPHIC| |A set of points defining a feature following the 1363 ISO/IEC 13249-3:2016 standard to conform Well-known Text (WKT) for the 1364 representation of geometries. See SDMX STANDARDS: SECTION 6 for further information on the format.|
763 |GEO_TYPE_GEOGRAPHIC|Indicates that a codelist contains GeoFeature values via the GEO_FEATURE_SET annotation.|Codelist| | |
764 |LEGAL_BASIS|(((
765 Indicates that the Legislation on which the codelist/nomenclature is based.
766
767 Example for NACE Rev.2.1
768
769 url: [[http:~~/~~/data.europa.eu/eli/reg_del/2023/137/oj>>url:http://data.europa.eu/eli/reg_del/2023/137/oj]]
770 )))|Codelist| | |http:~/~/data.europa.eu/eli/reg_del/2023/137/oj
771
772
773
774
775
776 = Concept Scheme SDMX:CS_ANNOT =
777
778 The Concept Scheme for standard Annotations will have the Maintenance Agency SDMX and will describe the following properties for each Annotation. For the information represented by Annotations, the value is in AnnotationTitle apart from the URL property where it is in AnnotationURL.
779
780 |**Property**|**Representation in Concept**|**Description**
781 |**Code**|Concept Id|The Annotation Type column, e.g. NOT_DISPLAYED, EXCLUDES
782 |**Name**|Concept Name|Short description of the standard Annotation derived from the “Use case” column
783 |**Representation**|Concept Core Representation|Allowable type or format for the Annotation
784 |**Description**|Concept Description|The information in the “Use case” column. Possible to add more contextual information. Specific details can be described here, such as if the value should be in AnnotationText or AnnotationTitle
785 |**Artefact(s)**|Annotation Type: Artefact(s)|The information in the “Where to attach” column
786 |**URL**|Annotation Type: URL|The Annotation URL column. The value is in URL
787
788 == Example of a Concept ==
789
790 |**Concept Id**|NOT_DISPLAYED
791 |**Concept Name**|Used to hide components or their values in the presentation
792 |**Concept Core Representation**|/TextFormat@textType="String"
793 |**Concept Description**|To hide dimensions and attributes in a display (e.g. a table). For example, if they have only one allowed, available or selected value
794 |**Concept: Annotation: Type: Artefact(s)**|Either a Dataflow or DSD, or an item in an item scheme
795
796 === ===
797
798 === SDMX-ML of the Example ===
799
800 <str:Concept id="NOT_DISPLAYED">
801 <com:Annotations>
802 <com:Annotation>
803 <com:AnnotationTitle>Either a Dataflow or DSD, or an item in an item scheme</com:AnnotationTitle>
804 <com:AnnotationType>Artefact(s)</com:AnnotationType>
805 </com:Annotation>
806 </com:Annotations>
807 <com:Name xml:lang="en">Used to hide components or their values in the presentation</com:Name>
808 <com:Description xml:lang="en">To hide dimensions and attributes in a display (e.g. a table). For example, if they have only one allowed, available or selected value</com:Description>
809 <str:CoreRepresentation>
810 <str:TextFormat textType="String"/>
811 </str:CoreRepresentation>
812 </str:Concept>
813
814 = References =
815
816 * [[Formalization of the Structure and Content of Statistical Classifications>>url:https://urldefense.com/v3/__https:/eur02.safelinks.protection.outlook.com/?url=https*3A*2F*2Furldefense.com*2Fv3*2F__https*3A*2Feur02.safelinks.protection.outlook.com*2F*3Furl*3Dhttps*3A*2F*2Fec.europa.eu*2Feurostat*2Framon*2Fmiscellaneous*2Fgen_intro_classif_files*2FStructure_and_content_of_classifications_version_1_0_October_2019.docx*26data*3D02*7C01*7CDavid.BARRACLOUGH*40oecd.org*7Cf9cb429291334e5170cb08d80c883aeb*7Cac41c7d41f61460db0f4fc925a2b471c*7C0*7C1*7C637273126543303645*26sdata*3Dl01*2BEX3SNWREH*2FElV3r9Ld*2BG49l7ouvFi7pqAGYg2Ss*3D*26reserved*3D0__*3BJSUlJSUlJSUlJSUlJSUlJSUlJSU!!DOxrgLBm!Q_cL04DGMBYhHfuPQVRMMCKao1C3QuaoJxBTxO4_mSKNMGfLjmV2UTCtAhTDvbMAZtNzrTZ3*24&data=02*7C01*7CDavid.BARRACLOUGH*40oecd.org*7Ca70a73c696814b06406408d80d1d9336*7Cac41c7d41f61460db0f4fc925a2b471c*7C0*7C1*7C637273768055440921&sdata=r4CVvCdYBIU39XMN0qNmt*2FC9FIS7AnXrzYcjuzDe0Dc*3D&reserved=0__;JSUlJSUlJSUlJSoqKioqKioqJSUqKioqKioqKiUlKioqKiUlJSUlJSUlJSUlJSUl!!DOxrgLBm!RCGOp-FMBfmiP7CvEwdSAhL4XCil-vey-z32n6uxoCDXVTN7rXWXG442IZgqwpmM4wKQq908$]]
817 * [[SDMX Global Registry>>url:https://registry.sdmx.org/overview.html]]
818 * [[SDMX Glossary 2.1>>url:https://sdmx.org/wp-content/uploads/SDMX_Glossary_version_2_1-Final-2.docx]]
819 * SDMX Standards, “[[Information Model: UML Conceptual Design>>url:https://sdmx.org/wp-content/uploads/SDMX_2_0_SECTION_02_InformationModel.pdf]]”, version 2.1
820 * [[SKOS Specification>>url:https://www.w3.org/TR/2009/REC-skos-reference-20090818/]]
821 * [[XKOS Specification>>url:https://ddialliance.org/Specification/XKOS/1.2/OWL/xkos.html]]
822
823 ----
824
825 [[~[1~]>>path:#_ftnref1]] The technical standard does not enumerate the annotation types, however this guideline provides a recommended enumeration or controlled vocabulary
826
827 [[~[2~]>>path:#_ftnref2]] International Standard Industrial Classification of All Economic Activities
828
829 [[~[3~]>>path:#_ftnref3]] Central Product Classification
© Semantic R&D Group, 2026