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 ESBI URI syntax

Production environment

ebsi:trusted-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 Trusted Nodes List, which lists all api_endpoint's per 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 resolved. There will be a versioned TNL issued for each environment. The TNL contains credentialSubject with properties environment and nodes, where the environment must match the network.
3. Select an API Endpoint: The nodes objects in the TNL can be used to select any api_endpoint. It is advisable to pick multiple api_endpoints with a priority to cover any network issues. The chosen endpoint will contain scheme and authority parts of the URL.
4. Client driven service version: The service does not contain a service version number and clients must inject that if the specific service requires it.
5. Transform the URL: The api_endpoint is concatenated with and in order of: service, client driven version suffix, and with 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

Pilot environment transformation

EBSI URI based:
ebsi:pilot:trusted-issuers-registry:issuers/did:ebsi:zZeKyEJfUTGwajhNyNX928z

TNL resolved node for Pilot environment:
https://api-pilot.ebsi.stsisp.ro/

After URL transformation:
https://api-pilot.ebsi.stsisp.ro/trusted-issuers-registry/v5/issuers/did:ebsi:zZeKyEJfUTGwajhNyNX928z