Re: [w3ctag/design-reviews] WG New Spec: DID Resolution (Issue #1157)

jyasskin left a comment (w3ctag/design-reviews#1157)

Hi! Thanks for sending this review our way. I did a pass over the first half of the spec (stopping before [Section 5, DID URL Dereferencing](https://www.w3.org/TR/did-resolution/#dereferencing)), and I think it'll be useful to let y'all look over my comments and start answering my questions in parallel with me finishing the second half and the TAG as a whole figuring out a consensus position. To be clear, _the following is just me and not a TAG-wide position, it may contain obvious mistakes_. Apologies for any such mistakes.

* Nit in the [Abstract](https://www.w3.org/TR/did-resolution/#abstract): there's a fairly grand description of what DIDs are meant to do, but mechanically, I think they're just a kind of URL that's guaranteed to resolve/dereference to a DID Document ... and this specification defines how that dereferencing works. Would it make sense to keep the abstract a little more grounded?
* There are references to both DID v1.0 and v1.1. The document should probably pick just one.

[Introduction](https://www.w3.org/TR/did-resolution/#introduction):
* The use of "resolution" here seems inconsistent with other uses. In particular, I don't think it's "the process of determining an access mechanism and the appropriate parameters necessary to dereference a URI" from https://www.rfc-editor.org/rfc/rfc3986.html#section-1.2.2, and it's not "the process of resolving a URI reference within a context that allows relative references so that the result is a string matching the `<URI>` syntax rule" from https://www.rfc-editor.org/rfc/rfc3986.html#section-5 (which is also used in https://www.w3.org/TR/did-1.1/#relative-did-urls). Is it the right term? Perhaps you're just defining how to "dereference" both DIDs and DID URLs?
* 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.

[Implementer Overview](https://www.w3.org/TR/did-resolution/#implementer-overview):
* This says "resolve did:example:123?versionTime=2021-05-10T17:00:00Z", but that's a DID URL, not a [DID](https://www.w3.org/TR/did-1.1/#did-syntax) (because DIDs don't contain `?` characters), so it's not in the domain of the resolution function.

[Terminology](https://www.w3.org/TR/did-resolution/#terminology):
* It would be ideal if this didn't duplicate definitions from other specs like https://www.w3.org/TR/did-1.1/#terminology. But I think there are technical reasons you have trouble deduplicating, perhaps that webref can't distinguish DID-ish terms from web platform terms well enough.

[DID Parameters](https://www.w3.org/TR/did-resolution/#did-parameters):
* Should this live in DID-core? It seems to set new requirements on all DID Methods, that they don't define conflicting meanings for these parameters, which aren't currently reserved in the definition of Methods.
* "MUST use percent-encoding for certain characters" is vague: which characters?
* "MUST be normalized to UTC 00:00:00" isn't an operation I recognize. Does this mean that it must have a timezone offset of 00:00?
* [HASHLINK] is an Internet-Draft, so might violate https://www.w3.org/guide/process/tilt/normative-references.html. There has been work on content digests since 2021, in particular in https://datatracker.ietf.org/doc/html/rfc9530 and https://www.ietf.org/archive/id/draft-ietf-httpbis-unencoded-digest-01.html. Consider if the `&hl` parameter needs to incorporate ideas from one of those.
* This says "use the DID Document Properties Extensions mechanism", which seems like a Registry sort of thing, but it's not using the W3C or IANA registry mechanisms. Should it?
* "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 [resource](https://www.w3.org/TR/did-resolution/#dfn-resources) with more precision than using the [DID](https://www.w3.org/TR/did-resolution/#dfn-decentralized-identifiers) alone." is hedgy ... this should probably be a SHOULD, and I think the note below this is a good description of what should be recommended.

[DID Resolution](https://www.w3.org/TR/did-resolution/#resolving):
* This refers to 'the "Read" operation of the applicable [DID method](https://www.w3.org/TR/did-resolution/#dfn-did-method-s) as described in [Method Operations](https://www.w3.org/TR/did-core/#method-operations)', but https://www.w3.org/TR/did-core/#method-operations doesn't mention the word "Read". What's the signature of that operation?
* It would be ideal if the definition of `didDocument` referred to https://www.w3.org/TR/did-1.0/#data-model, which actually defines DID documents.
* "match" is a yellow flag in specifications. Does this mean that it must be the same string, or does it use some other matching algorithm?
* `didDocument` says "MUST be a DID document that is capable of being represented", but https://www.w3.org/TR/did-resolution/#did-resolution-options says "The DID resolver implementation SHOULD use this value to determine the representation of the returned didDocument", which implies that the resolver is returning a serialized document rather than a parsed one. Which is it?

[DID Resolution Metadata](https://www.w3.org/TR/did-resolution/#did-resolution-metadata):
* The definition of `proof` includes, "the value MUST be a [set](https://infra.spec.whatwg.org/#sets) where each item is a [map](https://infra.spec.whatwg.org/#maps) that contains a proof". Maps hold key/value pairs, so it doesn't make sense for a map to "contain a proof". I also don't see a definition of the proofs these maps are supposed to hold.

[DID Document Metadata](https://www.w3.org/TR/did-resolution/#did-document-metadata)
* "A conforming [DID method](https://www.w3.org/TR/did-resolution/#dfn-did-method-s) specification MUST guarantee" <- Requirements on DID methods ought to live in DID core, not this document.
* Same problem with the `proof` field as in the Resolution Metadata.

[DID Resolution Algorithm](https://www.w3.org/TR/did-resolution/#resolving-algorithm):
* "against the input [DID](https://www.w3.org/TR/did-resolution/#dfn-decentralized-identifiers)'s [verifiable data registry](https://www.w3.org/TR/did-resolution/#dfn-verifiable-data-registry)" is probably unnecessary. If it is necessary, you'll need to specify how to find the "verifiable data registry".
* "This result MUST be represented in a [conformant representation](https://www.w3.org/TR/did-core/#representations) that corresponds to the accept input [DID resolution option](https://www.w3.org/TR/did-resolution/#did-resolution-options)." conflicts with the definition of that `accept` option, which only says it "SHOULD use this value to determine the [representation](https://www.w3.org/TR/did-resolution/#dfn-representations)".
* "Iterate over all [services](https://www.w3.org/TR/did-core/#services), [verification methods](https://www.w3.org/TR/did-core/#verification-methods), and [verification relationships](https://www.w3.org/TR/did-core/#verification-relationships)" <- Does this need to also iterate over any [extensions](https://www.w3.org/TR/did-1.0/#extensibility) in the document?

[Resolver Architectures](https://www.w3.org/TR/did-resolution/#resolver-architectures):
* "This inclusion can potentially enable a [client](https://www.w3.org/TR/did-resolution/#dfn-client) to independently verify the results of a [DID Resolution](https://www.w3.org/TR/did-resolution/#dfn-did-resolution) process, as long as it trusts the [DID resolver](https://www.w3.org/TR/did-resolution/#dfn-did-resolver-s)." doesn't sound like much of a proof if it requires the resolver to be trusted.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/1157#issuecomment-3439062470
You are receiving this because you are subscribed to this thread.

Message ID: <w3ctag/design-reviews/issues/1157/3439062470@github.com>