Fix DIDComm service

[brianorwhatever]

DIDComm spec changed to an object for serviceEndpoint

---

Preview | Diff

[dlongley]

While I see that this is just a reconfiguration of some old spec text where some object properties appear, I think time and more implementation experience has indicated that a better design is to encapsulate any parameters in the protocol URL. I worry that this broken out approach isn't going to slot in very well with any of the other protocols or assumptions made by tooling that needs to express multiple protocols.

Can these parameters instead be expressed in the URL? The expectation is that every protocol can use a URL to get an exchange / interaction started. Being able to encapsulate in that manner with any protocol options makes other software that is protocol-agnostic simpler -- and how to pass this information along to credential handlers if expressed via protocols in a CHAPI request, for example, is more straightforward. So could this be expressed, instead, as:

    "id": "did:example:123456789abcdefghi#didcomm-1",
    "type": "DIDCommMessaging",
    "serviceEndpoint": "https://example.com/path?accept=didcomm%2Fv2%2Cdidcomm%2Faip2%3Benv%3Drfc587&routingKeys=did%3Aexample%3Asomemediator%23somekey"

I generated the above like this:

x = new URLSearchParams({
  accept: ['didcomm/v2', 'didcomm/aip2;env=rfc587'],
  routingKeys: 'did:example:somemediator#somekey'
});
console.log('https://example.com/path?' + x.toString());

[TallTed]

I would like those parameters to be expressible in either the URL or the breakout style. URL lengths have arbitrary limits in various places, usually not (but still sometimes!) lower than 1024 chars, which I can imagine being exceeded as more parameters and more options need to be expressed and/or the values of those params increase (as I expect routingKeys to do).

Flexibility is often key to handling such limitations. Working with the SPARQL protocol, for instance, the SPARQL query may be in the URL as &query= for a GET or submitted as the HTTP request message body (i.e., outside the URL) via POST.

Also, this human finds the breakout above far easier to evaluate and understand than the encapsulation. If the point of this document is to educate humans, the breakout is more likely to be generally comprehensible.

I would be perfectly happy if both presentations were included in our documents, and I could live with the specs making interpretation of the URL a MUST and interpretation of the breakout a MAY (though I'd prefer a SHOULD).

[brianorwhatever]

Although I understand the desire for simplicity, this PR is meant to document reality. This is the relevant text in the DIDComm spec. As you can see serviceEndpoint must be an object.. I can bring this up if the DIDComm WG starts back up..

[dlongley]

@brianorwhatever,

Although I understand the desire for simplicity, this PR is meant to document reality.

Ok, I'll approve on that basis. But do read my comments below to Ted:

@TallTed,

I pretty much agree with everything you said and would prefer things to work that way as well. Unfortunately, the reality is that the URL size limitation is really driving everything.

While it's true that we can express broken out parameters in VPRs (since it's just JSON), the mechanism for transporting that information in important cases requires converting them to a URL representation anyway.

Specifically, it's not feasible to transport that information from the CHAPI mediator to native apps other than via URL (when using a polyfill). There aren't any other Web primitives that can get the job done that implementers are willing to use (the "Web Share" primitive exists but has bad UX and is very hard to implement -- and is itself size limited).

So while some mediums for VPRs might be able to handle the broken out parameters, I fear that flexibility will ultimately lead to interoperability and market problems. It's better, IMO, to signal that initial interaction information is limited to URLs to help people ensure their protocol designs account for it, i.e., they should ensure one can create initial (sufficiently short) URLs to get interactions started. If other parameters are needed for an interaction, they will need to be communicated over the channel of communication that the initial interaction URL enables.

Note: It's true that non-polyfill / platform-specific code or features could enable the transfer of information to native apps in some other way, but this requires someone to write platform- or browser-native code and for platform or browser vendors to accept and deploy it. A prerequisite for getting features into the browser is usually significant incubation -- which requires polyfilling. As mentioned, I don't think that's a possibility here without using URLs. When such incubation doesn't occur (regardless of whether it's required or not), there's also a strong risk for platform or browser vendors to create proprietary solutions that preference their own platforms and applications, cutting out other participants.

In the end, there's a good chance the result is that either the protocol that can't fit into a URL won't be used -- or some other outcome that is more undesirable than whatever benefits having broken out parameters brings. DIDComm designers (or any other protocol designers) should be made aware of this -- and the strongest way to signal it is to force them to use the primitive that has to be used anyway: URLs.

[TallTed]

I weep for the future. But I get it. Hopefully all the URL-using tools will be updated to accept much larger URLs than many do today.

[dlongley]

Approving since this is documenting reality, but I've noted problems with the approach in comments.