Codelist V11

From FMR Knowledge Base
Revision as of 02:10, 22 August 2022 by Vmurrell (talk | contribs) (Context within the SDMX 2.1 Information Model)
Jump to navigation Jump to search

Overview

An SDMX Codelist is a managed list of classification codes.

Codelists can be referenced directly by Data Structure Definitions, or indirectly through Concepts to explicitly define the closed set of values for enumerated Dimensions, Attributes or Measures.

Structure Properties

Structure Type Standard SDMX Structural Metadata Artefact
Maintainable Yes
Identifiable Yes
Item Scheme Yes
SDMX Information Model Versions 1.0, 2.0, 2.1, 3.0
URN - Codelist namespace urn:sdmx:org.sdmx.infomodel.codelist.Codelist
URN - Code namespace urn:sdmx:org.sdmx.infomodel.codelist.Code

Context within the SDMX 3.0 Information Model

Codelist

Usage

SDMX Codelists are lists of classification codes used principally for defining the set of allowed values for enumerated Components in Data Structure Definitions (DSDs) or Metadata Structure Definitions which describe Reference Metadata.

Each code is a separate Item so must have an ID and a Name, but can also have an optional Description. While Code IDs must be unique within a Codelist, the same Code ID may be safely used in other Codelists. For instance: The code 'A' may be used in a Frequency Codelist to represent 'Annual', but also appear in an Industry Codelist to represent 'Agriculture'.

Conventions

'CL_' Codelist ID Prefix

Codelist IDs are given a 'CL_' prefix to distinguish them from other structures. For instance: CL_FREQ, CL_REF_AREA, CL_AGE.

Code ID Conventions

Codes can take any legal SDMX ID. But there are several conventions that should be taken into account when choosing Code IDs:

Uppercase By convention, Code ID's are in uppercase such as 'ABC'. Lower case Codes are valid (for example 'abc'), but care should be taken in their use to avoid confusion.
'_Z' Code The '_Z' code is conventionally used for the Undefined and Unknown classification.
'TOTAL' Code The 'TOTAL' code represents the total or sum of the dimension. For a 'country' dimension, series with TOTAL would indicate the sum of observation values for all countries.

You can seem more examples and information on Identities in this article.

Flat Codelists

Flat Codelists are simple lists of codes with no explicit or implied relationships or hierarchies.

Example: CL_FREQUENCY Codelist

Code ID Code Name
A Annual
S Half-yearly, semester
Q Quarterly
M Monthly
W Weekly
D Daily
B Daily - Business Week
N Minutely

Example: CL_ADJUSTMENT Codelist with descriptions

Code ID Code Name Code Description
K Calendar component Synonyms: Calendar effects; calendar factors
X Seasonal component Synonyms: Seasonal effects; seasonal factors
M Seasonal and calendar components Synonyms: Seasonal and calendar effects; seasonal and calendar factors
I Irregular component Synonym: Irregular effects
N Neither seasonally adjusted nor calendar adjusted data Synonyms: Raw data; unadjusted data

Example: CL_ADJUSTMENT Codelist with multi-lingual names and descriptions

Code ID Locale Code Name Code Description
K en Calendar component Synonyms: Calendar effects; calendar factors
K fr Composant de calendrier Synonymes: effets de calendrier; facteurs de calendrier
X en Seasonal component Synonyms: Seasonal effects; seasonal factors
X fr Composant saisonnier Synonymes: effets saisonniers; facteurs saisonniers
M en Seasonal and calendar components Synonyms: Seasonal and calendar effects; seasonal and calendar factors
M fr Composants saisonniers et calendaires Synonymes: effets saisonniers et calendaires; facteurs saisonniers et calendaires
I en Irregular component Synonym: Irregular effects
I fr Composant irrégulier Synonyme: effets irréguliers
N en Neither seasonally adjusted nor calendar adjusted data Synonyms: Raw data; unadjusted data
N fr Ni données désaisonnalisées ni données désaisonnalisées Synonymes: données brutes; données non ajustées

Codelists with Simple Hierarchies

SDMX allows simple hierarchies to be defined within flat Codelists by making a code the parent of codes that logically sit under it in the hierarchy.

Imagine a CL_REF_AREA Codelist containing individual codes for each European country, and a code (EUR) for Europe as a whole. A simple hierarchy for Europe can be created by setting EUR as the parent for each of the countries:

Code ID Code Name Parent
EUR Europe (none)
DE Germany EUR
FR France EUR
IT Italy EUR
GR Greece EUR
SE Sweden EUR
AU Austria EUR
PL Poland EUR

Other than acting as a parent, EUR behaves as a normal code allowing series for EUR or any of the individual contries.

A Code can only have one parent meaning that it can only appear once in a simple Codelist hierarchy. This may be restrictive where Codes can be logically organised into multiple different groups. In the CL_REF_AREA example, countries could also be grouped into trading blocs in addition to geographical regions.

SDMX Hierarchical Codelists should be used where Codelists have more complex hierarchical structures.

Hierarchical Codelists

Hierarchical Codelists are a separate structure used for describing complex hierarchies of codes, potentially including codes from multiple different codelists.

Validity

Structure-Level Validity

As a Maintainable structure, the period in time during which a complete Codelist is considered to be valid can be defined.

Item-Level Validity

Validity periods can also be defined individually for each Code item in a Codelist. A common use case involves country codes that are only valid between particular dates when the country was in ‘existence’. It also supports the case where a code changes meaning over time.

Example:
The Gilbert and Ellice Islands had the ISO country code ‘GE’ until 1977 when split to become the independent countries of Kiribati and Tuvalu. When Georgia gained independence from the former Soviet Union in 1991, the ‘GE’ code was reused. Setting the Item Validity on the GE Code allows this change in meaning to be described and stored with the Codelist.

Period up to 1977: GE = Gilbert and Ellice Islands
Period between 1977 and 1991: GE is invalid
Period from 1991 to present: GE = Georgia

In practical terms, Item Validity allows data with dimension codes that vary in meaning over time to be robustly validated and correctly disseminated.

Use Case Example
Validation Observation data for country ‘GE’ and the time period ‘1970’ must relate to the Gilbert and Ellice islands. Whereas observations for the same ‘GE’ code but for the period 2005 must relate to Georgia. Observations for country ‘GE’ during the period 1978 and 1990 will be rejected as invalid because the validity rule states that no country with that code existed between those dates.
Dissemination Visualisations showing observation data for country ‘GE’ and time period ‘1970’ will use the code named ‘Gilbert and Ellice’. When showing similar data for ‘2005’, the Item Validity rules will mean that the code named ‘Georgia’ will be displayed.