Using DID document services

A party often exchanges data through its API endpoints. If a client only has the party's DID, services in the DID document can be used to register API endpoints. A service in a DID document describes its type and content (serviceEndpoint). A typical example is the FHIR base URL of the FHIR API which is to be accessed by other parties.

Service Type

Use cases should specify the service types when using DID document services for endpoint discovery. It's recommended to include the use case name in the service type, to avoid clashes when multiple use cases use same service type. This might lead to duplication of endpoints, but enables parties to differentiate API endpoints in case multiple use cases specify the same API family.

E.g., given the use cases "Pizza Delivery Service" and "Pasta Delivery Service" both having an "order" API, a bad approach would be:

{
  "services": [
    {
      "id": "#order",
      "type": "order-api",
      "serviceEndpoint": "https://example.com/api/pizza/order"
    }
  ]
}

An improved use case specification differentiates the service type to avoid clashes:

{
  "services": [
    {
      "id": "#order-pizza",
      "type": "order-pizza-api",
      "serviceEndpoint": "https://example.com/api/pizza/order"
    },
    {
      "id": "#order-pasta",
      "type": "order-pasta-api",
      "serviceEndpoint": "https://example.com/api/pasta/order"
    }
  ]
}

Service Endpoint

The serviceEndpoint property can contain a JSON string, object, array, or nesting of these types. If a use case requires multiple API endpoints, it could use a JSON object to specify multiple API endpoints:

{
  "services": [
    {
      "id": "#order-pizza",
      "type": "pizza-restaurant",
      "serviceEndpoint": {
        "api": "https://example.com/api/pizza/order",
        "menu": "https://example.com/pizza-list.pdf"
      }
    }
  ]
}

Note that services in DID documents are not restricted to describing API endpoints only; another example use for services in DID documents could be informing about who is administering the DID document.