- shows an overview of discovery process.
+ shows an overview of the discovery process.
Architecture
alt="Discovery process overview" />
Discovery process overview
-
- To do: an overview of the two-phase approach and its purpose, which is to support
- controlled and authenticated access to metadata by authorized users only.
+ The WoT discovery process is designed using a two-phase approach.
+ In the first phase, one or more of a set of "Introduction" mechanisms may be used to
+ generate a set of candidate URLs. These URLs do not themselves contain metadata,
+ but are used in the second stage, "Exploration", to actually fetch metadata.
+ The intention is that Introductions are relatively open and can support any
+ mechanism that can return a URL, including simply entering URLs directly.
+ Introductions, however, do not include any security or privacy controls and
+ so should not provide metadata directly. Instead, the provided URLs are followed
+ to "Exploration" mechanisms that will actually provide metadata but allow for
+ suitable security and privacy controls.
+
+ Note that the discovery process can produce a set of URLs following
+ its Introduction phase, and the final output after the Exploration phase
+ can be a set of Thing Descriptions.
+ Generally each URL provided by the Introduction phase points at a Thing Description,
+ and in the simplest case this is in fact the Thing Description of a Thing that
+ represents an IoT device. In the case of self-describing Things the URL might
+ even point directly at the Thing which can serve its own Thing Description,
+ but in general Thing Descriptions might also be provided by other entities.
+ However, there are also two special cases that allow for more flexibility:
+
+
A given Thing Description may in fact describe a Thing Description Directory service.
+ A Thing Description Directory service (which is still a Thing) maintains a (usually dynamic) list of Thing Descriptions
+ which can be fetched and added to the discovery set (the set can be narrowed by
+ using query filters when fetching TDs from a directory).
+
+
+ The second special case is a Thing Link. This is also a Thing Description,
+ but rather than describing a Thing directly serves as a container for links to
+ other Thing Descriptions. There are two categories of links supporting redirection
+ and sets. Redirection allows for Thing Descriptions to be stored somewhere else
+ than at the exact URL provided by the Introduction. Sets allows for single URLs to expand
+ into multiple Thing Descriptions without needing to use a Thing Description Directory.
+ Such sets are only appropriate for small static lists of Thing Descriptions.
+ In both cases, a Thing Link resolves a single URL into one or more additional URLs
+ which are fed back into the Introduction set, replacing the original URL pointing
+ at the Thing Link. A Thing Description Directory can also store Thing Links
+ which can redirect to other Thing Description Directories, allowing for a linked
+ directory structure.
+
+
Introduction Mechanisms
@@ -306,6 +344,14 @@
Well-Known URIs
When a request is made at the above Well-Known URI, the server MUST return
a Thing Description as prescribed in [[[#exploration-self]]].
+ It is sometimes the case that a well-known URI
+ needs to index multiple TDs.
+ For example, a URI may be inferred from
+ an IP address but multiple Things are hosted
+ at that IP address. In this case, a single
+ TD is still returned by the process but that
+ TD is a Thing Link and is used only
+ to collect references to other TDs.
The service name in Well-Known URI (wot-thing-description) is tentative.
@@ -505,22 +551,53 @@
Exploration Mechanisms
Thing Link
-
- A TD which describes a reference to another TD MUST use type `ThingLink` from the
+
+
+ A TD which describes references to other TDs MUST use type `ThingLink` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingLink`.
-
-
- A Thing Link MUST define the referenced TD as a Link with
- `describedby` link relation type, `application/td+json` media type
- and `href` set to the target URL.
-
+
+
+ A Thing Link MUST include either only a single Link with the
+ `describedby` link relation type or one or more Links with any
+ combination of `hosts` and `external` relation types.
+
+ To be clear, `describedby` cannot be mixed with other Link relation types, and there should be
+ only one such Link.
+
+
+ A Thing Link including a Link with the `describedby` link relation type
+ MUST use `application/td+json` media type and `href` set to the target URL in that Link.
+
+
+ A Thing Link including Links with either `hosts` or `external` relation types
+ MUST use `application/td+json` media type for each such Link.
+
+
+ A Thing Link including a Link with the `hosts` relation type
+ MUST use an `href` set to the target URLs,
+ hosted under the same context IRI as the Thing Link, in each such Link.
+
+
+ A Thing Link including a Link with the `external` relation type
+ MUST use an `href` set to the target URLs,
+ hosted under a different context IRI as the Thing Link, in each such Link.
+
+
+ The use of the `hosts` or `external` relations does not imply anything about the content of the TD
+ hosted externally; for example, a TD referenced by either relation may or may not include local URLs.
+ This relation is just describing where the TD is located, not where the Thing that TD describes is
+ located.
+ It is usually the case, given the context URL restrictions on these relation types,
+ that `hosts` Links will use relative URLs and `external` Links will use
+ absolute URLs.
- [[[#example-td-link-type]]] is an example Thing Link.
+ [[[#example-td-link-type]]] is an example Thing Link using the `describedby` relation.
+ [[[#example-td-link-set]]] is an example Thing Link using the `hosts` and `external` relations.
-
@@ -578,12 +711,26 @@
Self-description
The self-description is an exploration mechanism in which a Thing
hosts its own TD and exposes it at a URL or
- through others means.
+ through other means.
If exposed at a URL (e.g. over HTTP or CoAP), the URL may be advertised
via one of the [[[#introduction-mech]]].
- The hosted TD may also be registered inside a Thing Description Directory
+ The same TD may also be registered (at different URL) inside a Thing Description Directory
as prescribed in [[[#exploration-directory]]].
+
+ In some cases a single URL may need to return multiple
+ TDs. For large numbers of TDs that may need to change
+ dynamically over time,
+ a Thing Description Directory (TDD)
+ can be used instead; in such a case the TD returned is that
+ of the TDD.
+ If a small fixed number of TDs need to be returned,
+ particularly on small devices that do not want to host the
+ full TDD interface, a single TD can be returned, marked as
+ a Thing Link, which link to multiple TDs hosted
+ at different
+ URLs.
+
The self-description using the following protocols must be according
to the given specification:
Architecture
alt="Discovery process overview" />