Address confusing note about the difference between "resolving" a DID and "dereferencing" a DID URL

[wip-abramson]

There's a note that 'The difference between "resolving" a DID and "dereferencing" a DID URL is being thoroughly discussed', but the link doesn't point to a comment that discusses it. This should be resolved before publication.

From https://github.com/w3ctag/design-reviews/issues/1157#issuecomment-3439062470

Perhaps we can just remove this note?

[wip-abramson]

https://w3c.github.io/did-resolution/#introduction

[swcurran]

I'd really like to push on this. I think having the two terms and correspondingly the two algorithms in the spec is very confusing and unnecessary. Most notably, the "DID Resolution" being separate from "DID URL Dereferencing" acknowledges, but tries to gloss over that versionId and versionTime are query parameters but don't seem to make a what is being resolved a "URL". It is a URL. I think it would be better to have a single term (either works, although DID Resolution is the commonly used term), and that it cover all scenarios of having or not a path, query parameters and a fragment. Likewise, that single algorithm should cover the four possible results of returning a DIDDOc, a list of URLs/service endpoints, a resource associated with a DID, or an error.

[w3cbot]

This was discussed during the #did meeting on 06 November 2025.

View the transcript

w3c/did-resolution#227

ottomorac: I believe you opened this one, Will.

<Wip> https://w3c.github.io/did-resolution/#introduction

wip: The note is in this introduction section, and Geoffrey is saying that it is confusing.

<Wip> The note references this issue - w3c/did#166 (comment)

wip: My sense is that we should just remove it. It's old and stale and I don't know that it's adding anything.

ottomorac: Anybody have any strong opinions on removing it?

JoeAndrieu: I support removing it. It has been thoroughly discussed, and I don't think it's relevant anymore.

wip: These issues are all tagged "feedback". At the moment I'm trying to go through all tagged issues, label them "ready for PR", and find people to address them.

---

[ottomorac]

Hi @swcurran ,

Thanks for the input. During the group discussion there was agreement that we should remove the "green note box" after the introduction paragraph here: https://w3c.github.io/did-resolution/#introduction

It seems you are driving at a deeper point between distinguishing "DID Resolution" and "DID URL deferencing" however.

Do you agree that we should at least delete the "green note box" however?

[swcurran]

Yes -- agreed it should be removed.

[peacekeeper]

I think it would be better to have a single term

I strongly disagree with removing or blurring the differentiation between resolving a DID and dereferencing a DID URL. This would be a major breaking change. See e.g. also RFC3986 for some background, as well as many previous discussions in the DID WG on this topic.

I do however agree with removing the green note box :)

[swcurran]

Removing the differentiation between "resolving" and "dereferencing" would not be a "breaking change". The process is the same whether it is described as one flow or two. I think it is far easier to understand if one flow (and term) is used since in both cases, the item being processed is a DID URL. While I do agree that my PR that covers path handling is a change to the spec, that is independent of the "one term vs. two" question that I think only serves to make the spec more confusing.