DID Resolution section standardizes API instead of data format

[JelleMillenaar]

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.