Tag Review: Add examples of how to use DID resolution to solve the end-users' problems

[wip-abramson]

See #177

[w3cbot]

This was discussed during the #did meeting on 11 September 2025.

View the transcript

Tag Review: Add examples of how to use DID resolution to solve the end-users' problems #187

w3c/did-resolution#187

manu: This one is thinking how the browser looks before and after, but for us we can just point to examples in the spec and also to the test suite....

manu: if not we can just provide an example of a resolution request and a resolution response (sample with HTTP GET, HTTP response via command line)

manu: In this context our end user is not browser users but software developers instead

---

[ottomorac]

I will wait until Manu's PR is merged before I open my PR, but my suggested text is the following:

How DID resolution is used to address the needs from Software Developers:

By invoking a DID resolver using the standard resolve(did, resolutionOptions) interface (as defined in Section 4 of the DID Resolution spec) one can obtain a DID Document and accompanying metadata (e.g. contentType, proof, versioning) which an application can use to validate a user’s cryptographic keys, service endpoints, or status.

For example, a wallet app could resolve did:example:123?versionTime=2021-05-10T17:00:00Z (using the versionTime parameter) to retrieve the state of that DID at a past time, or a client could dereference a DID URL like did:example:123?service=files&relativeRef=/resume.pdf (illustrated in Section 5.5.2) to fetch a user’s resume stored via a service declared in the DID Document.

Further, the spec’s DID URL dereferencing algorithm (Section 5.4) shows how a client can follow a fragment (e.g. #key-1) to extract a particular verification method from the DID Document (see example in Section 5.5.1). In practice, implementers validate their resolver against the DID Resolution Test Suite (e.g. the w3c-ccg did-resolution-mocha test suite) which exercises normative MUST and error conditions (such as invalid DIDs, deactivated DIDs, unsupported methods, relative URL expansion, etc.) to ensure client applications can reliably depend on correct resolution behavior across different DID methods.

[peacekeeper]

#207 has been merged.