Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 26 additions & 37 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -195,26 +195,26 @@ <h1>Introduction</h1>
<section id="implementer-overview" class="informative">
<h2>Implementer Overview</h2>
<p>
By invoking a <a>DID resolver</a> using the standard <code>resolve(did, resolutionOptions)</code> interface (as defined in
the <a href="#resolving">DID Resolution section</a>) one can obtain a <a>DID document</a> and accompanying metadata
(e.g., `contentType`, proof, versioning) which an application can use to validate a user's cryptographic keys,
service endpoints, or status.
By invoking a <a>DID resolver</a> using the standard <code>resolve(did, resolutionOptions)</code> interface (as defined in
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By invoking a <a>DID resolver</a> using the standard <code>resolve(did, resolutionOptions)</code> interface (as defined in
By invoking a <a>DID resolver</a> using the standard `resolve(did, resolutionOptions)` interface (as defined in

the <a href="#resolving">DID Resolution section</a>) one can obtain a <a>DID document</a> and accompanying metadata
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the <a href="#resolving">DID Resolution section</a>) one can obtain a <a>DID document</a> and accompanying metadata
the <a href="#resolving">DID Resolution section</a>), one can obtain a <a>DID document</a> and accompanying metadata

(e.g., `contentType`, proof, versioning) which an application can use to validate a user's cryptographic keys,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
(e.g., `contentType`, proof, versioning) which an application can use to validate a user's cryptographic keys,
(e.g., `contentType`, proof, versioning), which an application can use to validate a user's cryptographic keys,

service endpoints, or status.
<p>
For example, a wallet app could resolve <code>did:example:123?versionTime=2021-05-10T17:00:00Z</code>
using the `versionTime` parameter to retrieve the state of that DID at a past time, or a client could
dereference a DID URL
like <code>did:example:123?service=files&relativeRef=/resume.pdf</code>
(see <a href="#example-dereferencing-to-service-endpoint-url">here for detailed example</a>)
to fetch a user's resume stored via a service declared in the DID document.
For example, a wallet app could resolve <code>did:example:123?versionTime=2021-05-10T17:00:00Z</code>
using the `versionTime` parameter to retrieve the state of that DID at a past time, or a client could
dereference a DID URL
like <code>did:example:123?service=files&relativeRef=/resume.pdf</code>
(see <a href="#example-dereferencing-to-service-endpoint-url">here for detailed example</a>)
to fetch a user's resume stored via a service declared in the DID document.
Comment on lines +203 to +208
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example, a wallet app could resolve <code>did:example:123?versionTime=2021-05-10T17:00:00Z</code>
using the `versionTime` parameter to retrieve the state of that DID at a past time, or a client could
dereference a DID URL
like <code>did:example:123?service=files&relativeRef=/resume.pdf</code>
(see <a href="#example-dereferencing-to-service-endpoint-url">here for detailed example</a>)
to fetch a user's resume stored via a service declared in the DID document.
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`
(see <a href="#example-dereferencing-to-service-endpoint-url">here for detailed example</a>)
to fetch a user's resume stored via a service declared in the DID document.

</p>
<p>
Further, the specification's <a href="#dereferencing-algorithm">DID URL dereferencing algorithm</a> shows how
a client can follow a fragment (e.g., <code>#key-1</code>) to extract a particular verification method from
the <a>DID document</a> (see <a href="#example-dereferencing-to-verification-method">here for detailed example</a>).
In practice, implementers validate their resolver against the
<a href="https://github.com/w3c-ccg/did-resolution-test-suite">DID Resolution Test Suite</a> which exercises
normative MUSTs and error conditions (such as invalid DIDs, deactivated DIDs, unsupported methods,
relative URL expansion, etc.) to ensure that client applications can reliably depend on correct resolution behavior
Further, the specification's <a href="#dereferencing-algorithm">DID URL dereferencing algorithm</a> shows how
a client can follow a fragment (e.g., <code>#key-1</code>) to extract a particular verification method from
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
a client can follow a fragment (e.g., <code>#key-1</code>) to extract a particular verification method from
a client can follow a fragment (e.g., `#key-1`) to extract a particular verification method from

the <a>DID document</a> (see <a href="#example-dereferencing-to-verification-method">here for detailed example</a>).
In practice, implementers validate their resolver against the
<a href="https://github.com/w3c-ccg/did-resolution-test-suite">DID Resolution Test Suite</a> which exercises
normative MUSTs and error conditions (such as invalid DIDs, deactivated DIDs, unsupported methods,
relative URL expansion, etc.) to ensure that client applications can reliably depend on correct resolution behavior
across different DID methods.
</p>
</section>
Expand Down Expand Up @@ -265,32 +265,32 @@ <h2>
<li>
A decentralized address book: By using DIDs as identifiers for people and organizations
within an address book, the controllers of those DIDs can independently update the contents of
their DID documents. Through DID resolution these DIDs can be resolved to obtain the
their DID documents. Through DID resolution these DIDs can be resolved to obtain the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
their DID documents. Through DID resolution these DIDs can be resolved to obtain the
their DID documents. Through DID resolution, these DIDs can be resolved to obtain the

current state of the DID document for any given contact, enabling persistent stable identifiers
with updatable services and verification material necessary for continued verifiable interactions.
with updatable services and verification material necessary for continued verifiable interactions.
</li>
<li>
Verifying a Verifiable Credential: Verifiable Credentials are signed by an issuer and given to a
Verifying a Verifiable Credential: Verifiable Credentials are signed by an issuer and given to a
holder. The holder can then create a Verifiable Presentation that is presented to a verifier.
Within the credential, if issuers and holders are identified using a DID, the verifier can
Within the credential, if issuers and holders are identified using a DID, the verifier can
use DID resolution to resolve the DID documents of the identified issuer and holder to obtain
the verification material necessary to verify the signatures on the Verifiable Presentation.
Comment on lines +275 to 277
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Within the credential, if issuers and holders are identified using a DID, the verifier can
use DID resolution to resolve the DID documents of the identified issuer and holder to obtain
the verification material necessary to verify the signatures on the Verifiable Presentation.
By using DIDs to identify issuers and holders within a credential, an issuer enables a verifier to
use DID resolution to resolve the DID documents of the identified issuers and holders to obtain
the verification material necessary to verify the signatures on the Verifiable Presentation.

</li>
<li>
Auditability: DID resolution can be used to obtain the historical state of a DID document either
at a specific point in time or for a specific version. This can be used to audit the historical
verifiable actions of a DID controller. For example, the issuance of a verifiable receipt or the
at a specific point in time or for a specific version. This can be used to audit the historical
verifiable actions of a DID controller. For example, the issuance of a verifiable receipt or the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
verifiable actions of a DID controller. For example, the issuance of a verifiable receipt or the
verifiable actions of a DID controller; for example, the issuance of a verifiable receipt or the

signing of a contract.
</li>
<li>
DID URL based resource retrieval: A DID controller can add service endpoints to their DID document
that point to resources they control, for example a profile picture. By referencing these resources
Copy link
Member

@TallTed TallTed Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
that point to resources they control, for example a profile picture. By referencing these resources
that point to resources they control; for example, a profile picture. If DID URLs are used to reference

using a DID URL, a web application can use DID resolution and DID URL dereferencing to retrieve the
using a DID URL, a web application can use DID resolution and DID URL dereferencing to retrieve the
current version of the resource. The DID URL can act as a persistent, dereferencable identifier
for this resource, while the DID controller can independently change the resource over time.
Comment on lines +288 to 290
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
using a DID URL, a web application can use DID resolution and DID URL dereferencing to retrieve the
current version of the resource. The DID URL can act as a persistent, dereferencable identifier
for this resource, while the DID controller can independently change the resource over time.
these resources, web applications can use DID resolution and DID URL dereferencing to retrieve the
current version of the resource(s). The DID URL can be used as a persistent, dereferenceable identifier
for these resources, while the DID controller can independently change the resource over time.

</li>
</ul>

</section>

</section>
Expand Down Expand Up @@ -409,17 +409,6 @@ <h2>DID Parameters</h2>
For example: <code>2020-12-20T19:17:47Z</code>.
</td>
</tr>
<tr>
<td>
<code>hl</code>
</td>
<td>
A resource hash of the <a>DID document</a> to add integrity protection, as
specified in [[?HASHLINK]]. This parameter is non-normative.
If present, the associated value MUST be an
<a data-lt="ascii string">ASCII string</a>.
</td>
</tr>

</tbody>
</table>
Expand Down Expand Up @@ -1588,7 +1577,7 @@ <h2>Metadata Structure</h2>
<a data-cite="INFRA#boolean">boolean</a>, or
<a data-cite="INFRA#nulls">null</a>. The values within any complex data
structure such as a map or list MUST be one of these data types as well.
All metadata property definitions registered in the DID Resolution Extensions
All metadata property definitions registered in the DID Resolution Extensions
[[?DID-EXTENSIONS-RESOLUTION]] MUST define the value type, including any
additional formats or restrictions to that value (for example, a string
formatted as a date). It is RECOMMENDED that property
Expand Down