EBSI URI scheme library

This library supports the EBSI URI Scheme. It allows you to parse EBSI URIs, serialize EBSI URI components, transform EBSI URIs into URLs, and URLs into EBSI URIs.

Table of Contents

1. Installation
2. Usage
3. License

Installation

npm install @europeum-ebsi/ebsi-uri

Usage

Configuration

All the methods described below require a configuration object. The library exports a TypeScript interface that you can use to properly define the configuration object. Here's an example of such a configuration object:

import type { EbsiUriConfiguration } from "@europeum-ebsi/ebsi-uri";

const config = {
  // Defines the URI scheme
  scheme: "ebsi",

  // Defines the network config
  network: {
    // Network component, as it appears in the URI
    name: "pilot",

    // Whether the network component is optional or not
    isOptional: false,
  },

  // The list of the supported services (with their version number)
  services: {
    "did-registry": "v5",
    "trusted-issuers-registry": "v5",
    "trusted-policies-registry": "v3",
    "trusted-schemas-registry": "v3",
  },
} as const satisfies EbsiUriConfiguration;

Parse EBSI URI

The parse function takes an EBSI URI (string) and returns the URI components scheme, network, service, and resource. It requires an EbsiUriConfiguration object as second parameter.

Example:

parse(
  "ebsi:test:did-registry:/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  config,
);

returns

{
  "network": "pilot",
  "resource": "/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  "scheme": "ebsi",
  "service": "did-registry"
}

Parse URL

The parseUrl function takes a URL (string) and returns the URI components scheme, network, service, and resource. It requires an EbsiUriConfiguration object as second parameter.

Example:

parseUrl(
  "https://api-pilot.ebsi.eu/did-registry/v5/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  config,
);

returns

{
  "network": "pilot",
  "resource": "/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  "scheme": "ebsi",
  "service": "did-registry"
}

Serialize

The serialize function takes an object containing the URI components scheme, network, service, and resource. It requires an EbsiUriConfiguration object as second parameter. It returns a string representation of the EBSI URI.

Example:

serialize(
  {
    network: "pilot",
    resource: "/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
    scheme: "ebsi",
    service: "did-registry",
  },
  config,
);

returns ebsi:test:did-registry:/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw

Transform EBSI URIs into URLs

The toUrl function takes an EBSI URI (string) and returns a URL string. You also have to pass the host to use as second parameter, and pass an EbsiUriConfiguration object as last parameter.

Example:

toUrl(
  "ebsi:test:did-registry:/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  "api-pilot.ebsi.eu",
  config,
);

returns https://api-pilot.ebsi.eu/did-registry/v5/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw

Transform URLs into EBSI URIs

The fromUrl function takes a URL (string) and returns an EBSI URI string. It requires an EbsiUriConfiguration object as second parameter. It returns a string representation of the EBSI URI.

Example:

fromUrl(
  "https://api-pilot.ebsi.eu/did-registry/v5/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw",
  config,
);

returns ebsi:test:did-registry:/identifiers/did:ebsi:zx23VhpbGYeqF2MRJk3HzPw

License

Copyright (C) 2026 European Union

This program is free software: you can redistribute it and/or modify it under the terms of the EUROPEAN UNION PUBLIC LICENCE v. 1.2 as published by the European Union.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the EUROPEAN UNION PUBLIC LICENCE v. 1.2 for further details.

You should have received a copy of the EUROPEAN UNION PUBLIC LICENCE v. 1.2. along with this program. If not, see https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12.