DID URL Derefencing and Fragments: The role of a DID Resolver

[swcurran]

AFAIUI DID URL fragments are to be handled after DID resolution, by the client -- just as they are with HTTP URLs. Thus, the act of "DID Resolution" stops at returning the resource and the handling of the fragment is up to the client.

If so, Example 5.5.1 is incorrect. The resolution of DID Resolution is the full DID Doc + metadata. It is not just the node of the DID Doc indicated by the fragment, as explained in the current spec text.

This impacts a number of places in the spec, generally simplifying the text.

Most importantly, we should be very clear on what the concrete output of DID Resolution is expected to be -- the resource and metadata. This simplifies creating DID Resolvers and clients that call DID Resolvers.

[peacekeeper]

@swcurran I completely agree that the result of DID Resolution is the full DID document + metadata, and that DID URL fragments are handled after that.

But I don't think there is anything in Example 5.5.1 or elsewhere in the spec which is incompatible with this statement, so could you clarify why you think the example is incorrect?

DID Resolution is not the same as DID URL Dereferencing. The latter includes handling the fragment, and can return a part of the DID document as in Example 5.5.1. Note that a part of the DID URL Dereferencing algorithm can (and usually should) be executed by the client, see also section 7.2.3 Client-Side Dereferencing.

[wip-abramson]

I think @swcurran is referring to https://w3c.github.io/did-resolution/#example-12 and suggesting that this example should in fact be a DID Resolution Result.

I can see his reasoning. The example seems to go: Input DID URL -> Result of DID Resolution -> Result of DID URL Dereferencing.

[w3cbot]

This was discussed during the #did meeting on 18 December 2025.

View the transcript

w3c/did-resolution#259

swcurran: The example implies that when a fragment is used, the DID Resolver returns the fragment of the DID Document. My understanding of a fragment is document is returned and the client then does something w/ the fragment.

swcurran: In other words, bring out the node of the document that's referenced.

swcurran: Returning the node itself seems wrong to me.

manu: Agree with Stephen, but... This part of the spec concerns me. Should a DID resolver be required to provide this? Universal resolver is server side and does server side option.

<Zakim> JoeAndrieu, you wanted to mention this is dereferencing

manu: general concern about where dereferencing ends. In general, we shouldn't be doing stuff with fragments.

JoeAndrieu: General agreement. Challenge is how we talk about it. The way 3986 talks about it, the process to get to the fragment and the client has a role in it.
… defining the end point of dereferencing sounds like a piece of work that we don't want to do. Client should do the work beyond the DID resolution.

swcurran: You're saying that we should put an end to where DID Resolution ends, but also talk about dereferencing that a client could do.

<Zakim> manu, you wanted to say "a client might... and if so, it MUST"

JoeAndrieu: Yes, I think we have too much in the spec wrt. dereferencing right now.
… Put a limit on what the DID Resolver does, but add what a client would do in dereferencing.

<JoeAndrieu> +1 agreed. this also addresses the query properties that feed into resolution options

manu: +1. Is there any easy path to split out the dereferencing to what the client is to do. Its a layering concern. We shoved derefencing into the resolver and we should do to a point and the client should do other.

swcurran: +1 to what Manu said, the same thing I've been working on Path URL thing is the same thing. I had thought that DID Resolver would return resource pointed to -- it shouldn't, it should be left to another layer. This change is worthy, it's been the source of the need for special topic calls, etc.

swcurran: I am deep into DIDs, and I was confused by this features. All mentions of fragments should be: You get back a resource and you deal w/ a fragment. This is a layering thing -- you should get the DID Document back, URL back, but dereferencing is up to client. We should say: Here's what DID Resolver returns, and here's what a client can do once it gets that result. I'd be happy if we never did dereferencing and left that to the client.

Wip: Anyone want to take it?

<Zakim> manu, you wanted to get buy-in from Markus.

JoeAndrieu: What's the complication about Markus to get buy in. Where do we hit the substantive contribution challenge?

manu: I think we should collaborate as a community and get Markus's input since he is deeply knowledgeable.
… we need to get the concept aligned with Markus, and then get a PR. Maybe this is just a layer nuance that splits derefencing between resolver and client.
… Markus should be added as an invited effort.

<Zakim> JoeAndrieu, you wanted to IP considerations are the only Markus thing we might worry about

pchampin: +1 about needing consensus across the community, looking to resolve the issues wrt Markus and working to resolve it.

JoeAndrieu: +1 to get him back and an exception as needed. The IP issues are already covered and would only come into play if there is new IP added.

Wip: Try in the new year to get Markus onboard.

manu: I'll take it on if I can get Markus onboard.

---

[w3cbot]

This was discussed during the #did meeting on 08 January 2026.

View the transcript

DID URL Derefencing and Fragments: The role of a DID Resolver (5 min)

<ottomorac> w3c/did-resolution#259

<ottomorac> Previous discussion about where DID Resolution ends, but also talk about dereferencing that a client could do.

ottomorac: there was a previous discussion where Steven was mentioning where DID Resolution ends
… and what dereferencing would mean for a client
… we also had a pending item around whether Marcus could give us some insights
… but he'd need to be added as an invited expert...and we'll need PA for that

swcurran: I think it comes down to a couple things
… a) fragments is post-dereferencing
… there's a good bit in the spec about that, but it should likely be kept out of it
… other than to say, the client will use it to find the relevant DID doc
… b) I'd been making the assumption that once a path was found that it would be resolved
… which it actually may not...
… once I got into it, I found you could return an array of service endpionts
… that the endpoints would be treated as an API definition
… and you could use what you needed from that array
… but with the path, we're talking about referencing something more specific
… and singular, and I assumed it would return the resource not only it's path
… but I think we only need to return the path
… Marcus' remaining objective seems to be around when the query parameters are applied
… on the initial request? or on the subsequent resource path

manu: I agree that's where we are
… I think we mainly need to see some PRs

swcurran: I'd assume that a DID resolver would "know" which query params would apply to the resolution process

<ottomorac> last comment from Markus is this: w3c/did-resolution#260 (comment)

<ottomorac> (in case people are wandering)

swcurran: and that could leave other query params to be applied to the resulting path
… but Marcus stated that (very reasonably) would be very confusing
… because you could get anything passed in as a query param and how do you know when and where to apply it?
… his suggestion was to encode ones intended for the DID into another parameter
… to make it clear which ones apply at which step
… and make it explicit which ones apply post-resolution

manu: no objection if we go that route
… an alternative might be that the resolver just uses what it knows and leaves the rest
… but I agree there's no way to know which will be used where
… the upside is that we can avoid the weird encoding thing
… the hard thing is that it's hard to know where and when the query params would be applied
… whereas with the encoded approach the resolvers could be more explicit about what they accept

<Zakim> JoeAndrieu, you wanted to say I think the resolver does know, if it handles the method. So the resolver gets everything. As @manu said.

manu: vs. never knowing what will be used when/where

JoeAndrieu: so...I see it differently
… my understanding is that the parameters stay with it throughout
… and that they continue to cascade down to other requests
… it's true the caller may not know

bigbluehat: CMS and Login flows often do this type of parameter double encoding

bigbluehat: a "destination" or "intention" parameter is added in these types of flows

bigbluehat: it doesn't look pretty but its clear about how it works

bigbluehat: we need to be clear about parameter naming to avoid issues

manu: I'm coming around to Marcus's approach which I thing bigbluehat just said he supports
… the double encoded parameter
… JoeAndrieu you touched on my concern at the end of what you said
… I'm concerned about a resolver silently passing things down that it doesn't know
… and would prefer the resolver complaining up front if/when it doesn't know what the parameter means

<Zakim> JoeAndrieu, you wanted to oppose encoding everything

manu: coupled with the encoded parameter passing, I think we have a nice clean approach

JoeAndrieu: so...this is a radically breaking change
… and I think it's a bad idea
… right now we have resolution params
… and I'm not seeing a security concern strong enough to break how we do things now

swcurran: so, one thing might be to only do that encoding approach when a path is provided
… another would be that the resolver would return the path + whatever params remain
… so the resolver handles what it knows and puts the rest on the path
… I don't think we'd want it to be rejected on params it didn't know

manu: we don't yet have a rec, so I think breaking changes are OK at this point
… it is a security concern to not throw an error if it's just going to silently ignore params
… do we have other implementations besides the universal resolver?
… we have other implementations, but not ones that use this feature

bigbluehat: if these are query parameters that go along with the path, would we just not encode them with the path?

<Zakim> JoeAndrieu, you wanted to say if there are features that MUST be supported, then they must be supported. Everything else is a extensibility point. and there are implementations

JoeAndrieu: yeah, I think this would have ramifications on DID Core and stuff in the wild
… unless that feature is required
… if it's not, then it's a point of extensibility
… or if it's part of some extension about dereferencing
… like version ID could be required...I don't think it is right now
… and I think there are issues if your resolver is being forced to make decisions about things it doesn't yet know about

Wip: I do see the issues around version ID when the used in situations where the resolver doesn't know
… the conversation is great, but I am concerned about the time
… maybe a special call on this one?
… because we're on a bit of a time crunch for the group in general
… ottomorac not sure what you want to do, but I'd suggest we move on and arrange a special topic call for this one

ottomorac: swcurran and manu can have the last word, and then can arrange a special call

swcurran: the reason they're split is that there are two different resolution steps
… so, maybe we encode the resource ones and not the resolution ones
… and that should avoid concerns that JoeAndrieu raised

manu: all of this is optional per the spec--I just checked
… I'll leave it that I think it's a security issue and am really concerned about this
… I won't stand in the way, but I think it's risky when versions are or are not checked for

swcurran: what I was trying to do, was to define requirements be defined

manu: they're not right now

swcurran: yeah, the proposal is that we define them to fix that
… and then we allow a space for arbitrary parameters
… I don't think we can say we don't have them
… HTTP allows this, you can pass in whatever but the server decides

manu: I'll note I'll work through this more, but I'll likely oppose it
… swcurran is suggesting we add requirements
… JoeAndrieu's opposing it
… so there seems to be miscommunication

ottomorac: swcurran can you bring a suggestion?

<smccown> IMO, all versions should be checked. If versions operate slightly differently, then Manu is correct that unforeseen security problems could arise.

swcurran: happy to, but I think manu is talking about something else

manu: agreed

swcurran: yeah...I think there are a few different conversations here
… I'll write up what I'm proposing on that PR

---