Dereferencing a DID URL

A DID URL extends a DID with optional components — like paths, query parameters, and fragments — to reference specific resources within or related to a DID document. In other words, a DID can serve as a root authority of a set of DID URLs tied to resources associated with the DID.

This enables many different purposes. Some are standardized — like identifying a specific public key inside the DID document, or identifying a previous version of the DID document — while some depend on the DID method or application. When dereferencing, the input is a DID URL plus dereferencing options, and the output is the DID document, or part of a DID document, or other resource.

For example, a service can be selected from a DID Document using a service DID parameter:

did:example:1234?service=myServiceId

which would make the dereferencing software select the service from the DID document whose serviceId matches the service parameter in the DID URL, and return the service endpoint associated with it.

This process comprises two stages:

1. resolving the DID: getting the DID document;
2. dereferencing: accessing or retrieving the resource identified by the DID URL (a part of the DID document, or a completely separate resource);

TIP

See DID URL in action:
The Power of DIDs #5: A Deep Dive into Service Endpoints and Digital Product Passports.

With a fragment

A request for a URL-encoded DID URL with a fragment will return only the part of the DID document that is identified by the fragment, e.g. a verification method:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE#verkey

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did%3Aindy%3Aidunion%3Atest%3ABDrEcHc8Tb4Lb2VyQZWEDE%23verkey"

NOTE

DID URLs with fragments are supported for all DID methods.

With service and relativeRef parameters

A request for a DID URL with these parameters will select one or more service(s) from the DID document and then construct a service endpoint URL using a relative URI reference:

did:web:danubetech.com?service=github&relativeRef=did-method-dns

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: text/uri-list" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:web:danubetech.com?service=github&relativeRef=did-method-dns"

Note that the service and relativeRef parameters are supported for all DID methods, and the format and meaning of their values are independent of the DID method.

TIP

See the DID Core specification for additional information about these parameters.

With transformKeys parameter

A request for a DID URL with this parameter that will transform the verification methods in the DID document to the requested format:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?transformKeys=JsonWebKey2020

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?transformKeys=JsonWebKey2020"

Similar to the previous example, but adding a fragment #verkey to the DID URL:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?transformKeys=JsonWebKey2020#verkey

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did%3Aindy%3Aidunion%3Atest%3ABDrEcHc8Tb4Lb2VyQZWEDE%3FtransformKeys%3DJsonWebKey2020%23verkey"

Another example of a DID URL with this parameter that will transform the verification methods in the DID document to the requested format:

did:ebsi:zwkqocXfSsfokNFcrSng8cM?transformKeys=jwks

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/jwk-set+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:ebsi:zeq8HUiJfnbvEKyum5XYscv?transformKeys=jwks"

Note that the transformKeys parameter is supported for all DID methods, and the format and meaning of its values are independent of the DID method.

TIP

See the transformKeys specification for additional information about this parameter.

With versionId parameter

A request for a DID URL with this parameter will retrieve the specific version 83 of the DID document:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionId=83

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionId=83"

A request for a DID URL with this parameter will retrieve the specific version 56 of the DID document:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionId=56

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionId=56"

NOTE

The versionId parameter is not supported for all DID methods, and the format and meaning of its values are specific to the DID method.

TIP

See the DID Core specification for additional information about this parameter.

With versionTime parameter

A request for a DID URL with this parameter will retrieve the version at the time 2020-09-29T13:37:56.000Z of the DID document:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionTime=2020-09-29T13:37:56.000Z

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionTime=2020-09-29T13:37:56.000Z"

A request for a DID URL with this parameter will retrieve the version at the time 2020-10-01T08:25:23.000Z of the DID document:

did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionTime=2020-10-01T08:25:23.000Z

curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \
     -H "Accept: application/did+ld+json" \
     -X GET "https://api.godiddy.com/1.0.0/universal-resolver/identifiers/did:indy:idunion:test:BDrEcHc8Tb4Lb2VyQZWEDE?versionTime=2020-10-01T08:25:23.000Z"

NOTE

The versionTime parameter is not supported for all DID methods, but if it is supported, then the format and meaning of its values are independent of the DID method.

TIP

See the DID Core specification for additional information about this parameter.