Skip to content

Andrieu/did parameter guidance #325

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

Open
jandrieu wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Andrieu/did parameter guidance #325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
72799e9
added DID URL authors so the spec doesnt blame DID method creators fo…
jandrieu Apr 12, 2026
4fad72e
Removed guidance about when DID parameters should be used, clarifying…
jandrieu Apr 12, 2026
7f54ec5
Update terms.html
jandrieu Apr 15, 2026
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
20 changes: 4 additions & 16 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,34 +421,22 @@ <h2>DID Parameters</h2>
</table>

<p>
Implementers as well as <a>DID method</a> specification authors might use
[=DID URL authors=] might use
additional DID parameters that are not listed here. For maximum
interoperability, it is RECOMMENDED that DID parameters use the DID
Document Properties Extensions mechanism [[?DID-EXTENSIONS-PROPERTIES]], 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
<a href="#did-url-dereferencing-options"></a> to a <a>DID resolver</a>, or a <a>DID URL dereferencer</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>.
alternatively passed as HTTP headers during the dereferencing process.
</p>
<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>

@wip-abramson wip-abramson Apr 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I know I keep picking on this - sorry! Appreciate the work gone into these PRs.

I still am not sure you mean [=Resolve=] or [=Dereference=] here.

Instead of referencing terms for Resolve and Dereference, do you mean to link to the relevant sections of the spec?

@jandrieu jandrieu Apr 15, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Yes. They should link to what's in the spec.

@wip-abramson wip-abramson Apr 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>
<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>
Suggested change
<p>If [=Resolve=] or [=Dereference=] is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>
<p>If <a href="#resolving">Resolve</a> or <a href="#derferencing">Dereference</a> is called with a resolution option of the same name as a DID parameter in the input DID URL, the resolution option MUST override the DID parameters, when interpreted by the Resolver or Dereferencer, respectively.</p>

Then this is the way to achieve that.

@wip-abramson wip-abramson Apr 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Separately, reading this again what you are saying is that if a DID URL like:

did:example:12345?versionId=55

Is dereferenced along with resolutionOptions that define versionId as 1, then the DID returned MUST be the version 1 DID.

I guess that makes sense, as it is the caller who defines the resolutionOptions. So they know that are explicitly stating they want back v1 regardless of the parameters in the DID URL.


<section id="datetime">
<h3>Datetime</h3>
Expand Down
4 changes: 4 additions & 0 deletions terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
<dt><dfn>client</dfn></dt>
<dd>Software and/or hardware that invokes a <a>DID resolver</a> in order to execute the <a>DID resolution</a> and/or <a>DID URL dereferencing</a> algorithms. This invocation is done via a <a>binding</a>. The term <a>client</a> does not imply any specific network topology.</dd>

<dt><dfn data-lt="">DID URL Author</dfn></dt>
<dd>The creator of a DID URL. Like any URL, DID URLs are strings, typically produced in one context and often consumed in another (although constructing a DID URL for a particular use case might immediately use that DID URL in the context it was created). DID URL authors are responsible for properly constructing the DID URL and using any path, query, and fragment parts correctly such that is complies with the <a>DID URL Syntax</a> defined in [[DID-CORE]].</dd>


<dt><dfn data-lt="">DID resolution result</dfn></dt>
<dd>A data structure that represents the result of the <a>DID resolution</a> algorithm.
May contain a <a>DID document</a>. See Section <a href="#did-resolution-result"></a>.</dd>
Expand Down