Codelists in eForms
Vocabularies
The Publications Office of the European Union (OP) has defined and published many vocabularies for use across a wide range of sectors on the EU Vocabularies website.
A subset of these vocabularies are relevant to the domain of eProcurement; most of these are flat lists of terms and their definitions; some, such as the NUTS (Nomenclature of Territorial Units for Statistics) are hierarchical taxonomies. They are listed on the Authority tables and taxonomies used in eProcurement page.
Codelists
A codelist is a flat (non-hierarchical) implementation of a vocabulary: a list of language-independent codes that represent an agreed set of values for a particular data context.
Codelists in eForms
Codelists are used in eForms notices to restrict the values of some data items. Each code has a short label. The majority of codelists also have descriptions in each of the 24 official EU languages for every code. Codelists for language- or geographic-dependent codes, such as the NUTS codes, do not have such translations.
Format of codelists
EU Vocabularies provides the codelists in a number of different formats for use in different applications. The format chosen for use in the eForms SDK is the OASIS Genericode XML format, which was designed for the interchange of machine-readable codelists.
Information on codelists
The file named codelists.json
provides information on each codelist.
{
"ublVersion" : "2.3", (1)
"sdkVersion" : "1.0.0", (2)
"metadataDatabase" : { (3)
"version" : "1.0.0",
"createdOn" : "2022-08-05T10:24:40"
},
"codelists" : [
{
"id" : "accelerated-procedure", (4)
"parentId" : "indicator", (5)
"filename" : "indicator_accelerated-procedure.gc", (6)
"description" : "List of codes to specify whether a procedure is accelerated or not.", (7)
"_label" : "codelist|name|accelerated-procedure" (8)
},
...
]
}
1 | Version of the UBL standard used. |
2 | Version of the eForms SDK the file belongs to. |
3 | Version number and date of the data used to create this file. |
4 | Identifier of the codelist. |
5 | Identifier of the parent codelist, if the codelist is a tailored codelist. |
6 | Name of the file containing the codelist. |
7 | Description of the codelist. |
8 | Identifier of the label for the name of the codelist. The label is available in the translations folder. |
In eForms, codelists are referenced using their identifier. The identifier is also indicated in the codelist Genericode files, in the "LongName" element which has no attributes:
<LongName>accelerated-procedure</LongName>
Types of codelists
There are three types of codelist used in eForms, based on their source and applicability:
-
Entire codelists from the EU Vocabularies site
-
Tailored codelists
-
Technical codelists
Entire codelists
These are eProcurement codelists published and maintained on the Authority tables and taxonomies used in eProcurement page of EU Vocabularies. They are used as provided, no changes are made, and all codes are available for use in the relevant eForms XML elements. The canonical source of these codelists is the EU Vocabularies website.
Tailored codelists
Where only a subset of codes included in an eProcurement codelist are allowed or applicable in a particular eForms context, a new tailored codelist has been created with only those codes. The labels and translations for these codes in these tailored codelists are the same as in the "parent" codelists. Since these codelists have no relevance or use outside the context of eForms, they are not published on the EU Vocabularies website, but are published as part of the eForms SDK.
For example, the "language" codelist has codes for thousands of languages. The business term BT-702 "Notice Official Language" designates an EU Official language in which the notice is officially available. Only one of the 24 EU Official languages is permitted. So a tailored codelist named "EU Official Language" has been created. This codelist contains the entries for these 24 EU languages, copied from the parent "Language" codelist.
As another example, the business terms BT-10 "Activity Authority" and BT-610 "Activity Entity" each use a different subset of codes from the same eProcurement "Main activity" codelist. Two new tailored codelists have been created, "Authority Activity" and "Entity Activity", which each contain the relevant codes.
Filenames of tailored codelist
The filenames of the tailored codelists are composed of two parts, separated by an underscore character "_":
-
the name of the parent codelist, from which the codes are copied,
-
the name of the tailored codelist.
Each part follows the same convention as used for the eProcurement codelists: the name of the codelist, with spaces replaced by hyphens, and all in lower case.
Parent codelist name |
Parent codelist filename |
Tailored codelist name |
Tailored codelist filename |
Language |
language.gc |
EU Official Language |
language_eu-official-language.gc |
Main activity |
main-activity.gc |
Authority Activity |
main-activity_authority-activity.gc |
Entity Activity |
main-activity_entity-activity.gc |
Additional information in genericode files
Some new elements have been added within the <Identification> element in the genericode files for tailored codelists.
<LongName Identifier="listId">http://publications.europa.eu/resource/authority/main-activity</LongName> (1)
<LongName Identifier="eFormsParentId">main-activity</LongName> (2)
<Version>0.2.19</Version> (3)
1 | URI of the parent codelist |
2 | Identifier of the parent codelist |
3 | Version number of the data used to create this file |
Technical codelists
The UBL schema was chosen to define the XML structure for eForms notices due to its wide use for representing business documents across many domains, and its very close match to eForms data requirements. However, there are some contexts where the UBL elements available are not sufficient to represent the Business Terms needed by the context. In these cases new codelists have been created to implement the required Business Terms. These technical codelists are also published in the eForms SDK.
Codelists in eForms notice XML
In eForms XML, codes and codelists are mostly referenced using elements designed for that purpose. The elements have names which end in "Code", and have the attribute "listName". This attribute is used to hold the identifier of the codelist, and the code value required is set as the content of the element. In eForms, only codes from one codelist are allowed for any specific element.
The example below shows an example of using the code value "supplies" from the "contract-nature" codelist.
<cbc:ProcurementTypeCode listName="contract-nature">supplies</cbc:ProcurementTypeCode>
Validation of codes and codelists
The Schematron rules that are included as part of the eForms SDK contain rules to validate the correct use of codelists in a notice XML file. The rules check that for each element which should reference a code:
-
the correct codelist is named in the "listName" attribute
-
the content of the element is one of the codes from that codelist