EBSI URI Scheme

The EBSI decentralised network can be accessed via trusted EBSI nodes, each of which exposes its own publicly accessible endpoints. It's recommended that a Verifiable Credential isn't tied to a single node, or to a version of a service, as this would link the validity of the Verifiable Credential with the validity of the node or the version of a service it is exposing.

Uniform Resource Identifiers (URIs) RFC 3986 can be utilised to locate resources without tying them to a URI authority. This document outlines a URI scheme for identifying the content of Trust Registries, enabling all participants (Issuers, Holders, and Verifiers) to use their preferred EBSI node, whilst maintaining consistent identifiers.

EBSI URI Scheme

The EBSI URI scheme complies with RFC 3986, and employs the ABNF syntax and definitions from RFC 5234, and RFC 3986. All Verifiable Credentials that reference EBSI node resources should use the EBSI URI scheme instead of HTTP(S).

The EBSI URI Syntax ABNF Rules

ebsi-uri = "ebsi:" network service resource
network  = 0*1( 1*unreserved ":" )
service  = 1*( 1*unreserved ":" )
resource = path-abempty \[ "?" query \] \[ "#" fragment \]

Examples of EBSI URI syntax

Production environment

ebsi:issuers-registry:/issuers/did:ebsi:zZeKyEJfUTGwajhNyNX928z/attributes/14bd0d26f3b05d825b91cede8b31068f4d3a3dfda7673e7d36ecfe9f9d402509

Pilot environment

ebsi:pilot:did-registry:/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw

EBSI resource transformation rules

Only EBSI REST API resources may be transformed into EBSI URI.

The EBSI URI must not contain service versions in the service component as it would lock the Verifiable Credential into that specific service version. The URI identified resource can be reached from multiple service versions, while the interpretation of the resource is same the content of the resource might differ. Resolvers of the EBSI URI must choose a version that they support.

Transforming EBSI URL into URI

The process of transforming an EBSI URL into a URI involves the following steps:

1. Identify the Environment: Identify on which environment the authority belongs to and set it into network. This can be done with the help of the Trusted Nodes List, which lists the node URLs of each environment. For production environment the network shall be omitted.
2. Strip service version number: The service shall be the full segment before the second /, which might continue with a version number like /v4. If a version number exists, it must be fully omitted.
3. Construct a URI: Concatenate the static ebsi: scheme with network, service and rest of the URL without the leading and optional version number.

Transforming EBSI URI into URL

To help identifying the network, service and resource, it is advisable to treat the value as a string and split it with /. This results into two or more parts, where the first part contains colon concatenated ebsi:network:service. The count of colons allows to identify if the network is for production (just one colon exists), or if some other environment (two colons exists).

The process of transforming an EBSI URI into a URL involves the following steps:

1. Identify the Environment: The network component of EBSI URI is used to determine the environment. If the network is empty, it corresponds to the production network.
2. Resolve the TNL: Once the correct environment is identified, the Trusted Nodes List shall be fetched and verified. Its environments object lists the node URLs of each environment, where the key must match the network (prod when the network is empty).
3. Select a node: Any node URL listed for the environment can be used. It is advisable to keep several nodes, in order of priority, to cover any network issues. A node URL contains the scheme and authority parts of the URL.
4. Client driven API version: The EBSI URI does not contain the API version, and clients must add it (/v1 for the Core API).
5. Transform the URL: The node URL is concatenated with, in order: the client driven API version, the service, and everything contained in the resource component.

This process ensures that the EBSI URI is correctly transformed into a valid EBSI node URL. It's important to note that the Trusted Nodes List is a crucial component in this transformation process as it provides the necessary mapping between the network the EBSI domain used in the URL.

Examples

Pre-production environment transformation

EBSI URI based:
ebsi:preprod:issuers-registry:issuers/did:ebsi:zZeKyEJfUTGwajhNyNX928z

Node selected from the TNL for the preprod environment:
https://api-preprod.ebsi.example.org

After URL transformation:
https://api-preprod.ebsi.example.org/v1/issuers-registry/issuers/did:ebsi:zZeKyEJfUTGwajhNyNX928z