3.3 Header of X-Road message

Pursuant to the rules of X-Road, obligatory specific X-Road headers must always be described and transmitted in messages. Headers must have a correct structure and correct namespace, which is http://x-road.eu/xsd/identifiers. Obligatory and additional header fields are described in the specification of X-Road message protocol (http://x-road.eu/docs/x-road_message_protocol_v4.0.pdf).

3.3.1 Obligatory header fields of X-Road are following:

  • <client> – obligatory complex-type field identifying the client having initiated the request, which is described with the following elements:

xRoadInstance – value of the field for Estonian X-Road members is EE in production instance, ee-test in test instance, and ee-dev in development instance;

memberClass – the field differentiates member classes (GOV – Estonian authorities, COM – Estonian companies, NGO – Estonian foundations and non-profit organisations, NEE – foreign authorities and companies);

memberCode – value of the field is the registry code of the authority;

subsystemCode – value of the field corresponds to the name of the subsystem.

  • <service> või <centralService> – complex-type fields, one of which is obligatory. The field specifies the dataservice to be used. Descriptive elements of the field are identical to the field <client> (xRoadInstance, memberClass, memberCode and subsystemCode), to which the following fields are added:

serviceCode – name of the wrapper corresponding to the SOAP message of dataservice;

serviceVersion – dataservice version.

  • <id> – obligatory field, the value of which is a unique identifier of the message. Message ID must be a unique for each member. The recommended format of <id> field is UUID. See also https://en.wikipedia.org/wiki/Universally_unique_identifier
  • <protocolVersion> – an obligatory field showing the version of X-Road message protocol. Value of the field must be 4.0
  • <requestHash> – the content of this header is automatically filled by the security server. The field has content only in the case of response messages and includes request hash.
  • <requestHash/@algorithmId> – content of this attribute shows which algorithm was used for calculating request hash.

3.3.2 Non-obligatory additional header fields of X-Road are following:

  • <userId> – a non-obligatory field, the value of which is the personal identification code of the user having initiated the request together with a two-letter prefix of the ISO country code (e.g. EE12345678901). If end user is authenticated, userID field must be included;
  • <issue> – a non-obligatory field, the value of which is the basis for request (internal code of the submitter of request to indicate a file or a reference in document management, etc.). Enables referring to requests e.g. if personal data are used and it is necessary to answer to the requests of a citizen or Data Protection Inspectorate.

Last modified: Wednesday, 30 August 2017, 4:08 PM