UBL Based and distribution package

Semantic assets have been defined by ISA as "a collection of highly reusable metadata (e.g. xml schemata, generic data models) and reference data (e.g. code lists, taxonomies, dictionaries, vocabularies) which are used for e-Government system development".

ESPD Distribution package

All the semantic assets needed to implement ESPD electronic documents are organised in a distribution package. The content of this folder is organised as follows:

Distribution package

Figure 5. Distribution package

  1. ESPDTeam: contains files for ESPD Team internal use in maintenance tasks of the ESPD-EDM;

  2. codelists: contains the different code lists used in ESPD in Genericode format and the criterion structure definition.

  3. conceptual-model: contains the UML conceptual model of the ESPD in .eap, .xmi and HTML format.

  4. java-library: contains the XML schemas used to generate the JAXB annotated Java classes. This artefac is not mantained for this release

  5. ubl-2.3: contains a redistribution package from UBL 2.3.

  6. validation: contains business rules validation files for Schematron and Testbed.

  7. xml-examples: contains default ESPDRequest and ESPDResponse xml samples and the criterion xml schema.

Adoption of UBL-2.3

UBL, developed by the Organization for the Advancement of Structured Information Standards, is a royalty-free library of standard electronic Extensible Markup Language (XML) business documents. It is designed to plug directly into existing business, legal, auditing, and records management practices, and to operate within a standard business framework such as ISO 15000 (ebXML) to provide a complete, standards-based infrastructure that can extend the benefits of existing Electronic Data Interchange (EDI) systems to businesses of all sizes.

UBL is also included in the ICT Standards for Procurement (ICT Standards for Procurement): the rules on European standardisation allow the European Commission to identify information and communication technology (ICT) technical specifications - that are not national, European or international standards - to be eligible for referencing in public procurement.

UBL is a specific used in some Member States and by the EU institutions, namely the European Commision. UBL is also referred to in the Commission implementing decision of 31 October 2014 on the identification of Universal Business Language version 2.1 for referencing in public procurement (COM Decision 2014/771/EU).

Technical resources and tools are freely available for its use and repurpose by the Member States, Service Providers, EC and any other stakeholders. Especially interesting and largely used are the open source tools and artefacts referred by the OASIS UBL-TC, such as Genericode , ISO Schematron and Crane Softwright.

The adoption of the new UBL version (UBL 2.3) is related to the alignment between ESPD and eForms, which will ensure and improve the interoperability between models.

UBL-2.3 Documents and libraries

UBL-2.3 defines thousands of different information components and dozens of documents. This guide describes and illustrates only those elements from UBL-2.3 that are actually used by the eESPD. Thus the ESPD-EDM reuses only a small set of those components and only 2 documents: QualificationApplicationRequest (for the ESPD Request) and QualificationApplicationResponse (for the ESPD Response).

UBL-2.3 distributes two sets of XSD schemas: see folders xsd and xsdrt of the UBL distribution package. The xsd folder contains the schemata fully documented (with dictionary entry names, definitions, examples, etc.); whilst the xsdrt schemata are not likewise documented and are frequently used in production environments (rt stands for "run-time").

The previous ESPD-EDM versions used its own libraries where Criterion and Evidence-related aggregate and components were defined (components prefixed with cac-ccv:, cac-cev, cbc-ccv and cbc-cev).

This new version uses components exclusively defined by UBL-2.3 in two main libraries: Common Aggregate Components (file UBL-CommonAggregateComponents-2.3.xsd.xsd) and Common Basic Components (UBL-CommonBasicComponents-2.3.xsd.xsd).

The usual prefix used to identify Common Aggregate Components is cac:. The prefix for Common Basic Components is cbc:.

All the materials developed by UBL-2.3 Technical Committee can be accessed here: here.

UBL-2.3 and TOOP Requirements

During the development of ESPD-EDM some requirements arose from TOOP related to the Evidence class. The aforementioned requirements that can be found in the following GitHub issue, are fully mappable to the UBL 2.3 Schema.

To check the mapping, please access to these TOOPRequirements_UBL_2.3.xlsx or TOOPRequirements_UBL_2.3.ods.

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:

  1. Identifiers point at specific occurrences of objects (instances); codes replace concepts;

  2. 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.

  3. Identifiers are in principle maintained in the business domain, e.g. buyer identifiers, economic operator identifiers, exclusion or selection criteria identifiers, etc.

  4. Codes may belong to three different domains:

    1. they can be somehow 'business-agnostic' and be used cross-domain (e.g. country codes, currency codes, language codes, etc.);

    2. business-specific domain (i.e. procurement specific, like codes representing contract types, procurement procedure types, criteria types, etc.); and

    3. 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.

Codes and code lists

The ESPD Exchange Data Model tries to reuse as much as possible the codes that are already used for e-Procurement. In any project, like the ESPD-EDM, there are at least three types (or layers) of codes:

  1. 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.;

  2. 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);

  3. 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.

Moreover, the ESPD will reuse code list from EU Vocabularies. This is due to the alignment between both models, ESPD and eForms to ensure the maximum interoperability. With this purpose ESPD will align the use of certain code lists.

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).

However, it is worth to note that those code list that are reused from EU Vocabularies in alignment with eForms are not completely shown in excel and ods files. Instead, the metadata and the location of them in EU Vocabularies is provided.

For the genericodes is different, in this version ESPD will provide the gc files from EU Vocabularies to ensure its use and the validation. In future versions of the ESPD, only will be provided these GC of the code list purely used and maintained by ESPD.

ESPD-EDM Code list contain 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 illustrate how these elements are organised in the code lists maintained in spread-sheets:

Elements and metadata of an ESPD code list

Figure 6. Elements and metadata of an ESPD code list

The Annex I of this document lists all the code lists used by the ESPD and in which context or element it is used.

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.

Code attributes

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.

Identifier attributes

Figure 8. Identifier attributes

Table 4. UBL attributes for identifiers

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.

And its corresponding definitions, as provided by OASIS UBL (ISO/IEC 19845):

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.

<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>

  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" Agnecy ID. Notice that the other additional attributes may be also used, as in this example.

  6. 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.

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):

Values of the schemeID for Party Identifiers

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

...

<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>

...

  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).

TenderingCriterionResponse (the answer to the previous QUESTION)

...
<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>
...

  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).