How X-Road Member Identifiers Are Structured?
- Petteri Kivimäki
In X-Road, member organisations have globally unique identifiers that consist of a sequence of hierarchical codes. The structure of the identifiers is predefined and cannot be changed. However, the values of different identifier parts can be freely defined for every X-Road environment. It’s strongly recommended that the environments that belong to the same X-Road ecosystem follow the same conventions.
A member identifier consists of three parts:
instance identifier
member class
member code.
It is important to plan the acceptable values and conventions upfront so that they are consistent across different environments of the ecosystem. In addition, changing the values is not possible once they have been initially set.
How to use the identifiers in REST and SOAP requests?
REST
SOAP
https://docs.x-road.global/Protocols/pr-mess_x-road_message_protocol.html#21-identifiers
Instance identifier
Every X-Road environment has a code that identifies the X-Road instance – the instance identifier. The instance identifier defines a namespace for the environment. Federation between two X-Road environments - connecting two X-Road environments to one another - is not possible when two environments have the same instance identifier. Therefore, the instance identifier should be globally unique.
It is recommended to use the two-letter country code (defined in ISO 3166-1) of the country running the environment as an instance identifier. Since an X-Road ecosystem usually has more than one X-Road environment, an additional suffix defining the role of the environment may be appended to the country code. The instance identifier of all the environments of the same ecosystem should start with the country code that may be followed by an additional suffix. For example, the table below shows the instance identifiers of the Estonian X-Road ecosystem.
Instance identifier | Country code | Additional suffix | Description |
EE | EE | - | Estonian production environment |
EE-TEST | EE | TEST | Estonian test environment |
EE-DEV | EE | DEV | Estonian development environment |
In a corporate deployment, the company running the ecosystem can be included in the instance identifier to avoid a collision with a national ecosystem, for example, EE-MYCOMPANY, EE-MYCOMPANY-TEST, EE-MYCOMPANY-DEV.
Member class
Member classes are used to divide member organisations into different groups or categories, for example, governmental organisations, municipalities, private companies, non-profit organisations, etc. For example:
Member class | Description |
GOV | Governmental organisations |
MUN | Municipalities |
COM | Private companies |
NGO | Non-profit organisations |
The number of the required member classes depends on the member code. However, it is a common practice to have multiple member classes even if they are not technically required.
Member code
Member code is a unique code identifying a member organization within its member class, for example, a business / company id. Therefore, the number of the required member classes depends on the information that is used as a member code. In case the member code is unique within the ecosystem, one member class is enough to satisfy the technical requirements. However, if there are overlapping member codes, member classes must be designed so that member codes are always unique within a member class.Â