3 SDMX Base Package

3.1 Introduction

The constructs in the SDMX Base package comprise the fundamental building blocks that support many of the other structures in the model. For this reason, many of the classes in this package are abstract (i.e., only derived sub-classes can exist in an implementation).

The motivation for establishing the SDMX Base package is as follows:

it is accepted “Best Practise” to identify fundamental archetypes occurring in a model
identification of commonly found structures or “patterns” leads to easier understanding
identification of patterns encourages re-use

Each of the class diagrams in this section views classes from the SDMX Base package from a different perspective. There are detailed views of specific patterns, plus overviews showing inheritance between classes, and relationships amongst classes.

3.2 Base Structures - Identification, Versioning, and Maintenance

3.2.1 Class Diagram

Figure 10: SDMX Identification, Maintenance and Versioning

3.2.2 Explanation of the Diagram

3.2.2.1 Narrative

This group of classes forms the nucleus of the administration facets of SDMX objects. They provide features which are reusable by derived classes to support horizontal functionality such as identity, versioning etc.

All classes derived from the abstract class AnnotableArtefact may have Annotations (or notes): this supports the need to add notes to all SDMX-ML elements. The Annotation is used to convey extra information to describe any SDMX construct. This information may be in the form of a URL reference and/or a multilingual text (represented by the association to InternationalString).

The IdentifiableArtefact is an abstract class that comprises the basic attributes needed for identification. Concrete classes based on IdentifiableArtefact all inherit the ability to be uniquely identified.

The NamableArtefact is an abstract class that inherits from IdentifiableArtefact and in addition the +description and +name roles support multilingual descriptions and names for all objects based on NameableArtefact. The InternationalString supports the representation of a description in multiple locales (locale is similar to language but includes geographic variations such as Canadian French, US English etc.). The LocalisedString supports the representation of a description in one locale.

VersionableArtefact is an abstract class which inherits from NameableArtefact and adds versioning ability to all classes derived from it, as explained in the SDMX versioning rules in SDMX Standards Section 6 “Technical Notes”, paragraph “4.3 Versioning”.

MaintainableArtefact further adds the ability for derived classes to be maintained via its association to an Organisation, and adds locational information (i.e., from where the object can be retrieved).

The inheritance chain from AnnotableArtefact through to MaintainableArtefact allows SDMX classes to inherit the features they need, from simple annotation, through identity, naming, to versioning and maintenance.

3.2.2.2 Definitions

3.3 Basic Inheritance

3.3.1 Class Diagram – Basic Inheritance from the Base Inheritance Classes

Figure 11: Basic Inheritance from the Base Structures

3.3.2 Explanation of the Diagram

3.3.2.1 Narrative

The diagram above shows the inheritance within the base structures. The concrete classes are introduced and defined in the specific package to which they relate.

3.4 Data Types

3.4.1 Class Diagram

Figure 12: Class Diagram of Basic Data Types

3.4.2 Explanation of the Diagram

3.4.2.1 Narrative

The FacetType and FacetValueType enumerations are used to specify the valid format of the content of a non-enumerated Concept or the usage of a Concept when specified for use on a Component on a Structure (such as a Dimension in a DataStructureDefinition). The description of the various types can be found in the chapter on ConceptScheme (section 4.5).

The ActionType enumeration is used to specify the action that a receiving system should take when processing the content that is the object of the action. It is enumerated as follows:

• Append: Data or metadata is an incremental update for an existing data/metadata set or the provision of new data or documentation (attribute values) formerly absent. If any of the supplied data or metadata is already present, it will not replace that data or metadata. This corresponds to the "Update" value found in version 1.0 of the SDMX Technical Standards.
• Replace: Data/metadata is to be replaced and may also include additional data/metadata to be appended.
• Delete: Data/Metadata is to be deleted.
• Information: Data and metadata are for information purposes.

The ToValueType data type contains the attributes to support transformations defined in the StructureMap (see Section 0).

The ConstraintRoleType data type contains the attributes that identify the purpose of a Constraint (allowableContent, actualContent).

The ComponentRoleType data type contains the predefined Concept roles that can be assigned to any Component.

The CascadeValues data type contains the possible values for a MemberValue within a CubeRegion, in order to enable cascading to all children Codes of a selected Code, while including/excluding the latter in the selection.

The VersionType data types provides the details for versioning according to SDMX versioning rules, as explained in SDMX Standards Section 6, paragraph “4.3 Versioning”.

3.5 The Item Scheme Pattern

3.5.1 Context

The Item Scheme is a basic architectural pattern that allows the creation of list schemes for use in simple taxonomies, for example.

The ItemScheme is the basis for CategoryScheme, Codelist, ConceptScheme, ReportingTaxonomy, OrganisationScheme, TransformationScheme, CustomTypeScheme, NamePersonalisationScheme, RulesetScheme, VtlMappingScheme and UserDefinedOperatorScheme.

3.5.2 Class Diagram

Figure 13 The Item Scheme pattern

3.5.3 Explanation of the Diagram

3.5.3.1 Narrative

The ItemScheme is an abstract class which defines a set of Item (this class is also abstract). Its main purpose is to define a mechanism which can be used to create taxonomies which can classify other parts of the SDMX Information Model. It is derived from MaintainableArtefact which gives it the ability to be annotated, have identity, naming, versioning and be associated with an Agency. An example of a concrete class is a ConceptScheme. The associated Concepts are Items.

In an exchange environment an ItemScheme is allowed to contain a sub-set of the Items in the maintained ItemScheme. If such an ItemScheme is disseminated with a sub-set of the Items then the fact that this is a sub-set is denoted by setting the isPartial attribute to "true".

A “partial” ItemScheme cannot be maintained independently in its partial form i.e., it cannot contain Items that are not present in the full ItemScheme and the content of any one Item (e.g., names and descriptions) cannot deviate from the content in the full ItemScheme. Furthermore, the id of the ItemScheme where isPartial is set to "true" is the same as the id of the full ItemScheme (agencyId, id, version). This is important as this is the id that that is referenced in other structures (e.g., a Codelist referenced in a DSD) and this id is always the same, regardless of whether the disseminated ItemScheme is the full ItemScheme or a partial ItemScheme.

The purpose of a partial ItemScheme is to support the exchange and dissemination of a subset ItemScheme without the need to maintain multiple ItemSchemes which contain the same Items. For instance, when a Codelist is used in a DataStructureDefinition it is sometimes the case that only a sub-set of the Codes in a Codelist are relevant. In this case a partial Codelist can be constructed using the Constraint mechanism explained later in this document.

Item inherits from NameableArtefact which gives it the ability to be annotated and have identity, and therefore has id, uri and urn attributes, a name and a description in the form of an InternationalString. Unlike the parent ItemScheme, the Item itself is not a MaintainableArtefact and therefore cannot have an independent Agency (i.e., it implicitly has the same agencyId as the ItemScheme).

The Item can be hierarchic and so one Item can have child Items. The restriction of the hierarchic association is that a child Item can have only parent Item.

3.5.3.2 Definitions

3.6 The Structure Pattern

3.6.1 Context

The Structure Pattern is a basic architectural pattern which allows the specification of complex tabular structures which are often found in statistical data (such as Data Structure Definition, and Metadata Structure Definition). A Structure is a set of ordered lists. A pattern to underpin this tabular structure has been developed, so that commonalities between these structure definitions can be supported by common software and common syntax structures.

3.6.2 Class Diagrams

Figure 14: The Structure Pattern

Figure 15: Representation within the Structure Pattern

3.6.3 Explanation of the Diagrams

3.6.3.1 Narrative

The Structure is an abstract class which contains a set of one or more ComponentList(s) (this class is also abstract). An example of a concrete Structure is DataStructureDefinition.

The ComponentList is a list of one or more Component(s). The ComponentList has several concrete descriptor classes based on it: DimensionDescriptor, GroupDimensionDescriptor, MeasureDescriptor, and AttributeDescriptor of the DataStructureDefinition and MetadataAttributeDescriptor of the MetadataStructureDefinition.

The Component is contained in a ComponentList. The type of Component in a ComponentList is dependent on the concrete class of the ComponentList as follows:

DimensionDescriptor: Dimension, TimeDimension
GroupDimensionDescriptor: Dimension, TimeDimension
MeasureDescriptor: Measure
AttributeDescriptor: DataAttribute, MetadataAttributeRef
MetadataAttributeDescriptor: MetadataAttribute

Each Component takes its semantic (and possibly also its representation) from a Concept in a ConceptScheme. This is represented by the conceptIdentity association to Concept.

The Component may also have a localRepresentation. This allows a concrete class, such as Dimension, to specify its representation which is local to the Structure in which it is contained (for Dimension this will be DataStructureDefinition), and thus overrides any coreRepresentation specified for the Concept.

The Representation can be enumerated or non-enumerated. The valid content of an enumerated representation is specified either in an ItemScheme which can be one of Codelist, ValueList or GeoCodelist. The valid content of a non-enumerated representation is specified as one or more Facet(s) (for example, these may specify minimum and maximum values). For any Attribute this is achieved by one of more ExtendedFacet(s), which allow the additional representation of XHTML.

The types of representation that are valid for specific components is expressed in the model as a constraint on the association:

• The Dimension, DataAttribute, Measure, MetadataAttribute may be enumerated and, if so, use an EnumeratedList.
• The Dimension and Measure may be non-enumerated and, if so, use one or more Facet(s), note that the FacetValueType applicable to the TimeDimension is restricted to those that represent time.
• The MetadataAttribute and DataAttribute may be non-enumerated and, if so, use one or more ExtendedFacet(s).

The Structure may be used by one or more StructureUsage(s). An example of this, in terms of concrete classes, is that a Dataflow (sub class of StructureUsage) may use a particular DataStructureDefinition (sub class of Structure), and similar constructs apply for the Metadataflow (link to MetadataStructureDefinition).

3.6.3.2 Definitions

The specification of the content and use of the sub classes to ComponentList and Component can be found in the section in which they are used (DataStructureDefinition and MetadataStructureDefinition). Moreover, the FacetType SentinelValues is explained in the datastructure representation diagram (see 5.3.2.2), since it only concerns DataStructureDefinitions.

3.6.3.3 Representation Constructs

The majority of SDMX FacetValueTypes are compatible with those found in XML Schema, and have equivalents in most current implementation platforms:

There are also a number of SDMX data types which do not have these direct correspondences, often because they are composite representations or restrictions of a broader data type. These are detailed in Section 6 of the standards.

The Representation is composed of Facets, each of which conveys characteristic information related to the definition of a value domain. Often a set of Facets are needed to convey the required semantic. For example, a sequence is defined by a minimum of two Facets: one to define the start value, and one to define the interval.

1. ^ In the JSON schemas, more complex data types are complemented with regular expressions, whenever no direct mapping to a standard type exists.