Skip to Content

Wiki source code of 6 Codelist

Version 2.1 by Helena on 2025/06/16 11:36
Show last authors
1 {{box title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 As of [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0, Codelists have gained new features like geospatial properties, inheritance and extension. Moreover, [[hierarchies>>doc:sdmx:Glossary.Hierarchy.WebHome]] (used to build complex [[hierarchies>>doc:sdmx:Glossary.Hierarchy.WebHome]] of one or more Codelists) are now linked to other [[Artefacts>>doc:sdmx:Glossary.Artefact.WebHome]] in order to facilitate the formers' usage in dissemination or other scenarios. For all geospatial related features, as well as the new Geographical Codelist, please refer to section 7.
6
7 == 6.1 Codelist extension and discriminated unions ==
8
9 A Codelist can extend one or more Codelists. Codelist extensions are defined as a list of references to parent Codelists. The order of the references is important when it comes to conflict resolution on [[Code>>doc:sdmx:Glossary.Code.WebHome]] Ids. When two Codelists have the same [[Code>>doc:sdmx:Glossary.Code.WebHome]] Id, the Codelist referenced later takes priority. In the example below, the [[code>>doc:sdmx:Glossary.Code.WebHome]] 'A', exists in both CL_INDICATOR and CL_SERIES. The Codelist CL_INDICATOR_EX will contain the [[code>>doc:sdmx:Glossary.Code.WebHome]] 'A' from CL_SERIES as this was the second Codelist to be referenced in the sequence of references.
10
11 [[image:1750062803922-257.png]]
12
13 **Figure 7: Codelist extension**
14
15 As the extended Codelist, CL_INDICATOR_EX in this example, may also define its own [[Codes>>doc:sdmx:Glossary.Code.WebHome]], these take the ultimate priority over any referenced Codelists. If CL_INDICATOR_EX defines [[Code>>doc:sdmx:Glossary.Code.WebHome]] 'A', then this will be used instead of [[Code>>doc:sdmx:Glossary.Code.WebHome]] 'A' from CL_INDICATOR and CL_SERIES, as shown below:
16
17 [[image:1750062830447-619.png]]
18
19 **Figure 8: Codelist extension with new Codes**
20
21 === 6.1.1 Prefixing Code Ids ===
22
23 A reference to a Codelist may contain a prefix. If a prefix is provided, this prefix will be applied to all the [[codes>>doc:sdmx:Glossary.Code.WebHome]] in the Codelist before they are imported into the extended Codelist. Following the above example if the CL_SERIES reference includes a prefix of 'SER_' then the resulting Codelist would contain 7 [[codes>>doc:sdmx:Glossary.Code.WebHome]], A, E, F, X, Y, SER_A, SER_B, SER_C.
24
25 [[image:1750062854655-955.png]]
26
27 **Figure 9: Extended Codelist with prefix**
28
29 === 6.1.2 Including / Excluding Specific Codes ===
30
31 The default behaviour of extending another Codelist is to import all [[Codes>>doc:sdmx:Glossary.Code.WebHome]]. However, an explicit list of [[Code>>doc:sdmx:Glossary.Code.WebHome]] Ids may be provided for explicit inclusion or exclusion. This list of Ids may contain wildcards using the same notation as (% style="color:#e74c3c" %)Constraints(%%) ~(%). Cascading values is also supported using the same syntax as the (% style="color:#e74c3c" %)Constraints(%%). The list of Ids is either a list of excluded items, or included items, exclusion and inclusion is not supported against a single Codelist.
32
33 [[image:1750062868263-375.png]]
34
35 **Figure 10: Extended Codelist with include/exclude terms**
36
37 === 6.1.3 Parent Ids ===
38
39 Parent Ids are preserved in the extended Codelist if they can be.  If a [[Code>>doc:sdmx:Glossary.Code.WebHome]] is inherited but its parent [[Code>>doc:sdmx:Glossary.Code.WebHome]] is excluded, then the [[Code>>doc:sdmx:Glossary.Code.WebHome]]'s parent Id will be removed. This rule is also true if the parent [[Code>>doc:sdmx:Glossary.Code.WebHome]] is excluded because it is overwritten by another [[Code>>doc:sdmx:Glossary.Code.WebHome]] with the same Id from another Codelist.  This ensures the parent Ids do not inadvertently link to [[Codes>>doc:sdmx:Glossary.Code.WebHome]] originating from different Codelists, and also prevents circular references from occurring.
40
41 [[image:1750062880967-585.png]]
42
43 **Figure 11: Parent Code included**
44
45 [[image:1750062894576-817.png]]
46
47 **Figure 12: Parent Code from different extended Codelist**
48
49 [[image:1750062909999-872.png]]
50
51 **Figure 13: Parent Code overridden by local Code**
52
53 [[image:1750062926702-448.png]]
54
55 **Figure 14: Parent Code not included**
56
57 === 6.1.4 Discriminated Unions ===
58
59 A common use case solved in [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] 3.0 is that of discriminated unions, i.e., dealing with classification or breakdown "variants" which are all valid but mutually exclusive. For example, there are many (% style="color:#e74c3c" %)versions(%%) of the international classification for [[economic activities>>doc:sdmx:Glossary.Economic activity.WebHome]] "ISIC". In [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]], classifications are enumerated (% style="color:#e74c3c" %)concepts(%%), normally modelled as [[dimensions>>doc:sdmx:Glossary.Dimension.WebHome]] corresponding to breakdowns. Each enumerated (% style="color:#e74c3c" %)concept(%%) is associated to one and only one [[code>>doc:sdmx:Glossary.Code.WebHome]] list.
60
61 To support this use case, the following have to be considered:
62
63 * **Independent Codelists per variant**: Having each variant in a separate Codelist facilitates the maintenance and allows keeping the original [[codes>>doc:sdmx:Glossary.Code.WebHome]], even if different (% style="color:#e74c3c" %)versions(%%) of the classification have the same [[code>>doc:sdmx:Glossary.Code.WebHome]] for different (% style="color:#e74c3c" %)concepts(%%). For example, in ISIC Rev. 4 the [[code>>doc:sdmx:Glossary.Code.WebHome]] "A" represents "Agriculture, forestry and fishing", while in ISIC 3.1 "A" means "Agriculture, hunting and forestry".
64 * **Prefixing [[Code>>doc:sdmx:Glossary.Code.WebHome]] Ids**: When extending Codelists, the reference to an extension Codelist may contain a prefix. If a prefix is provided, this prefix will be applied to all the [[codes>>doc:sdmx:Glossary.Code.WebHome]] in the Codelist before they are imported into the extended Codelist.  In this case, the reference to CL_ISIC4 includes a prefix of "ISIC4_" and the reference to ISIC3 includes "ISIC3_", so the resulting Codelist will have no conflict for the "A" items which will become "ISIC3_A" and "ISIC4_A".
65 * **Including / Excluding Specific [[Codes>>doc:sdmx:Glossary.Code.WebHome]]**: As explained above, there will be independent DFs/PAs with specific (% style="color:#e74c3c" %)Constraint(%%) attached, in order to keep the proper items according to the variant in use by each [[data provider>>doc:sdmx:Glossary.Data provider.WebHome]].
66
67 For example, assuming:
68
69 * [[DSD>>doc:sdmx:Glossary.Data structure definition.WebHome]] DSD_EXDU contains a [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]]: ACTIVITY enumerated by CL_ACTIVITY.
70 * CL_ACTIVITY has no items and is extended by:
71 * CL_ISIC4, prefix="ISIC4_"
72 * CL_ISIC3, prefix="ISIC3_"
73 * CL_NACE2, prefix="NACE2_"
74 * CL_AGGR, prefix="AGGR_"
75 * [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] DF1, with a DataConstraint CC_NACE2, CubeRegion for ACTIVITY and Value="NACE2_%"
76 * [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] DF2, with a DataConstraint CC_ISIC3, CubeRegion for ACTIVITY and Value="ISIC3_%"
77 * [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] DF3, with a DataConstraint CC_ISIC4, CubeRegion for ACTIVITY and Value="ISIC4_%", Value="AGGR_TOTAL", Value="AGGR_Z"
78
79 The discriminated unions are achieved, by requesting any of the above [[Dataflows>>doc:sdmx:Glossary.Dataflow.WebHome]] with references="all" and detail="referencepartial": returns CL_ACTIVITY with the corresponding extensions resolved and the DataConstraint, referencing the [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]], applied. Thus, the CL_ACTIVITY will only include [[Codes>>doc:sdmx:Glossary.Code.WebHome]] prefixed according to the [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]], i.e.:
80
81 * Prefix "NACE2_%" for DF1;
82 * Prefix "ISIC3_%" for DF2;
83 * Prefix "ISIC4_%" for DF3; note that [[Codes>>doc:sdmx:Glossary.Code.WebHome]] "AGGR_TOTAL" and "AGGR_Z" are also included in this case.
84
85 == 6.2 Linking Hierarchies ==
86
87 To facilitate the usage of [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] within other [[SDMX>>doc:sdmx:Glossary.Statistical data and metadata exchange.WebHome]] [[Artefacts>>doc:sdmx:Glossary.Artefact.WebHome]], the HierarchyAssociation is defined to link any [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] with any IdentifiableArtefact within a specific context.
88
89 The HierarchyAssociation is a simple [[Artefact>>doc:sdmx:Glossary.Artefact.WebHome]] operating like a Categorisation. The former specifies three references:
90
91 * The link to a [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]];
92 * The link to the IdentifiableArtefact that the [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] is linked (e.g., a [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]]);
93 * The link to the context that the linking is taking place (e.g., a [[DSD>>doc:sdmx:Glossary.Data structure definition.WebHome]]).
94
95 As an example, let’s assume:
96
97 * A [[DSD>>doc:sdmx:Glossary.Data structure definition.WebHome]] with a **COUNTRY** [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]] that uses Codelist **CL_AREA** as representation.
98 * A [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] (e.g., **EU_COUNTRIES**) that builds a [[hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] for the **CL_AREA** Codelist.
99 * In order to use this [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] for data of a [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] (e.g., **EU_INDICATORS**), we need to build the following HierarchyAssociation:
100 * Links to the [[Hierarchy>>doc:sdmx:Glossary.Hierarchy.WebHome]] **EU_COUNTRIES (what is associated?)**
101 * Links to the [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]] **COUNTRY (where is it associated?)**
102 * Links to the context: [[Dataflow>>doc:sdmx:Glossary.Dataflow.WebHome]] **EU_INDICATORS (when is it associated?)**
103 * The above are also shown in the schematic below:
104
105 [[image:1750062961795-115.png]]
106
107 **Figure 15: Hierarchy Association**