4.1 Namespace of X-Road

This chapter provides a brief description of the XML namespace and XML schema, followed by descriptions of namespaces of X-Road itself and the header fields of X-Road Version 6. At the end, a list is provided of header fields which were valid in former versions, as many services are still described according to an older version.

4.1.1 Concept of XML namespace

Namespace is set or group of elements, defined based on some specific naming agreement.

XML namespace is a set of XML element types and attribute names; namespace has a unique name, which is a URI reference. Thus, each element type and attribute name in XML namespace is uniquely identified by two components: name of the XML namespace and their local name.

XML namespace provides a two-part system for naming element types and attributes. The first part is a URI reference identifying the namespace or namespace name, the second part is the name of element or attribute (local name).

Namespace can be declared in XML in two ways:

Common abbreviations should be always preferred when defining the alias of a namespace. E.g.:

4.1.2 XML schema

XSD Schema standard is generally used for defining XML namespace (URI) and its elements and attributes. Namespace XSD definition is the collection of metadata describing element types (string, dateTime), structure and sequence (if the element is located inside or after another element), and rules (if element is obligatory), as well as notes describing the essential character of the element (annotation, documentation).

XSD Example (http://x-road.eu/xsd/identifiers):

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema elementFormDefault="qualified"

        targetNamespace="http://x-road.eu/xsd/identifiers"

        xmlns="http://x-road.eu/xsd/identifiers"

        xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:complexType name="XRoadIdentifierType">

        <xs:annotation>

            <xs:documentation>Globally unique identifier in the X-Road system.

                Identifier consists of object type specifier and list of

                hierarchical codes (starting with code that identifiers

                the X-Road instance).</xs:documentation>

        </xs:annotation>

        <xs:sequence>

            <xs:element minOccurs="0" ref="xRoadInstance"/>

            <xs:element minOccurs="0" ref="memberClass"/>

            <xs:element minOccurs="0" ref="memberCode"/>

            <xs:element minOccurs="0" ref="subsystemCode"/>

            <xs:element minOccurs="0" ref="groupCode"/>

            <xs:element minOccurs="0" ref="serviceCode"/>

            <xs:element minOccurs="0" ref="serviceVersion"/>

            <xs:element minOccurs="0" ref="securityCategoryCode"/>

            <xs:element minOccurs="0" ref="serverCode"/>

        </xs:sequence>

        <xs:attribute ref="objectType" use="required"/>

    </xs:complexType>


<xs:schema> element descriptions:

  • elementFormDefault=“qualified“

Qualified – specifies that elements defined in this namespace must be used with a namespace prefix in XML (<ns-prefix:element-name>). This ensures upon reading XML a clear understanding of the namespace where the element was defined. Generally, it is recommended to use the value ‘qualified’.

  • attributeFormDefault=“unqualified“

Unqualified – specifies that attributes defined in this namespace need not have a namespace prefix in XML (<ns-prefix:element-nameattribute1=“123“>). In the example above, this is lacking, which means that the default value ‘unqualified’ is used.

  • targetNamespace="http://x-road.eu/xsd/identifiers"

Specifies namespace (URI) defined by the XSD.

  • xmlns="http://x-road.eu/xsd/identifiers"

Specifies the default namespace. I.e., an ability is provided in XSD to refer to other elements defined in this namespace without a prefix (Unqualified). E.g., the definition of “objectType” refers to the defined “XRoadObjectType” type without a prefix (reference with a prefix would be, e.g., type=”id:XRoadObjectType”)
<xs:attribute name=”objectType” type=”XRoadObjectType”/>

4.1.3 General description of X-Road namespaces

Namespaces offered by X-Road are described with the following URI addresses:

Notices about namespaces of X-Road Version 6:

  • In the namespace of X-Road Version 6 (http://x-road.eu/xsd/xroad.xsd), standard header fields are described (SOAP Header elements);
  • namespace of X-Road Version 6 does not define any message body (SOAP Body) elements;
  • furthermore, elements used for documenting WSDL operations (version, title, notes, techNotes) are described in the namespace of X-Road Version 6 (http://x-road.eu/xsd/xroad.xsd);
  • the namespace for defining services is not standardised on the level of X-Road protocol. Thus, services may be described also in namespaces specified by protocol version 3.1;
  • description of X-Road message protocol 4.0 specifies only definitions and rules of X-Road fields used in header;
  • upon the creation of X-Road services (WSDL description), Document/Literal-Wrapped SOAP encoding style must be used, and the description of the header must be based on the namespace of X-Road elements http://x-road.ee/xsd/xroad.xsd. The body of request as well as the response must be wrapped into one root element.

4.1.4 Header fields of namespace of X-Road Version 6

X-Road Version 6 does not differentiate X-Road members in terms of use and the provision of dataservices, thus the dataservices and clients of X-Road (providers as well as users of dataservice) are described as complex types.

X-Road header elements are necessary for unambiguous identification of users (client) and of service providers (service).

Security server uses header fields:

  • for routing or transmission of requests and responses in the infrastructure of X-Road to the correct ‘physical’ recipient;
  • for validating the rights – if the user is entitled to use the service;
  • for ensuring authenticity – automatically generated requestHash is used to the enable user of the service to check if the security server of the provider of the service received their message unchanged, and it furthermore enables coupling ASiC-E containers of request and response;
  • for logging.

Furthermore, header elements are necessary for the providers and users of dataservice, e.g. for:

  • performing additional client-specific validation of rights;
  • apply client-specific business logic calculations or filters. E.g., one client is transmitted a larger set of data than the other;
  • logging.

Header fields described in X-Road namespace are described in clause 3.3, but they are explained in more detail in clause 4.1.4.1 for the purposes of illustration.


4.1.4.1 Explanations of elements of header fields

  • xRoadInstance – identifier of the instance of X-Road infrastructure. Country code. Depends on the X-Road instance the service is located in. When a service is moved from one instance to another, the identifier of the service must be changed. For Estonian X-Road members its value is:
  • EE (in production instance);
  • ee-test (in test instance);
  • ee-dev (in development instance).
  • memberClass – classifies X-Road members. Differentiates authorities of public and private sectors.
  • GOV (Legal person registered in the register of authorities of the State of Estonia and local governments);
  • COM (Legal person registered in the Estonian Commercial Register);
  • NGO (Legal person registered in the Estonian Non-Profit Associations and Foundations Register), and
  • NEE (Legal person registered in a register other than a register specified in member classes gov, com or ngo), i.e. authorities/companies of other countries.
  • memberCode – registry code of the authority;
  • subsystemCode – unique name of the subsystem of an X-Road member. As the concept of database was removed in X-Road Version 6, it is replaced by the concept of subsystem. Possibilities for its use and definition are broader for members. Subsystems are independent of databases. They can overlap with a database, exist independently of a database, or form part of a database. Each member may decompose their subsystems based on their own needs and independently of databases. Mediation of service requests between X-Road members (user and/or provider of dataservice) takes place through subsystems;
  • serviceCode – code/name of dataservice
  • serviceVersion – version of dataservice

Example of the use of elements of header fields:

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"

xmlns:id="http://x-road.eu/xsd/identifiers">

<SOAP-ENV:Header>

<xrd:client id:objectType="SUBSYSTEM">

<id:xRoadInstance>EE</id:xRoadInstance>

<id:memberClass>GOV</id:memberClass>

<id:memberCode>12345678</id:memberCode>

<id:subsystemCode>alamsysteemi nimetus</id:subsystemCode>

</xrd:client>

<xrd:service id:objectType="SERVICE">

<id:xRoadInstance>EE</id:xRoadInstance>

<id:memberClass>COM</id:memberClass>

<id:memberCode>87654321</id:memberCode>

<id:subsystemCode>alamsüsteem</id:subsystemCode>

<id:serviceCode> teenuse nimetus</id:serviceCode>

<id:serviceVersion>v1</id:serviceVersion>

</xrd:service>

<xrd:userId>EE12345678</xrd:userId>

<xrd:id>11111aaaa2222</xrd:id>

<xrd:protocolVersion>4.0</xrd:protocolVersion>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

                               ….

</SOAP-ENV:Body>

</SOAP-ENV:Envelope> 


4.1.5 Changes in transfer to Version 6

In former versions (Version 5 and earlier), X-Road members were not hierarchically described, and the following header elements were described in X-Road namespace: consumer, producer, userId, id, service, issue, unit, position, userName, async, authentication, paid, encrypt, encryptCert, encrypted, encryptedCert.

In addition, the following header fields are no more described in X-Road message protocol 4.0 implemented with Version 6: position; userName; authenticator.

The functionality of X-Road Version 6 does not enable the use of the following header fields of X-Road message protocol version 3.1:

  • async, because asynchronous requests are no more supported;
  • paid, because paid requests are no more supported;
  • encrypt, encryptCert, encrypted, encryptedCert, because the encryption system operates automatically.

As X-Road Version 6 does not differentiate X-Road members in terms of use and the provision of dataservices, yet in X-Road Version 6 the membership is hierarchical, the header field ‘consumer’ used in protocol version 3.1 moved into the complex type of header field ‘client’ in protocol version 4.0 and is described with elements: xRoadInstance, memberClass, memberCode, subsystemCode.

Header element ‘producer’ moved into the complex types ‘service’ and ‘centralService’, and is described with elements xRoadInstance, memberClass, memberCode and subsystemCode. ‘service’ used in protocol version 3.1 moved into the complex types ‘service’ and ‘centralService’ in protocol version 4.0 and is described with elements xRoadInstance, serviceCode, serviceVersion (see above).



Last modified: Tuesday, 16 May 2017, 12:43 PM