Wiki source code of 6 Codelist

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

version	line-number	content
11.2	1	{{box title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
2.1	4
18.1	5	As of [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] 3.0, Codelists have gained new features like geospatial properties, inheritance and extension. Moreover, [[hierarchies>>doc:Glossary.Hierarchy.WebHome]] (used to build complex [[hierarchies>>doc:Glossary.Hierarchy.WebHome]] of one or more Codelists) are now linked to other [[Artefacts>>doc: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.
2.1	6
	7	== 6.1 Codelist extension and discriminated unions ==
	8
18.1	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:Glossary.Code.WebHome]] Ids. When two Codelists have the same [[Code>>doc:Glossary.Code.WebHome]] Id, the Codelist referenced later takes priority. In the example below, the [[code>>doc:Glossary.Code.WebHome]] 'A', exists in both CL_INDICATOR and CL_SERIES. The Codelist CL_INDICATOR_EX will contain the [[code>>doc:Glossary.Code.WebHome]] 'A' from CL_SERIES as this was the second Codelist to be referenced in the sequence of references.
2.1	10
12.2	11	[[image:1747384656299-761.png]]
2.1	12
11.2	13	(% class="wikigeneratedid" id="HFigure7:Codelistextension" %)
	14	Figure 7: Codelist extension
2.1	15
18.1	16	As the extended Codelist, CL_INDICATOR_EX in this example, may also define its own [[Codes>>doc:Glossary.Code.WebHome]], these take the ultimate priority over any referenced Codelists. If CL_INDICATOR_EX defines [[Code>>doc:Glossary.Code.WebHome]] 'A', then this will be used instead of [[Code>>doc:Glossary.Code.WebHome]] 'A' from CL_INDICATOR and CL_SERIES, as shown below:
2.1	17
12.2	18	[[image:1747384672686-615.png]]
2.1	19
11.2	20	(% class="wikigeneratedid" id="HFigure8:CodelistextensionwithnewCodes" %)
	21	Figure 8: Codelist extension with new Codes
2.1	22
	23	=== 6.1.1 Prefixing Code Ids ===
	24
18.1	25	A reference to a Codelist may contain a prefix. If a prefix is provided, this prefix will be applied to all the [[codes>>doc: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:Glossary.Code.WebHome]], A, E, F, X, Y, SER_A, SER_B, SER_C.
2.1	26
12.2	27	[[image:1747384699130-401.png]]
2.1	28
11.2	29	(% class="wikigeneratedid" id="HFigure9:ExtendedCodelistwithprefix" %)
	30	Figure 9: Extended Codelist with prefix
2.1	31
	32	=== 6.1.2 Including / Excluding Specific Codes ===
	33
18.3	34	The default behaviour of extending another Codelist is to import all [[Codes>>doc:Glossary.Code.WebHome]]. However, an explicit list of [[Code>>doc:Glossary.Code.WebHome]] Ids may be provided for explicit inclusion or exclusion. This list of Ids may contain wildcards using the same notation as [[Constraints>>doc:Glossary.Constraint.WebHome]] ~(%). Cascading values is also supported using the same syntax as the [[Constraints>>doc: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.
2.1	35
12.2	36	[[image:1747384712935-862.png]]
2.1	37
11.2	38	(% class="wikigeneratedid" id="HFigure10:ExtendedCodelistwithinclude2Fexcludeterms" %)
	39	Figure 10: Extended Codelist with include/exclude terms
2.1	40
	41	=== 6.1.3 Parent Ids ===
	42
18.1	43	Parent Ids are preserved in the extended Codelist if they can be. If a [[Code>>doc:Glossary.Code.WebHome]] is inherited but its parent [[Code>>doc:Glossary.Code.WebHome]] is excluded, then the [[Code>>doc:Glossary.Code.WebHome]]'s parent Id will be removed. This rule is also true if the parent [[Code>>doc:Glossary.Code.WebHome]] is excluded because it is overwritten by another [[Code>>doc:Glossary.Code.WebHome]] with the same Id from another Codelist. This ensures the parent Ids do not inadvertently link to [[Codes>>doc:Glossary.Code.WebHome]] originating from different Codelists, and also prevents circular references from occurring.
2.1	44
12.2	45	(% class="wikigeneratedid" %)
	46	[[image:1747384741039-595.png]]
	47
11.2	48	(% class="wikigeneratedid" id="HFigure11:ParentCodeincluded" %)
	49	Figure 11: Parent Code included
2.1	50
12.2	51	[[image:1747384753771-913.png]]
	52
2.1	53	Figure 12: Parent Code from different extended Codelist
	54
12.2	55	[[image:1747384769943-748.png]]
	56
2.1	57	Figure 13: Parent Code overridden by local Code
	58
12.2	59	[[image:1747384788183-252.png]]
	60
2.1	61	Figure 14: Parent Code not included
	62
	63	=== 6.1.4 Discriminated Unions ===
	64
18.3	65	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 [[concepts>>doc:sdmx:Glossary.Concept.WebHome]], normally modelled as [[dimensions>>doc:sdmx:Glossary.Dimension.WebHome]] corresponding to breakdowns. Each enumerated [[concept>>doc:sdmx:Glossary.Concept.WebHome]] is associated to one and only one [[code>>doc:sdmx:Glossary.Code.WebHome]] list.
2.1	66
	67	To support this use case, the following have to be considered:
	68
18.3	69	* 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 versions of the classification have the same [[code>>doc:sdmx:Glossary.Code.WebHome]] for different [[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".
	70	* 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".
	71	* Including / Excluding Specific [[Codes>>doc:sdmx:Glossary.Code.WebHome]]: As explained above, there will be independent DFs/PAs with specific [[Constraints>>doc: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]].
2.1	72
	73	For example, assuming:
	74
18.1	75	* [[DSD>>doc:Glossary.Data structure definition.WebHome]] DSD_EXDU contains a [[Dimension>>doc:Glossary.Dimension.WebHome]]: ACTIVITY enumerated by CL_ACTIVITY.
2.1	76	* CL_ACTIVITY has no items and is extended by:
	77	* CL_ISIC4, prefix="ISIC4_"
	78	* CL_ISIC3, prefix="ISIC3_"
	79	* CL_NACE2, prefix="NACE2_"
	80	* CL_AGGR, prefix="AGGR_"
18.1	81	* [[Dataflow>>doc:Glossary.Dataflow.WebHome]] DF1, with a DataConstraint CC_NACE2, CubeRegion for ACTIVITY and Value="NACE2_%"
	82	* [[Dataflow>>doc:Glossary.Dataflow.WebHome]] DF2, with a DataConstraint CC_ISIC3, CubeRegion for ACTIVITY and Value="ISIC3_%"
	83	* [[Dataflow>>doc:Glossary.Dataflow.WebHome]] DF3, with a DataConstraint CC_ISIC4, CubeRegion for ACTIVITY and Value="ISIC4_%", Value="AGGR_TOTAL", Value="AGGR_Z"
2.1	84
18.1	85	The discriminated unions are achieved, by requesting any of the above [[Dataflows>>doc:Glossary.Dataflow.WebHome]] with references="all" and detail="referencepartial": returns CL_ACTIVITY with the corresponding extensions resolved and the DataConstraint, referencing the [[Dataflow>>doc:Glossary.Dataflow.WebHome]], applied. Thus, the CL_ACTIVITY will only include [[Codes>>doc:Glossary.Code.WebHome]] prefixed according to the [[Dataflow>>doc:Glossary.Dataflow.WebHome]], i.e.:
2.1	86
	87	* Prefix "NACE2_%" for DF1;
	88	* Prefix "ISIC3_%" fo DF2;
18.1	89	* Prefix "ISIC4_%" for DF3; note that [[Codes>>doc:Glossary.Code.WebHome]] "AGGR_TOTAL" and "AGGR_Z" are also included in this case.
2.1	90
	91	== 6.2 Linking Hierarchies ==
	92
18.1	93	To facilitate the usage of [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] within other [[SDMX>>doc:Glossary.Statistical data and metadata exchange.WebHome]] [[Artefacts>>doc:Glossary.Artefact.WebHome]], the HierarchyAssociation is defined to link any [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] with any IdentifiableArtefact within a specific context.
2.1	94
18.1	95	The HierarchyAssociation is a simple [[Artefact>>doc:Glossary.Artefact.WebHome]] operating like a Categorisation. The former specifies three references:
2.1	96
18.1	97	* The link to a [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]];
	98	* The link to the IdentifiableArtefact that the [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] is linked (e.g., a [[Dimension>>doc:Glossary.Dimension.WebHome]]);
	99	* The link to the context that the linking is taking place (e.g., a [[DSD>>doc:Glossary.Data structure definition.WebHome]]).
2.1	100
	101	As an example, let’s assume:
	102
18.1	103	* A [[DSD>>doc:Glossary.Data structure definition.WebHome]] with a COUNTRY [[Dimension>>doc:Glossary.Dimension.WebHome]] that uses Codelist CL_AREA as representation.
	104	* A [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] (e.g., EU_COUNTRIES) that builds a [[hierarchy>>doc:Glossary.Hierarchy.WebHome]] for the CL_AREA Codelist.
	105	* In order to use this [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] for data of a [[Dataflow>>doc:Glossary.Dataflow.WebHome]] (e.g., EU_INDICATORS), we need to build the following HierarchyAssociation:
	106	* Links to the [[Hierarchy>>doc:Glossary.Hierarchy.WebHome]] EU_COUNTRIES (what is associated?)
	107	* Links to the [[Dimension>>doc:Glossary.Dimension.WebHome]] COUNTRY (where is it associated?)
	108	* Links to the context: [[Dataflow>>doc:Glossary.Dataflow.WebHome]] EU_INDICATORS (when is it associated?)
2.1	109	* The above are also shown in the schematic below:
	110
13.1	111	[[image:1747384831345-304.png]]
2.1	112
	113	Figure 15: Hierarchy Association