Skip to content

Concept Scheme

A Concept Scheme is an item scheme of concepts: the definitions used by the components of data and metadata structures. A concept may have a parent concept, a core representation (a codelist, value list or text format), and a reference to an ISO concept. A concept scheme document starts ref: "ConceptScheme=AGENCY:ID(1.0)".

Simple form

The document is the common header followed by a list of concepts. Each concept is a single ID: "name" pair.

format: "fusion-yaml(1.0.0)"
ref: "ConceptScheme=TEST:TEST(1.0)"
name: "TEST"
items:
- FREQ: "FREQ-Name"
- REF_AREA: "REF_AREA-Name"
- INDICATOR: "INDICATOR-Name"
- TIME_PERIOD: "TIME_PERIOD-Name"
- OBS_VALUE: "OBS_VALUE-Name"

Source: conceptscheme/testNonRepresented.yaml (trimmed)

  • items is the list of concepts, in the order they are held in the scheme (concepts are not sorted).
  • Each concept is written as ID: "name", where the name is the English name. This is the simple form of an item.

Complex form

A concept is written in the simple form only when it has nothing to say other than its id and its English name. As soon as it carries more information it becomes an object, keyed by its id.

format: "fusion-yaml(1.0.0)"
ref: "ConceptScheme=TEST:TEST(1.0)"
name: "TEST"
items:
- CONTACT: "Contact"
- PHONE:
    name: "Phone Number"
    parent: "CONTACT"
- REF_AREA:
    name: "REF_AREA-Name"
    codelist: "ACY:CL_REF(1.0)"
    isoConcept: "Concept=ISO:ISO_CONCEPTS(1.0).COUNTRY"
- A1:
    name: "A1-Name"
    codelist: "ACY:CL_REF(1.0)"
    maxLength: 3
    minLength: 1
- A2:
    name: "A2-Name"
    valuelist: "ACY:VL_REF(1.0)"
- A5:
    name: "A5-Name"
    textType: "Alpha"

Based on conceptscheme/testParentConcepts.yaml, conceptscheme/testIsoConceptReference.yaml and conceptscheme/testRepresentations.yaml (the codelist on REF_AREA is added).

A concept is written as a string (- FREQ: "Frequency") when all of the following are true:

  • it has exactly one name, and that name is in English;
  • it has no description;
  • it has no URI;
  • it has no validity period;
  • it has no parent concept and no parent agency;
  • it has no core representation;
  • it has no ISO concept reference;
  • it has no annotations and no links.

If any one of these is not true, the concept is written as an object. Inside the object the fields are written in this order:

  1. name, name-<locale>, description, description-<locale>, as localised text.
  2. uri, the concept's URI.
  3. validFrom and validTo, the start and end of the concept's validity period, each written only if set.
  4. parent, the id of the parent concept. The concepts are always written as a flat list; the hierarchy is expressed only through parent.
  5. parentAgency, the agency of the parent concept.
  6. The core representation, see representation: the enumeration reference keyed by its lower-case class (codelist, valuelist, geographiccodelist, geogridcodelist), then the text format fields (textType, maxLength, minLength, …), then minOccurs and maxOccurs.
  7. isoConcept, the reference to the ISO concept in canonical form, e.g. "Concept=ISO:ISO_CONCEPTS(1.0).COUNTRY". The class is part of the value, as the field name is fixed (see references).
  8. annotations and links.

Note

The validity of a concept is written as two fields, validFrom and validTo, each an SDMX date string. This differs from codes, whose validity is a single validity period field.

The numeric text format fields (maxLength, minLength, decimals, minValue, maxValue, startValue, endValue and interval) are written as unquoted numbers (maxLength: 3).

Field reference

Body fields, written after the common header:

Field Value Written when
partial true The concept scheme is partial.
items Array of concepts, each ID: "name" or ID: {object} The scheme has at least one concept.

Concept object fields (items[].<ID>), used when the concept is not simple:

Field Value Written when
name, name-<locale> String The concept has a name in that locale.
description, description-<locale> String The concept has a description in that locale.
uri String The concept has a URI.
validFrom SDMX date string The concept has a validity period with a start.
validTo SDMX date string The concept has a validity period with an end.
parent Id of the parent concept The concept has a parent.
parentAgency String The concept has a parent agency.
codelist / valuelist / geographiccodelist / geogridcodelist Short URN of the enumeration The core representation is enumerated.
textType Text type, e.g. "String", "Decimal" The core representation has a text type.
maxLength, minLength Number, e.g. 3 Set on the text format.
maxValue, minValue, startValue, endValue, interval Number Set on the text format.
startTime, endTime SDMX date string Set on the text format.
timeInterval Duration string Set on the text format.
pattern String Set on the text format.
multilingual true The text format is multilingual.
decimals Number Set on the text format.
sequence true The text format is a sequence.
minOccurs Number Set on the core representation.
maxOccurs Number, or "unbounded" Set on the core representation.
isoConcept Canonical reference, e.g. "Concept=ISO:ISO_CONCEPTS(1.0).COUNTRY" The concept references an ISO concept.
annotations Array, see annotations The concept has annotations.
links Array, see links The concept has links.

Reading notes

  • A concept written as ID: "name" is read as a concept with a single English name and no core representation.
  • Any representation field (enumeration reference, text format field, minOccurs, maxOccurs) on a concept object creates the concept's core representation; all such fields of one concept are collected into the same representation.