Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move DID Parameters section from did-core to did-resolution. #106

Merged
merged 1 commit into from
Jan 15, 2025
Merged

Move DID Parameters section from did-core to did-resolution. #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 10 additions & 0 deletions common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,16 @@ var ccg = {
status: "CG-DRAFT",
publisher: "Digital Verification Community Group"
},
"HASHLINK": {
title: "Cryptographic Hyperlinks",
date: "December 2018",
href: "https://tools.ietf.org/html/draft-sporny-hashlink-05",
authors: [
"Manu Sporny"
],
status: "Internet-Draft",
publisher: "IETF"
},
"DATA-INTEGRITY": {
title: "Verifiable Credential Data Integrity 1.0",
href: "https://www.w3.org/TR/vc-data-integrity/",
Expand Down
153 changes: 148 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,149 @@ <h1>Terminology</h1>

</section>

<section id="did-parameters">
<h2>DID Parameters</h2>

<p>
The <a>DID URL</a> syntax supports a simple format for parameters
(see section <a href="https://www.w3.org/TR/did-core/#query">Query</a>
in [[DID-CORE]]). Adding a DID
parameter to a <a>DID URL</a> means that the parameter becomes part of the
identifier for a <a>resource</a>.
</p>

<pre class="example nohighlight"
title="A DID URL with a 'versionTime' DID parameter">
did:example:123?versionTime=2021-05-10T17:00:00Z
</pre>

<pre class="example nohighlight"
title="A DID URL with a 'service' and a 'relativeRef' DID parameter">
did:example:123?service=files&amp;relativeRef=/resume.pdf
</pre>

<p>
Some DID parameters are completely independent of of any specific <a>DID
method</a> and function the same way for all <a>DIDs</a>. Other DID parameters
are not supported by all <a>DID methods</a>. Where optional parameters are
supported, they are expected to operate uniformly across the <a>DID methods</a>
that do support them. The following table provides common DID parameters that
function the same way across all <a>DID methods</a>. Support for all
<a href="#did-parameters">DID Parameters</a> is OPTIONAL.
</p>

<table class="simple">
<thead>
<tr>
<th>
Parameter&nbsp;Name
</th>
<th>
Description
</th>
</tr>
</thead>

<tbody>
<tr>
<td>
<code><a>service</a></code>
</td>
<td>
Identifies a service from the <a>DID document</a> by service ID.
If present, the associated value MUST be an <a
data-lt="ascii string">ASCII string</a>.
</td>
</tr>
<tr>
<td>
<code>relativeRef</code>
</td>
<td>
A relative <a>URI</a> reference according to <a
data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a> that identifies a
<a>resource</a> at a <a>service endpoint</a>, which is selected from a <a>DID
document</a> by using the <code>service</code> parameter.
If present, the associated value MUST be an <a
data-lt="ascii string">ASCII string</a> and MUST use percent-encoding for
certain characters as specified in <a data-cite="RFC3986#section-2.1">RFC3986
Section 2.1</a>.
</td>
</tr>
<tr>
<td>
<code>versionId</code>
</td>
<td>
Identifies a specific version of a <a>DID document</a> to be resolved (the
version ID could be sequential, or a <a>UUID</a>, or method-specific).
If present, the associated value MUST be an <a
data-lt="ascii string">ASCII string</a>.
</td>
</tr>
<tr>
<td>
<code>versionTime</code>
</td>
<td>
Identifies a certain version timestamp of a <a>DID document</a> to be resolved.
That is, the <a>DID document</a> that was valid for a <a>DID</a> at a certain
time. If present, the associated value
MUST be an <a data-lt="ascii string">ASCII string</a> which is a valid XML
datetime value, as defined in section 3.3.7 of <a
href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition Language
(XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime value MUST be
normalized to UTC 00:00:00 and without sub-second decimal precision.
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>.
Comment on lines +289 to +292
Copy link
Member

Choose a reason for hiding this comment

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

Not for this PR, but I wonder if we should just define hashlinks in this spec given that we have Multihash defined in CID now?

</td>
</tr>

</tbody>
</table>

<p>
Implementers as well as <a>DID method</a> specification authors might use
additional DID parameters that are not listed here. For maximum
interoperability, it is RECOMMENDED that DID parameters use the DID
Specification Registries mechanism [[?DID-SPEC-REGISTRIES]], to avoid collision
with other uses of the same DID parameter with different semantics.
</p>

<p>
DID parameters might be used if there is a clear use case where the parameter
needs to be part of a URL that references a <a>resource</a> with more
precision than using the <a>DID</a> alone. It is expected that DID parameters
are <em>not</em> used if the same functionality can be expressed by passing
input metadata to a <a>DID resolver</a>.
</p>

<p class="note" title="DID parameters and DID resolution">
The <a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can
be influenced by passing <a href="#did-resolution-options"></a> or
<a href="#did-url-dereferencing-options"></a> to a <a>DID resolver</a> that are
not part of the <a>DID URL</a>. This is comparable to
HTTP, where certain parameters could either be included in an HTTP URL, or
alternatively passed as HTTP headers during the dereferencing process. The
important distinction is that DID parameters that are part of the <a>DID
URL</a> should be used to specify <em>what <a>resource</a> is being
identified</em>, whereas input metadata that is not part of the <a>DID URL</a>
should be used to control <em>how that <a>resource</a> is resolved or
dereferenced</em>.
</p>

</section>

<section id="resolving">
<h1>DID Resolution</h1>

Expand Down Expand Up @@ -1775,23 +1918,23 @@ <h1>Errors</h1>
<h2>invalidDid</h2>
<p>If an invalid DID is detected during <a>DID Resolution</a>,
the value of the DID Resolution Metadata <strong>error</strong> property MUST be <strong>invalidDid</strong>
as defined in section <a href="https://www.w3.org/TR/did-core/#did-resolution-metadata">DID Resolution Metadata</a> in [[DID-CORE]].
as defined in section <a href="#did-resolution-metadata"></a>.
</p>
<h2>invalidDidUrl</h2>
<p>If an invalid DID URL is detected during <a>DID Resolution</a> or <a>DID URL dereferencing</a>,
the value of the DID Resolution or DID URL Dereferencing Metadata <strong>error</strong> property MUST be <strong>invalidDidUrl</strong>
as defined in section <a href="https://www.w3.org/TR/did-core/#did-url-dereferencing-metadata">DID URL Dereferencing Metadata</a> in [[DID-CORE]].
as defined in section <a href="#did-url-dereferencing-metadata"></a>.
</p>
<h2>notFound</h2>
<p> If during <a>DID Resolution</a> or <a>DID URL dereferencing</a> a DID or DID URL doesn't exist,
the value of the DID Resolution or DID URL dereferencing Metadata <strong>error</strong> property MUST be <strong>notFound</strong> as
defined in sections <a href="https://www.w3.org/TR/did-core/#did-resolution-metadata">DID Resolution Metadata</a> and
<a href="https://www.w3.org/TR/did-core/#did-url-dereferencing-metadata">DID URL Dereferencing Metadata</a> in [[DID-CORE]].
defined in sections <a href="#did-resolution-metadata"></a> and
<a href="#did-url-dereferencing-metadata"></a>.
</p>
<h2>representationNotSupported</h2>
<p> If a DID document representation is not supported during <a>DID Resolution</a> or <a>DID URL dereferencing</a>,
the value of the DID Resolution Metadata <strong>error</strong> property MUST be <strong>representationNotSupported</strong> as
defined in section <a href="https://www.w3.org/TR/did-core/#did-resolution-metadata">DID Resolution Metadata</a> in [[DID-CORE]].
defined in section <a href="#did-resolution-metadata"></a>.
</p>
<h2>methodNotSupported</h2>
<p> If a DID method is not supported during <a>DID Resolution</a> or <a>DID URL dereferencing</a>,
Expand Down
14 changes: 14 additions & 0 deletions terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,4 +262,18 @@
There are guarantees about the integrity and correctness of the result to the extent possible under the applicable <a>DID method</a>.
See Section <a href="#method-architectures"></a>.</dd>

<dt><dfn data-lt="UUID|UUIDs">Universally Unique Identifier</dfn> (UUID)</dt>
<dd>
A type of globally unique identifier defined by [[RFC4122]]. UUIDs are similar
to DIDs in that they do not require a centralized registration authority. UUIDs
differ from DIDs in that they are not resolvable or
cryptographically-verifiable.
</dd>

<dt><dfn data-lt="URI|URIs">Uniform Resource Identifier</dfn> (URI)</dt>
<dd>
The standard identifier format for all resources on the World Wide Web as
defined by [[RFC3986]]. A <a>DID</a> is a type of URI scheme.
</dd>

</dl>
Loading