Code List Catalogue
1. General Information
1.1. Codes and Identifiers
A code is a shortened way (a number, or a short abbreviated text), leading to the definition of a 'concept'. The code represents the concept and is used by software applications to retrieve the definition of the concept or make automatic decisions.
An Identifier, in turn, can be defined as "a value (represented as a short text, a number or a combination of both) used to establish the identity of, and distinguish uniquely, one occurrence of an object following a pattern".
The essential distinctive features between identifiers and codes are:
-
Identifiers point at specific occurrences of objects (instances); codes replace concepts;
-
Identifiers are virtually limitless while codes are finite. In other words, identifier lists are "open" (the lists may grow) and code list are "closed" (practically never updated once consolidated). Hence codes are maintained in 'Codelists' whilst identifiers are usually kept in databases.
-
Identifiers are in principle maintained in the business domain, e.g. buyer identifiers, economic operator identifiers, exclusion or selection criteria identifiers, etc.
-
Codes may belong to three different domains:
-
they can be somehow 'business-agnostic' and be used cross-domain (e.g. country codes, currency codes, language codes, etc.);
-
business-specific domain (i.e. procurement specific, like codes representing contract types, procurement procedure types, criteria types, etc.); and
-
business process-specific, i.e. ESPD-specific, such as the data type expected in the response to a criterion, or the type of a criterion property, etc.
-
1.2. Codes and code lists
The ESPD Exchange Data Model tries to reuse as the codes that are already used for e-Procurement much as possible. In any project, like the ESPD-EDM, there are at least three types (or layers) of codes:
-
Cross-sector, common, codes, like the ones defined and maintained by the ISO for currencies, languages, countries, etc.; or the ones defined by the European Commission that can be used in multiple business domains, e.g. the NUTS defined by EUROSTAT; the ones defined by BACH (Banque de France), etc.;
-
Business domain-related, maintained by international or European authorities, e.g. the ones defined by UNECE (as unit codes), or by the Publications Office of the European Union (OP), e.g. types of procurement procedures (based on the EU Directives);
-
Project-specific (or application-specific), i.e. those codes that are particular of the project. Types (taxonomy) of exclusion and selection criteria, types of evaluation method, etc. in the case of the ESPD-EDM.
Codes are normally maintained in "code lists". The ESPD-EDM keeps and distributes these code lists in Genericode 1.0 (GC) files (one *.gc file per code list).
The ESPD reuses code lists from EU Vocabularies. This is to facilitate alignment between the ESPD and eForms models, ensuring maximum interoperability. The excel and code list files themselves are not provided, their metadata and their location in EU Vocabularies is given.
| For Genericodes it is different. In this version ESPD provides the genericode (gc) files from EU Vocabularies to ensure its use and validation. In future versions of the ESPD, only the GC of the code lists used and maintained by ESPD will be provided. |
ESPD-EDM Code list contains the following elements:
-
Metadata: information about the code list, e.g. its identifier, the identifier and name of the agency responsible for defining and maintaining the list, the version of the list, etc.
-
Code identifier: the literal (a label composed of characters, numbers and symbols like '_');
-
Concept description: the definition of the concept represented by the code;
-
Multilingual descriptions: the translations of the English definitions.
The figure below illustrates how these elements are organised in the code lists maintained in spread-sheets:
Figure 6. Elements and metadata of an ESPD code list
1.3. Compulsory attributes
Table 1. ESPD Requirement regarding codes
REQUIREMENT: |
For codes, this ESPD specification requires always three mandatory attributes: listID, listAgencyID, and listVersionID. |
Table 2. ESPD Requirement regarding identifiers
REQUIREMENT: |
For identifiers, this ESPD specification requires at least (and always) the mandatory attribute schemeAgencyID. When identifying parties, like the Economic Operator, the Buyer, etc., the attribute schemeID SHOULD also be used (for this use the code list EOIDType). |
In UBL Codes and identifiers are based on ebXML Core components (UBL conforms to ebXML CCTS ISO/TS 15000-5:2005 currently maintained by UN/CEFACT).
One convenient characteristic of these two CCT elements (Codes and Identifiers) is that they use a rich set of attributes that allow to identify their pattern, the name of the list, the URI from where to obtain the list, the Agency that maintains the list, the version of the list, and other.
UBL-2.3 CCT are defined in the file CCTS_CCT_SchemaModule-2.3.xsd (see folders xsd/common or xsdrt/common in the distribution package).
The figure below shows the complete list of attributes for the CCT CodeType component.
Figure 7. Code attributes
And its corresponding definitions, as provided by OASIS UBL (ISO/IEC 19845):
Table 3. UBL attributes for codes
Attribute |
Definition |
listID |
The identification of a list of codes (MANDATORY in this version of ESPD). |
listAgencyID |
An agency that maintains one or more lists of codes (MANDATORY in this version of ESPD). |
listAgencyName |
The name of the agency that maintains the list of codes. |
listName |
The name of a list of codes. |
listVersionID |
The version of the list of codes (MANDATORY in this version of ESPD). |
name |
The textual equivalent of the code content component. |
languageID |
The identifier of the language used in the code name. |
listURI |
The Uniform Resource Identifier that identifies where the code list is located. |
listSchemeURI |
The Uniform Resource Identifier that identifies where the code list scheme is located. |
This other figure shows the attributes for the CCT `IdentifierType`component.
Figure 8. Identifier attributes
Table 4. UBL attributes for identifiers and corresponding definitions, as provided by OASIS UBL (ISO/IEC 19845):
Attribute |
Definition |
schemeID |
The identification of the identification scheme. |
schemeName |
The name of the identification scheme. |
schemeAgencyID |
The identification of the agency that maintains the identification scheme (MANDATORY in this version of ESPD). |
schemeAgencyName |
The name of the agency that maintains the identification scheme. |
schemeVersionID |
The version of the identification scheme. |
schemeDataURI |
The Uniform Resource Identifier that identifies where the identification scheme data is located. |
schemeURI |
The Uniform Resource Identifier that identifies where the identification scheme is located. |
1.4. XML Example
This fragment of XML shows how the compulsory attributes are used for the some of the root elements of an ESPD Request document.
1.4.1. Code with callouts
| The source code can be copied from the code block below the callout section |
(1)
<cbc:UBLVersionID schemeAgencyID="OASIS-UBL-TC">2.3</cbc:UBLVersionID>
(2)
<cbc:ID schemeAgencyID="DGPE">ESPDREQ-DGPE-3b5755dfb8</cbc:ID>
<cbc:UUID schemeID="ISO/IEC 9834-8:2008" schemeAgencyID="OP"
(3)
schemeVersionID="4">0fddbf2d-1e33-4267-b04f-52b59b72ccb6</cbc:UUID>
(4)
<cbc:ContractFolderID schemeAgencyID="DGPE">PP.20170419.1024-9</
cbc:ContractFolderID>
(5)
<cbc:VersionID schemeAgencyID="OP" schemeVersionID="3.3.0">1.0</cbc:VersionID>
| 1 | The Agency responsible for the maintenance of the UBL versioning is the OASIS UBL Technical Committee |
| 2 | The identifier for this document was issued by the a Spanish Central Government Directorate identified as 'DGPE' |
| 3 | The UUID follows the ISO/IEC Scheme 9834-8:2008 Version 4 and was generated by the European Commission’s Directorate General GROWTH (DG GROW) |
| 4 | The reference number used to identify to which procurement procedure this ESPD document belongs (PP.20170419.1024-9) has been supplied by the Spanish Directorate DGPE |
| 5 | Generic information, such as the content version ID, use always by default the "OP" Agency ID. Notice that the other additional attributes may be also used, as in this example. |
Beware that the codes may be numbers, text or combinations of both. These code labels are the ones that are specified in the codelist spreadsheets and XML Genericode files distributed jointly with this specification (in the folder /codelists of the distribution package.
1.4.2. Copy the code block
<cbc:UBLVersionID schemeAgencyID="OASIS-UBL-TC">2.3</cbc:UBLVersionID>
<cbc:ID schemeAgencyID="DGPE">ESPDREQ-DGPE-3b5755dfb8</cbc:ID>
<cbc:UUID schemeID="ISO/IEC 9834-8:2008" schemeAgencyID="OP"
schemeVersionID="4">0fddbf2d-1e33-4267-b04f-52b59b72ccb6</cbc:UUID>
<cbc:ContractFolderID schemeAgencyID="DGPE">PP.20170419.1024-9</cbc:ContractFolderID>
<cbc:VersionID schemeAgencyID="OP" schemeVersionID="3.3.0">1.0</cbc:VersionID>xml1.5. Code list that IS NOT used for CODE values
Code lists contain the code identifiers that are expected as "values" for a data element of type CODE (i.e. a UBL-2.3. cbc:CodeType element). This is case of code lists such as eo-role-type, or docref-content-type, etc.
However, this ESP-EDM specification also uses the code list EOIDType with a different purpose, "the identification of the type of scheme used to identify parties, namely Economic Operators" (but should also used to identify the schemes used to identify Buyers, Service Providers, etc.).
The figure below shows the possible values of this code list. These codes are to be used as values of the schemeID attribute (attribute of the UBL-2.3 element cbc:Identifier):
Figure 9. Values of the schemeID for Party Identifiers
The next fragment of XML shows how this is used in the particular case of the Criterion "Relied on entities" ("Does the economic operator rely on the capacities of other entities in order to meet the selection criteria…?").:
TenderingCriterionProperty (a QUESTION) asking for the identifier of the Economic Operator
1.6. XML Example
1.6.1. Code with callouts
| The source code can be copied from the code block below the callout section |
<cac:TenderingCriterionProperty>
<cbc:ID schemeID="Criterion" schemeAgencyID="OP" schemeVersionID="3.3.0">
1fa05728-308f-43b0-b547-c903ffb0a8af
(1)
</cbc:ID>
<cbc:Description>ID of the economic operator</cbc:Description>
<cbc:TypeCode listID="criterion-element-type" listAgencyID="OP" listVersionID="3.3.0">QUESTION</cbc:TypeCode>
<cbc:ValueDataTypeCode listID="response-data-type" listAgencyID="OP" listVersionID="3.3.0">
ECONOMIC_OPERATOR_IDENTIFIER
(2)
</cbc:ValueDataTypeCode>
</cac:TenderingCriterionProperty>
| 1 | The identifier of the property will be used in the response to map link the response to this QUESTION. |
| 2 | The ECONOMIC_OPERATOR_IDENTIFIER is mapped to an element cbc:ResponseID in the response (which is based on the UBL-2.3. element cbc:Identifier). |
1.6.2. Copy the code block
<cac:TenderingCriterionProperty>
<cbc:ID schemeID="Criterion" schemeAgencyID="OP" schemeVersionID="3.3.0">
1fa05728-308f-43b0-b547-c903ffb0a8af
</cbc:ID>
<cbc:Description>ID of the economic operator</cbc:Description>
<cbc:TypeCode listID="criterion-element-type" listAgencyID="OP" listVersionID="3.3.0">QUESTION</cbc:TypeCode>
<cbc:ValueDataTypeCode listID="response-data-type" listAgencyID="OP" listVersionID="3.3.0">
ECONOMIC_OPERATOR_IDENTIFIER
</cbc:ValueDataTypeCode>
</cac:TenderingCriterionProperty>xmlTenderingCriterionResponse (the answer to the previous QUESTION)
1.7. XML Example
1.7.1. Code with callouts
| The source code can be copied from the code block below the callout section |
<cac:TenderingCriterionResponse>
<cbc:ID schemeID="ISO/IEC 9834-8:2008 - 4UUID" schemeAgencyID="OP" schemeVersionID="3.3.0">acb58f0e-0fe4-4372-aa08-60d0c36bfcfe</cbc:ID>
<cbc:ValidatedCriterionPropertyID schemeID="Criterion" schemeAgencyID="OP" schemeVersionID="3.3.0">
1fa05728-308f-43b0-b547-c903ffb0a8af
(1)
</cbc:ValidatedCriterionPropertyID>
<cbc:ResponseID schemeID="VAT" schemeAgencyID="ES-AEAT">
B82387770
(2)
</cbc:ResponseID>
</cac:TenderingCriterionResponse>
| 1 | Notice that this UUID is identical to the QUESTION UUID, which is the mechanism used in UBL to link the answer to the very specific QUESTION it is responding. |
| 2 | The element cbc:ResponseID is of type Identifier(as defined in the Core Component Type Specification library). The value ''VAT'' assigned to the attribute schemeID, taken from the code list EOIDType, is used to indicate that the type of identifier used is the Value Added Tax identifier issued by the Spanish Tax Agency (ES-AEAT). |
1.7.2. Copy the code block
<cac:TenderingCriterionResponse>
<cbc:ID schemeID="ISO/IEC 9834-8:2008 - 4UUID" schemeAgencyID="OP" schemeVersionID="3.3.0">acb58f0e-0fe4-4372-aa08-60d0c36bfcfe</cbc:ID>
<cbc:ValidatedCriterionPropertyID schemeID="Criterion" schemeAgencyID="OP" schemeVersionID="3.3.0">
1fa05728-308f-43b0-b547-c903ffb0a8af
</cbc:ValidatedCriterionPropertyID>
<cbc:ResponseID schemeID="VAT" schemeAgencyID="ES-AEAT">
B82387770
</cbc:ResponseID>
</cac:TenderingCriterionResponse>xmlThis section collects all code lists used in ESPD-EDM with its classification, description and meta-data.
2. access-right
An example of how to use this code list can be found in access-right xml Example.
Name |
AccessRight |
||||||||||||||||||
Code list type |
Business-agnostic |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains controlled vocabulary listing the access rights or restrictions to resources. It is designed for but not limited to DCAT descriptions of datasets. |
||||||||||||||||||
Metadata |
|
3. boolean-gui-control-type
An example of how to use this code list can be found in boolean-gui-control-type xml Example.
Name |
BooleanGUIControlType |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
This code list is only used in criterion 'Other economic or financial requirements' (finan-requ). Contains values to be use by software implementations to display graphic control elements: radio buttons and check boxes. Code allows to represent values: true, false and not selected. |
||||||||||||
Metadata |
|
4. country
An example of how to use this code list can be found in country xml Example.
Name |
Country |
||||||||||||||||||
Code list type |
Business-agnostic |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains controlled vocabulary that lists concepts associated with names of countries and territories with a three-letter coding. |
||||||||||||||||||
Metadata |
|
5. criterion
An example of how to use this code list can be found in criterion xml Example.
Name |
Criterion |
||||||||||||||||||
Code list type |
Procurement specific |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains coded exclusion and selection criteria used for public procurement procedures. |
||||||||||||||||||
Metadata |
|
6. criterion-element-type
An example of how to use this code list can be found in criterion-element-type xml Example.
Name |
CriterionElementType |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
Contains coding for each type of structural element to render the ESPDRequest and ESPDResponse. |
||||||||||||
Metadata |
|
7. currency
An example of how to use this code list can be found in currency xml Example.
Name |
Currency |
||||||||||||||||||
Code list type |
Business-agnostic |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains controlled vocabulary that lists concepts associated with currencies and currency subunits. The concepts included are correlated with the ISO 4217 international standard. |
||||||||||||||||||
Metadata |
|
8. docrefcontent-type
An example of how to use this code list can be found in docrefcontent-type xml Example.
Name |
DocRefContentType |
||||||||||||||
Code list type |
Procurement Specific |
||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||
Description |
Contains coded possible document types referenced from the actual document. This code list is maintained as technical for the time being. In the future it may be removed or published on EU Vocabularies. |
||||||||||||||
Metadata |
|
9. economic-operator-size
An example of how to use this code list can be found in economic-operator-size xml Example.
Name |
EconomicOperatorSize |
||||||||||||||||||
Code list type |
Business-agnostic |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains different categories in which the operators are classified, according to their size (using as criteria the number of employees). |
||||||||||||||||||
Metadata |
|
10. eoid-type
An example of how to use this code list can be found in eoid-type xml Example.
Name |
eoid-type |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
Contains coded parts identification type used in cac:PartyIdentification. This code list is maintained as technical for the time being. In the future it may be removed or published on EU Vocabularies. |
||||||||||||
Metadata |
|
11. eo-role-type
An example of how to use this code list can be found in eo-role-type xml Example.
Name |
EoRoleType |
||||||||||||||||||
Code list type |
Procurement specific |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains codes identifying the role of the economic operator in each procurement procedure. |
||||||||||||||||||
Metadata |
|
12. financial-ratio-type
An example of how to use this code list can be found in financial-ratio-type xml Example.
Name |
financial-ratio-type |
||||||||||||||||
Code list type |
Technical |
||||||||||||||||
Maintainer |
ESPD Team |
||||||||||||||||
Description |
Contains codes of the possible financial ratios to declare in selection criteria finan-rat. This code list is maintained by the ESPD Team and codes are collected from Banque de France. |
||||||||||||||||
Metadata |
|
13. language
An example of how to use this code list can be found in language xml Example.
Name |
Language |
||||||||||||||||||
Code list type |
Business-agnostic |
||||||||||||||||||
Maintainer |
EU Vocabularies |
||||||||||||||||||
Description |
Contains controlled vocabulary that lists concepts associated with languages. The concepts included are correlated with the ISO 639 international standard. |
||||||||||||||||||
Metadata |
|
14. occupation
An example of how to use this code list can be found in occupation xml Example.
Name |
Occupation |
||||||||||||||||||
Code list type |
Procurement specific |
||||||||||||||||||
Maintainer |
ESPD Team |
||||||||||||||||||
Description |
Contains codes for professional enrolment areas in which the Economic Operator must be registered in. This code list is maintained by the ESPD Team but content is collected from the [esco] (from now on ESCO) classification. This code list remains as technical but in the future it could be published in EU Vocabularies or provided directly from ESCO. The data type expected for this code is URL following the ESCO taxonomy identification that uses a URI as the key value. |
||||||||||||||||||
Metadata |
|
15. profile-execution-id
Name |
ProfileExecutionID |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
Contains coded identification and version the ESPD-EDM used to create the to [xml] instance. The identification may include the exact version of the specification.
|
16. property-group-type
Name |
PropertyGroupType |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
Contains coded types to be used by software implementations to control which elements to be rendered in the displayed user interface.
|
17. response-data-type
Name |
ResponseDataType |
||||||||||||
Code list type |
Technical |
||||||||||||
Maintainer |
ESPD Team |
||||||||||||
Description |
Contains identifiers used to describe data type expected in criteria elements.
|
