Wiki source code of 6 Codelist

Last modified by Artur on 2025/09/10 11:19

version	line-number	content
1.1	1	{{box title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
	4
1.3	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.
1.1	6
	7	== 6.1 Codelist extension and discriminated unions ==
	8
1.3	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.
1.1	10
2.1	11	[[image:1750062803922-257.png]]
1.1	12
	13	Figure 7: Codelist extension
	14
1.3	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:
1.1	16
2.1	17	[[image:1750062830447-619.png]]
1.1	18
	19	Figure 8: Codelist extension with new Codes
	20
	21	=== 6.1.1 Prefixing Code Ids ===
	22
1.3	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.
1.1	24
2.1	25	[[image:1750062854655-955.png]]
	26
1.1	27	Figure 9: Extended Codelist with prefix
	28
	29	=== 6.1.2 Including / Excluding Specific Codes ===
	30
3.2	31	The default behaviour of extending another [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]] 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>>doc:sdmx:Glossary.Constraint.WebHome]](%%) ~(%). Cascading values is also supported using the same syntax as the (% style="color:#e74c3c" %)[[Constraints>>doc:sdmx:Glossary.Constraint.WebHome]](%%). The list of Ids is either a list of excluded items, or included items, exclusion and inclusion is not supported against a single [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]].
1.1	32
2.1	33	[[image:1750062868263-375.png]]
	34
1.1	35	Figure 10: Extended Codelist with include/exclude terms
	36
	37	=== 6.1.3 Parent Ids ===
	38
3.2	39	Parent Ids are preserved in the extended [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]] 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>>doc:sdmx:Glossary.Code list.WebHome]]. This ensures the parent Ids do not inadvertently link to [[Codes>>doc:sdmx:Glossary.Code.WebHome]] originating from different [[Codelists>>doc:sdmx:Glossary.Code list.WebHome]], and also prevents circular references from occurring.
1.1	40
2.1	41	[[image:1750062880967-585.png]]
1.1	42
1.2	43	Figure 11: Parent Code included
1.1	44
2.1	45	[[image:1750062894576-817.png]]
1.2	46
1.1	47	Figure 12: Parent Code from different extended Codelist
	48
2.1	49	[[image:1750062909999-872.png]]
1.2	50
1.1	51	Figure 13: Parent Code overridden by local Code
	52
2.1	53	[[image:1750062926702-448.png]]
1.2	54
1.1	55	Figure 14: Parent Code not included
	56
	57	=== 6.1.4 Discriminated Unions ===
	58
3.2	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 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>>doc:sdmx:Glossary.Concept.WebHome]](%%), normally modelled as [[dimensions>>doc:sdmx:Glossary.Dimension.WebHome]] corresponding to breakdowns. Each enumerated (% style="color:#e74c3c" %)[[concept>>doc:sdmx:Glossary.Concept.WebHome]](%%) is associated to one and only one [[code list>>doc:sdmx:Glossary.Code list.WebHome]].
1.1	60
	61	To support this use case, the following have to be considered:
	62
3.2	63	* Independent [[Codelists>>doc:sdmx:Glossary.Code list.WebHome]] per variant: Having each variant in a separate [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]] facilitates the maintenance and allows keeping the original [[codes>>doc:sdmx:Glossary.Code.WebHome]], even if different (% style="color:#e74c3c" %)[[versions>>doc:sdmx:Glossary.Version.WebHome]](%%) of the classification have the same [[code>>doc:sdmx:Glossary.Code.WebHome]] for different (% style="color:#e74c3c" %)[[concepts>>doc:sdmx:Glossary.Concept.WebHome]](%%). 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>>doc:sdmx:Glossary.Code list.WebHome]], the reference to an extension [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]] 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>>doc:sdmx:Glossary.Code list.WebHome]] before they are imported into the extended [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]]. In this case, the reference to CL_ISIC4 includes a prefix of "ISIC4_" and the reference to ISIC3 includes "ISIC3_", so the resulting [[Codelist>>doc:sdmx:Glossary.Code list.WebHome]] 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>>doc:sdmx:Glossary.Constraint.WebHome]](%%) attached, in order to keep the proper items according to the variant in use by each [[data provider>>doc:sdmx:Glossary.Data provider.WebHome]].
1.1	66
	67	For example, assuming:
	68
1.4	69	* [[DSD>>doc:sdmx:Glossary.Data structure definition.WebHome]] DSD_EXDU contains a [[Dimension>>doc:sdmx:Glossary.Dimension.WebHome]]: ACTIVITY enumerated by CL_ACTIVITY.
1.1	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_"
1.4	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"
1.1	78
1.4	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.:
1.1	80
	81	* Prefix "NACE2_%" for DF1;
	82	* Prefix "ISIC3_%" for DF2;
1.4	83	* Prefix "ISIC4_%" for DF3; note that [[Codes>>doc:sdmx:Glossary.Code.WebHome]] "AGGR_TOTAL" and "AGGR_Z" are also included in this case.
1.1	84
1.2	85	== 6.2 Linking Hierarchies ==
1.1	86
1.4	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.
1.1	88
1.4	89	The HierarchyAssociation is a simple [[Artefact>>doc:sdmx:Glossary.Artefact.WebHome]] operating like a Categorisation. The former specifies three references:
1.1	90
1.4	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]]).
1.1	94
	95	As an example, let’s assume:
	96
1.4	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?)
1.1	103	* The above are also shown in the schematic below:
	104
2.1	105	[[image:1750062961795-115.png]]
	106
1.1	107	Figure 15: Hierarchy Association