What is a Thing Directory?

[benfrancis]

I suggest it would be useful to reach a consensus on a definition of a Thing Directory so that we know we are all taking about the same thing. In particular, what is a "directory" vs. a "gateway".

The discussion in #18 revealed three discrete functions:

1. Hosting a list of Thing Descriptions
2. Hosting Thing Descriptions
3. Hosting the API/protocol endpoints to communicate with a Thing

I'd suggest that a service which carries out all three of these functions is definitely a "gateway". A service which carries out nos. 1 and 2 could be described as a directory, but so could a service which only does no. 1 (by linking to Thing Descriptions hosted elsewhere).

In the Mozilla/Krellian proposal for a Thing Directory a "directory" need only link to Thing Descriptions (no. 1). A "gateway" would be a superset of a directory which also does 2 and 3 and the Thing Descriptions and API endpoints happen to be hosted by the same service as the directory.

• A thing "directory" provides a list of links to Thing Descriptions, can have web things explicitly added to it and removed from it by URL by a WoT client, and can notify a WoT client when a thing is added, removed or updated.
• A "gateway" may also host the Thing Descriptions and API endpoints of devices which it bridges from other protocols and adds to the list of Things itself, as the result of some other device pairing action which may itself be initiated by the user

It sounds like there might be another type of service which does nos. 1 and 2 but not 3, where a Thing Description is hosted by the service but the API endpoints are hosted elsewhere.

In the first draft of the Use Cases & Requirements document for the Web Thing Protocol I made an attempt at defining WoT gateways and directories.

In that document I wrote:

A WoT directory is a service which provides a list of web things and links to their Thing Descriptions.

Do we agree that a service need only need link to Thing Descriptions to be considered a directory, or must it host them as well? Or are there two types of directory?

[zolkis]

A WoT directory is a service which provides a list of web things and links to their Thing Descriptions.

IMHO a Thing Directory is a service that makes TD discovery possible by knowing a single URL - as opposed to other forms of discovery, e.g. a multicast request to return TDs or needing to know each Thing's TD's URL. Anyway, the main function is providing TDs, optionally based on provided filters, authorization level etc. I don't think the clients would be interested whether the Things are hosted or just linked.

[relu91]

IMHO a Thing Directory is a service that makes TD discovery possible by knowing a single URL - as opposed to other forms of discovery, e.g. a multicast request to return TDs or needing to know each Thing's TD's URL.

I am on the same page, although we can state that the minimal service is something that hosts a list of Thing Descriptions (hence the point 1). Which is quite in line with CORE resource Directory

On the other hand, I think we all agree that point 3 is another functionality which maybe implemented in a TDD instance but it does not define it as a TDD.

[mmccool]

We were discussing this in the Directory TF call June 6. Summary of our discussion follows:

1. I think there is some confusion between a gateway service and a gateway device. A gateway device is just an edge computer box (eg from your ISP) that may run multiple services, act as a NAT and firewall, etc. To avoid confusion, let's use "gateway" in the following to refer only to a service.
2. A directory in our current definition does only function 2, i.e. acting as a searchable repository for TDs. We are currently discussing adding explicit support for function 1, i.e. also storing a searchable set of links to other directories and TDs available elsewhere. For example, a sensitive medical device may not want to register its TD with the directory, but might store only a link and require you to authenticate directly with the Thing to access it. A directory service definitely would not do function 3. Protocol translation would be the function of a separate ("gateway") service and is important especially for non-IP protocols like Zigbee that can't have TDs, even in theory. However, the (conceptually separate) gateway service might register TDs for the bridged protocol with the directory.
3. If we do add links (function 1) to directories, then I think personally it is reasonable to have directories that only have links and no TDs (because it would start out empty of both links and TDs, but maybe only links get registered). Note: probably when a TD is added to a directory, we might also always create a link to it in the links section. But the links section might also have remote entries to other directories and remote TDs hosted elsewhere. We do need to discuss further what kind of metadata can be associated with the links to facilitate search, or even if we want links. See Issue https://github.com/w3c/wot-discovery/issues/34 for further discussion of links.

However, the Web Things definition is not quite accurate, because the purpose is not just to store links. The purpose is to facilitate access to TDs and provide an ability to search a collection of them, and more generally to "distribute" TDs. So even if we support links (function 1) they are not ideal for providing access to TDs since they are not as searchable as having full TDs registered, and function 2 should be considered the primary purpose.

[benfrancis]

@mmccool It's interesting that you see no. 2 as the primary function and no. 1 as an extension of that, whereas I was thinking of it as being the other way around.

I suppose it ultimately depends on the design of the discovery API/protocol.

• In the Mozilla/Krellian proposal the directory API would expose the list of Thing Descriptions as a list of links, both for Thing Descriptions served by the same service and for links to externally hosted Thing Descriptions.
• In the Fraunhofer LinkSmart proposal appears to serve a list of the Thing Descriptions themselves as a single JSON resource with extra wrapping metadata.
• The current Mozilla specification (and WebThings Gateway implementation) falls somewhere in between. It exposes a Things resource which serves a list of the Thing Descriptions themselves as a JSON array, but also includes a href in each Thing Description which links to the canonical URL of each individual Thing Description.

The rationale behind the new Mozilla/Krellian proposal of exposing the list of Thing Descriptions as a list of links is so that the directory itself can be described by a Thing Description, without having to serve both the Thing Description of the directory and the Thing Descriptions of all of its children in a single resource.

[farshidtz]

We should also keep in mind that not all devices are self-describing, i.e. serving a TD.

There are use cases where devices have IP-based networking interfaces but cannot be customized to serve a TD which describes their metadata and interactions. The TD for such devices can be created and registered to the directory by a third party application (script, UI). The directory or the third party application are not acting as gateways. They don't proxy the interactions and the endpoints are directly exposed and served by the devices themselves.

[benfrancis]

We should also keep in mind that not all devices are self-describing, i.e. serving a TD.

Yes, that would be functions 1 & 2, but not 3. i.e. a directory that isn't also a gateway. I think that should be possible with all of the API designs described above.

[mmccool]

The current spec supports 1 & 2, but not 3. I would propose we close this issue but perhaps open a new issue to provide "gateway" functionality (actually, it is reasonable to combine a proxy and a directory) in a future spec but doing that right may require some additional features we definitely don't have time to get into in this version.

Will mark this both as "Propose Closing" and "Defer" and "Discuss". I would rather only close after we create the new, more focused issue so we don't forget about it :)