w3c
Fix bug in implementer overview description
This says "resolve did:example:123?versionTime=2021-05-10T17:00:00Z", but that's a DID URL, not a DID (because DIDs don't contain ? characters), so it's not in the domain of the resolution function.
From https://github.com/w3ctag/design-reviews/issues/1157#issuecomment-3439062470
Suggest we could say resolve did:example:123 with the versionTime resolutionOption, or something like that
Section in question: https://w3c.github.io/did-resolution/#implementer-overview
Same comment I added on #227 (here) about the artificial and confusing attempt to different a "DID" and "DID URL".
Also to note in that section is the error in the relativeRef example -- did:example:123?service=files&relativeRef=/resume.pdf. The query parameter relativeRef in that example is illegal -- it can't have /s in it. It has to be percent-encoded (which also makes it harder to read) so that it is did:example:123?service=files&relativeRef=%2Fresume.pdf.
This was discussed during the #did meeting on 06 November 2025.
View the transcript
w3c/did-resolution#228
<Wip> https://
wip: Our example says resolve, but the thing we're resolving is a DID URL, so either it should be "dereferencing" or we should change the example. Do people agree? As soon as you add a query parameter it becomes a URL, so the correct term should be "dereferencing".
JoeAndrieu: Where is the URL?
wip: In section 1.1, second paragraph down, ignoring "This section is non-normative".
JoeAndrieu: I think it's more nuanced that we've discussed so far. The DID URL is modifying your resolution because it has a query parameter "versionTime". It would be incorrect to resolve this without using the version time.
… This section is non-normative, so that helps with our options. Resolving the DID may require understanding if there is a DID parameter.
… I think this paragraph is not about resolution. The "For example" is about dereferencing.
Ivan: I'm also pretty much mixed up. We had two normative sections on DID resolution and DID URL dereferencing. We use different terms if we do something with a DID vs. a DID URL. This example here is a DID URL, not a DID.
JoeAndrieu: The challenge is that the version time as a query parameter is going to change how you resolve that DID, so you can't fully separate it.
Ivan: We need to understand this is a URL, but it modifies the resolution, so it's part of the resolution.
… We shouldn't have this example in this section. If we are going to talk about URLs, we should put it in a paragraph at the end of the section.
<Wip> Obtain the DID document for the input DID by executing the DID resolution algorithm as defined in 4. DID Resolution. All dereferencing options and all DID parameters of the input DID URL MUST be passed as resolution options to the DID Resolution algorithm.
<Wip> https://
wip: I think, Joe, this is a section in the DID URL dereferencing algorithm, which takes the parameter and passes it to the resolve operation.
… You're going to parse the URL and pass them into the resolution algorithm.
… I agree with Ivan. We change the example to use something simpler.
<Zakim> JoeAndrieu, you wanted to say I think we need to redefine resolution to take a DID URL
JoeAndrieu: Simple, but I'm not sure it's right. I think the mistake is that we say that DID resolution starts with a DID, rather than a DID URL, which may affect which document is returned.
<KevinDean> +1 to JoeAndrieu
JoeAndrieu: We may need to pass query parameters through to the resolution process. We have a handful of parameters. Some may affect resolution, some may affect dereferencing.
Ivan: Is this defined somewhere? This is not defined in the DID resolution document.
… I understand the intention, but I'm wondering if the specifications are clear in this respect.
JoeAndrieu: They're not clear, because we say that DID resolution starts with a DID, not a DID URL. Anyone at any time can add another parameter that changes resolution even more.
wip: I always thought we resolve DIDs and dereference DID URLs.
… I thought we handled that by stating that we pass the parameters through to the resolution as resolution options along with the DID.
JoeAndrieu: The problem is that the language is what we've been using, but we cannot resolve the DID without the full DID URL. The DID resolution process can't happen without the parameters in the DID URL.
… I agree in some moment before we do resolution that we have to parse the DID URL.
… I don't think we've properly discussed this preprocessing step that has to take place before resolution.
Ivan: What bothers me is that this is so different from the way that HTTP URLs are handled that we're bound to create confusion for the community.
… I see this as, "If I take an HTTP URL, whatever is in a query parameter, will influence how I handle the host name."
JoeAndrieu: I think you're right, but I don't know how we get out of it.
… We wanted parameters that affect resolution and parameters that affect dereferencing.
wip: I think this is great, but I suggest we move on, and discuss at TPAC.
<ivan> for the record, from the did spec: "Identifies a certain version timestamp of a DID document to be resolved. That is, the DID document that was valid for a DID at a certain time."
This was discussed during the #did meeting on 04 December 2025.
View the transcript
w3c/did-resolution#228
<ottomorac1> Fix bug in implementer overview description #228
ottomorac1: we discuss that on a previous call, but manu was not here
… did it get discussed at TPAC?
JoeAndrieu: this is about the fact that we define DID resolution as only using the DID
… but that's not exactly how it works.
<swcurran> +1 to Joe's description
JoeAndrieu: we start with a DID URL with parameters; we extract the DID and the parameters, and use the parameters to configure the resolution
<manu> +1 to Joe
ottomorac1: I think this is an issue for Markus
manu: we talked about this at TPAC and came to a resolution. This is marked "ready for PR". What JoeAndrieu said should be addressed.
I agree with @wip-abramson 's suggestion above. This should say something like "resolve did:example:123" with "versionTime" passed to the resolver in the resolutionOptions.
Unassigning myself from this for now, maybe someone could try to create a PR, should be quite straightforward...
