Discovery

Discovery allows parties to publish information about themselves as a Verifiable Presentation, so that other parties can discover them for further (data) exchange.

A Discovery Service is hosted on a server (also a Nuts node), by an organization that is agreed upon by the parties to be the server for that particular use case. The parties implementing that use case then configure their Nuts nodes with the service definition that defines the server.

The service definition is a JSON document agreed upon (and loaded) by all parties that specifies:

  • which Verifiable Credentials are required for the service,

  • where the Discovery Service is hosted, and

  • how often the Verifiable Presentations must be updated.

Service definitions are loaded from the discovery.definitions.directory directory by both client and server. It does not load subdirectories. If the directory contains JSON files that are not (valid) service definitions, the node will fail to start.

Clients

Clients will periodically query the Discovery Service for new registrations. Applications can then search for entries in the Discovery Service (in this case coffeecorner), e.g.:

GET /internal/discovery/v1/discovery/coffeecorner/?credentialSubject.name=John%20Doe

Any string property in the Verifiable Credential(s) can be queried, including nested properties. Arrays, numbers or booleans are not supported. Wildcards can be used to search for partial matches, e.g. Hospital* or *First. If multiple query parameters are specified, all of them must match a single Verifiable Credential.

Registration

To register a DID on a Discovery Service, the DID must be activated for the service. The Nuts node will then register a Verifiable Presentation of the DID on the service, and periodically refresh it. E.g., for service coffeecorner and DID did:web:example.com:

POST /internal/discovery/v1/coffeecorner/did:web:example.com

The DID’s wallet must contain the Verifiable Credential(s) that are required by the service definition, otherwise registration will fail. If the wallet does not contain the credentials, the Nuts node will retry registration periodically.

Servers

To act as server for a specific discovery service, its service ID needs to be specified in discovery.server.ids, e.g.:

discovery:
  server:
    ids:
      - "coffeecorner"

The IDs in this list must correspond to the id fields of the loaded service definition, otherwise the node will fail to start.

Clients will access the discovery service through /discovery on the external HTTP interface, so make sure it’s available externally.

The endpoint for a Discovery Service MUST be in the following form (unless mapped otherwise in a reverse proxy):

https://<host>/discovery/<service_id>

Where <service_id> is the ID of the service, e.g.: /discovery/coffeecorner.