Multiple Responses from Peer-to-Peer Discovery

[mmccool]

It was noted that when "guessing" the URL to access TDs from self-describing Things given just the IP address that we have to deal with the case of endpoints that host multiple Things, like a gateway (which could have several services acting as Things, including proxies) or even endpoint with multiple sub-devices (e.g. a geolocator, a temp sensor, a humidity sensor, etc all in one device).

Proposed: the return value at .well-known can be an array of TDs. If this proposal makes sense, we should also discuss whether it should always be an array (e.g. should square brackets always be used even if there is just one element) or if the array notation is only necessary if there are multiple TDs. We could also discuss making this consistent with the TDD listing API, whether we need pagination (might be useful for gateways with a bunch of services, including, for instance, proxies for all devices on the LAN), etc. This aligns with my initial thought of making .well-known a special case of a TDD.

Assumption: authentication determines the identity of the requestor and whether they have access to any of the things or a subset. Only the subset they have the right to view should be returned. If the array would have been empty (no rights to view anything) then an Unauthorized error should be returned rather than an empty array.

[mmccool]

Discussion:

• Could also return one TD that links to other TDs. This gives a TD similar functionality of CoRE-RD, but without bringing in another spec (and format that needs to be parsed by a consumer). Would be helpful to identify with a special "ThingCollection" @type. Or we can use the existing "ThingLink" type
• If we return an array... in DNS service type, is it a Thing or a Directory?
• Maybe we should use CoRE-RD format for .well-known?
• We have an IANA content type for TDs, but not for "collections of TDs". So what would the content type of the .well-known endpoint be?
• in Node-wot script, can have expose multiple Things from the same script, servient exposes itself using a TD. This leads to different cases for one and multiple TDs. Do we switch between them? Or just always use ThinkLinks? Disadvantage: need to fetch two TDs, so two network transactions. If we return the TD itself for "singleton" Things then we avoid this problem for the simple case (one Thing for a given IP).

[mmccool]

I'm leaning towards:

• Using a ThinkLink TD, but only when there are multiple Things at a given IP address.
• We could ALLOW people to use a ThingLink even if they have only one TD.

[benfrancis]

I was under the impression that this use case was already solved by the text in section 5.2:

If the Thing or Thing Description Directory use the Well-Known Uniform Resource Identifier to advertise its presense, it MUST register its own Thing or Directory Description into the following path: /.well-known/wot-thing-description.

In other words, if a given origin hosts multiple Thing Descriptions and uses the Well-Known URI introduction mechanism then it should host a Directory Description at /.well-known/wot-thing-description, which would then provide an endpoint for a list of Things via a property, following the Directory Service API.

This is consistent with all of the other introduction mechanisms which can advertise ether a Thing Description or a Directory Description.

This came up in w3c/wot-profile#121 because I concluded that if we made the Well-Known URI discovery mechanism mandatory in the Core Profile then it would effectively also make support for the Directory Service API mandatory since the URI could resolve to a Directory Description as well as a Thing Description.

I don't imagine that's an intended side-effect, but since a host can only have one well-known URI, the only alternative seems to be to invent another mechanism for listing Thing Descriptions specifically for that feature.

Note that if read-only directories were allowed (see #208) and the only mandatory interaction affordance was the things property, then a Directory Description could actually be pretty simple.

Edit: Having the Well-Known URI resolve to a Thing Description (or Thing Link) which provides links to other Thing Descriptions using an item or hosts link relation type would also work (see #208 (comment)), but does that mean that all introduction mechanisms should support both that and Directory Descriptions?

[farshidtz]

@mmccool

• If we return an array... in DNS service type, is it a Thing or a Directory?

DNS Service will not need to return multiple TDs. This is just a use case for well-known (see #208 (comment)) because it doesn't allow adding base path. Multiple TDs can be registered as separate DNS SD services, with their own base path (td TXT record).

Summarizing discussed solutions to address the well-known URL limitation:

1. Use Thing Link to link other TD: Permit use of TD Links for Self-Description of Multiple Endpoints #269
2. Return an array of TDs
3. Partial Thing Directory with only listing endpoint (the things property)

Another option that comes to my mind is to return array of URLs:

GET /.well-known/wot-thing-description
Host: device.example.com

Response is an array of links relative to well-known URL:

HTTP/1.1 200 OK
Content-Type: application/json
[
  "proxied-thing1", --> http://device.example.com/.well-known/wot-thing-description/proxied-thing1
  "proxied-thing2"  --> http://device.example.com/.well-known/wot-thing-description/proxied-thing2
]

Note that well-known doesn't prevent additional path components:

Typically, a registration will reference a specification that defines
the format and associated media type to be obtained by dereferencing
the well-known URI.

It MAY also contain additional information, such as the syntax of
additional path components, query strings and/or fragment identifiers
to be appended to the well-known URI, or protocol-specific details
(e.g., HTTP [RFC2616] method handling).
https://datatracker.ietf.org/doc/html/rfc5785#section-3

[mmccool]

Let's follow up on issue #208 which can resolve this is .well-known returns a small static directory that only implements "listing". But we have to clearly indicate that "listing" is the ONLY mandatory affordance required, and that requires a bit of restructuring.

[mmccool]

So, I think this may be resolved now, technically, by having such endpoints return a (single) TD for a small, read-only directory, and our improvements to allow "listing" to be the only mandatory affordances in TDDs. But we MAY need to add some informative text somewhere to explain that this is what should be done in this case.

Going to "Propose Closing".