DOCUMENT HISTORY

Introduction

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.

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.

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.

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.

The Controlled Vocabulary referred to above will be maintained as a SDMX Concept Scheme stored in the SDMX Global Repository.

SDMX Information Model for the Annotation construct

SDMX 2.1

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).

SDMX 3.0

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.

Properties of the Annotation construct

The properties of the Annotation construct are listed below. This information is taken from the SDMX official technical documentation.

Introducing Standard Annotations

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.

This guideline proposes an Annotation controlled vocabulary and guidelines on their (re)use for SDMX implementers.

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.

How to Identify Standard Annotations?

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).

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.

Examples

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”.

* denotes a mandatory information for standard Annotations

The Business value of Standard Annotations

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.

List of Standard Annotations

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.

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

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.

Relationships between Annotation properties

Text value defaults and specific locale values

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.

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.

URL value defaults and specific locale values

SDMX 2.1 and earlier

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:

fr:<a href=”https://someLink”>

When both a URL and text property for the locale exists, the text property overrides (is used instead of) the URL property.

SDMX 3.0 and later

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.

General and Display-related Annotation types

Codelist and Statistical Classification-specific Annotations

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² and CPC³.

Concept Scheme SDMX:CS_ANNOT

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.

Example of a Concept

SDMX-ML of the Example

<str:Concept id="NOT_DISPLAYED">
   <com:Annotations>
      <com:Annotation>
         <com:AnnotationTitle>Either a Dataflow or DSD, or an item in an item scheme</com:AnnotationTitle>
         <com:AnnotationType>Artefact(s)</com:AnnotationType>
      </com:Annotation>
   </com:Annotations>
   <com:Name xml:lang="en">Used to hide components or their values in the presentation</com:Name>
   <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>
   <str:CoreRepresentation>
      <str:TextFormat textType="String"/>
   </str:CoreRepresentation>
</str:Concept>

References

• Formalization of the Structure and Content of Statistical Classifications
• SDMX Global Registry
• SDMX Glossary 2.1
• SDMX Standards, “Information Model: UML Conceptual Design”, version 2.1
• SKOS Specification
• XKOS Specification

1. ^ The technical standard does not enumerate the annotation types, however this guideline provides a recommended enumeration or controlled vocabulary
2. ^ International Standard Industrial Classification of All Economic Activities
3. ^ Central Product Classification