DID Resolution section standardizes API instead of data format

For the IOTA Identity framework, an implementation of the iota did method, we are currently discussing our resolution logic to be better in-line with the DID spec. In Section 7.1, the DID Resolution logic is defined in an API format that has a fixed set of functions with certain parameters and expected return values. Given the addition Resolution document it looks like it strongly defines a fixed API, but this is inconsistent with how the DID standard has been written.

Any other section in the DID standard rather describes a data format. It leaves the implementation up to the library developers, which provides a certain level of freedom for library developers to design an API that fits their design principles and patterns. As such, for the IOTA Identity framework, we want to hide unnecessarily complicated parts from the library consumers by default and provide them with access to more complicated data / features via extra API calls. For example, 90%+ of the DID use cases probably will not be interested in the DID Document Metadata or DID Resolution Metadata, while some other library consumers might. Therefore we want to introduce a simple API to return those results if someone is interested in it, but not pollute the return data of the resolve or resolveRepresentation function with them. The effect on projects like the Universal Resolver might be that their integration of IOTA Identity gets slightly more complicated, but not much.

Long story short, my question/suggestion is for the DID spec to remain a specification for data formats instead of defining an API. If agreed upon, it would drop the suggestion for how the resolve and resolveRepresentation functions should look like and instead purely define data structures such as didResolutionMetadata, didResolutionMetadata and didDocumentMetadata.

PS. Is this the best format for suggestion or questions as an outsider of the WG? We have more questions/suggestions.

Hello @JelleMillenaar thanks for your feedback..!

The DID WG had long discussions if (and to what extent) DID Resolution should be defined in DID Core. The conclusion was that DID Core should define an abstract interface (an API), but not a concrete implementation of the protocol(s) or data format(s) of DID Resolution. The main reason for this is that DID Resolution can come in many forms; sometimes it is implemented as an HTTP service (like the DIF Universal Resolver), and sometimes it is a purely local process (e.g. when resolving a did:key using a local library). At this point of the standardization process, your suggestion to remove the API and add data formats to DID Core unfortunately comes too late, we cannot make such changes anymore (at least in DID Core 1.0).

As you note, the DID Resolution specification (which is a work item in the W3C Credentials Community Group rather than the W3C DID WG) goes into more detail and defines a concrete HTTP(S) binding and also a concrete JSON-LD data format for the resultion result (including a DID document + metadata). This DID Resolution specification is still lagging a bit behind DID Core and may not be 100% consistent. We will work on updating it and would certainly welcome your help if you have thoughts on this!

The DIF Universal Resolver is one implementation of a DID resolver (there are many others). It tries to be an accurate implementation of the DID Resolution specification. In this implementation, I believe your idea to only return the DID document without metadata should already be supported, e.g. you could try this to retrieve the DID document plus metadata:

curl "https://dev.uniresolver.io/1.0/identifiers/did:sov:builder:VbPQNHsvoLZdaNU7fTBeFx"

Or this to retrieve only the DID document:

curl -H "accept: application/did+ld+json" "https://dev.uniresolver.io/1.0/identifiers/did:sov:builder:VbPQNHsvoLZdaNU7fTBeFx"

I would also be very interested in learning more about the IOTA identity framework and how DID Resolution happens there. I would however suggest to move the discussion elsewhere since as mentioned above I think it's not directly relevant to DID Core, e.g.:

Github issues on the DID Resolution specification: https://github.com/w3c-ccg/did-resolution
DIF Identifiers&Discovery Working Group (if you are a member): https://identity.foundation/working-groups/identifiers-discovery.html

How does this sound?

This is delayed waiting on feedback by @JelleMillenaar. Please respond to @peacekeeper.

The conclusion was that DID Core should define an abstract interface (an API), but not a concrete implementation of the protocol(s) or data format(s) of DID Resolution.

This is what confuses me, the rest of the DID Core purely defined data formats and has little to no implementation requirements. With the only exception being the DID Resolution section, which defines an API.

At this point of the standardization process, your suggestion to remove the API and add data formats to DID Core unfortunately comes too late, we cannot make such changes anymore (at least in DID Core 1.0).

Is this still the case now that the DID Core has extended? While it is not a big bother to me, we have decided to not support the API and design an API that fits our own style. Through future integration with the Universal Resolver we hope to still have a compliant version available.

I would also be very interested in learning more about the IOTA identity framework and how DID Resolution happens there.

If you (@peacekeeper) ever have some time, I would love to schedule a call to discuss our DID method. The IOTA Tangle is a particularly challenging environment for a DID method with a non-linear Directed Acyclic Graph and the implementation not running on a Smart Contract. It might be mutual beneficial to walk through our solution such that we might be able to provide more feedback to the spec, while also being able to validate some of our assumptions / interpretation of the spec.

@msporny My apologizes for not responding sooner, I thought that as the DID Core was locked and the discussion was done. But I am happy to see we can still provide input.

@msporny My apologizes for not responding sooner, I thought that as the DID Core was locked and the discussion was done. But I am happy to see we can still provide input.

DID Core v1.0 is locked and done, that much is true.

However, the group will continue to exist until this summer 2022, and after that, there will be a DID maintenance Working Group of some form. A future DID WG can decide to make changes to the core specification, and often will. Remember, while HTML 1.0 was a specification, eventually HTML2, HTML4, and HTML5 came after it (and those specs changed in fairly radical ways).

So, everything I say below is speculative and just my opinion. The specification will continue to be refined as long as there is a desire to do so.

The conclusion was that DID Core should define an abstract interface (an API), but not a concrete implementation of the protocol(s) or data format(s) of DID Resolution.

This is what confuses me, the rest of the DID Core purely defined data formats and has little to no implementation requirements. With the only exception being the DID Resolution section, which defines an API.

DID Resolution defined and abstract API... but yes, your read is true in general.

Is this still the case now that the DID Core has extended? While it is not a big bother to me, we have decided to not support the API and design an API that fits our own style. Through future integration with the Universal Resolver we hope to still have a compliant version available.

It is still the case, the WG is done with DID Core v1.0, but as I said above... there might be a DID Core v1.1 or DID Core v2.0 in the future that could take your comments into consideration.

It is perfectly reasonable to NOT implement the DID Resolution section. There are different conformance classes in DID Core:

https://www.w3.org/TR/did-core/#conformance

If you don't implement the resolution section, you can't claim you have a "conforming DID resolver"... but that's fine if you don't want to make that claim. You can claim other things in the specification, such as you having a conforming DID, conforming DID document, conforming producer, conforming consumer, or conforming DID Method specification.

If you (@peacekeeper) ever have some time, I would love to schedule a call to discuss our DID method. The IOTA Tangle is a particularly challenging environment for a DID method with a non-linear Directed Acyclic Graph and the implementation not running on a Smart Contract. It might be mutual beneficial to walk through our solution such that we might be able to provide more feedback to the spec, while also being able to validate some of our assumptions / interpretation of the spec.

I would love to touch base at some point. I'm exceedingly time starved at present with wrapping up the DID WG and starting up the VC 2.0 WG, and I don't expect that to change until the summer. Sorry, that's just where I'm at righ tnow. That said, Veres One (a DID Method we've implemented) also uses a DAG and witness-based consensus and, I expect, shares some aspects of the IOTA Tangle... so I'm interested, but without time to engage right now.

If you (@peacekeeper) ever have some time, I would love to schedule a call to discuss our DID method.

@JelleMillenaar Yes I would definitely be interested in talking and learning more about your DID method. We should probably keep implementation-specific discussions separate from the DID Core Github repo. Maybe reach out to me on LinkedIn or DIF Slack (not sure if you are a member)?

w3c / did-core

DID Resolution section standardizes API instead of data format #798