Skip to content

Commit

Permalink
Add section for TD types
Browse files Browse the repository at this point in the history
  • Loading branch information
@farshidtz
farshidtz committed May 16, 2022
1 parent 001fe38 commit a808f9b
Showing 1 changed file with 138 additions and 127 deletions.
265 changes: 138 additions & 127 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -295,9 +295,9 @@ <h1>Architecture</h1>
using query filters when fetching TDs from a directory).
</li>
<li>
The second special case is a Thing Link. This is also a Thing Description,
but rather than describing a Thing directly holds a link to
a Thing Descriptions hosted elsewhere.
The second special case is a <a href="#exploration-td-type-thingdirectory">Thing Link</a>. This is also a Thing Description,
but rather than describing a Thing directly holds a link to
a Thing Descriptions hosted elsewhere.
A Thing Description Directory can also store Thing Links
which can redirect to other Thing Description Directories, allowing for a linked
directory structure.
Expand Down Expand Up @@ -394,7 +394,8 @@ <h1>Discoverer Process</h1>
</li>
<li><span class="rfc2119-assertion" id="discoverer-td-identify">
A Discoverer MUST be able to identify whether a TD fetched from an
Introduction URL is a Thing Description Directory or a Thing Link.</span>
Introduction URL has <a href="#exploration-td-type-thingdirectory">Thing Directory</a>
or <a href="#exploration-td-type-thingdirectory">Thing Link</a> type.</span>
This implies that the Discoverer needs to be able
to check the <code>@type</code> field and make this distinction.

Expand All @@ -414,14 +415,14 @@ <h1>Discoverer Process</h1>
might be prohibitively expensive.
</li>
<li><span class="rfc2119-assertion" id="discoverer-fetch-links">
A Discoverer MAY fetch source TDs from the targets of the links in a Thing Link
A Discoverer MAY fetch source TDs from the targets of the links in a <a href="#exploration-td-type-thingdirectory">Thing Link</a>
described in its initial set of TDs and add them into the set of TD results.</span>
This only adds the results of fetching TDs from a Thing Link to the set of
results. These new results do not delete the original TD describing the Thing Link.
A Discoverer implementation can decide whether or not to fetch the targets of Thing Links.
</li>
<li><span class="rfc2119-assertion" id="discoverer-fetch-iteration">
A Discoverer MAY fetch additional TDs iteratively from any Thing Link or
A Discoverer MAY fetch additional TDs iteratively from any <a href="#exploration-td-type-thingdirectory">Thing Link</a> or
Exploration mechanism described in its set of TDs and add them into the set of TD results.</span>
This only adds the results of fetching TDs from an Exploration mechanism to the set of
results. These new results do not delete the original TD describing the Exploration mechanism.
Expand All @@ -448,7 +449,7 @@ <h1>Discoverer Process</h1>
</ul>
<p>
The above process supports a way to let Directories reference other Directories without duplicating their TDs:
a Directory wanting to reference other Directories should include a Thing Link with a "describedby" relation to the
a Directory wanting to reference other Directories should include a <a href="#exploration-td-type-thingdirectory">Thing Link</a> with a "describedby" relation to the
TD of the other Directory service. Then the above process would expand the Thing Link to obtain the actual TD of the Directory,
and then (optionally) use the appropriate Directory affordance to access the contents of the linked Directory.
Note that such a Thing Link points at the TD of the Directory, not at the Directory itself. These
Expand Down Expand Up @@ -648,135 +649,145 @@ <h1>Exploration Mechanisms</h1>
To do: Description of supported explorations, and requirements for
new exploration mechanisms.
</p>
<div class="issue" data-number="202"></div>

<figure id="exploration-class-diagram">
<img src="images/exploration-class-diagram.svg"
class="wot-diagram"
alt="Exploration mechanisms high-level class diagram" />
<figcaption>
The high-level class diagram of the exploration mechanisms,
depicting how Things expose <a>TDs</a>.
</figcaption>
</figure>
<section id="exploration-overview" class="normative">
<h2>Overview</h2>
<figure id="exploration-class-diagram">
<img src="images/exploration-class-diagram.svg"
class="wot-diagram"
alt="Exploration mechanisms high-level class diagram" />
<figcaption>
The high-level class diagram of the exploration mechanisms,
depicting how Things expose <a>TDs</a>.
</figcaption>
</figure>

[[[#exploration-class-diagram]]] depicts the high-level information
model for self-describing and directory services.
A directory may contain <a>TDs</a> and at the same time provide a <a>TD</a>
and act as a self-describing Thing.
The exploration mechanisms are described in
[[[#exploration-self]]] and [[[#exploration-directory]]].

<figure id="discovery-class-diagram-ontology">
<img src="images/discovery-class-diagram-ontology.svg"
class="wot-diagram"
alt="Ontology of TD in discovery context" />
<figcaption>The ontology of Thing Descriptions in the Discovery context.</figcaption>
</figure>
[[[#exploration-class-diagram]]] depicts the high-level information
model for self-describing and directory services.
A directory may contain <a>TDs</a> and at the same time provide a <a>TD</a>
and act as a self-describing Thing.
The exploration mechanisms are described in
[[[#exploration-self]]] and [[[#exploration-directory]]].

<section id="exploration-ontology" class="normative">
<h3>Ontology</h3>
<figure id="discovery-class-diagram-ontology">
<img src="images/discovery-class-diagram-ontology.svg"
class="wot-diagram"
alt="Ontology of TD in discovery context" />
<figcaption>The ontology of Thing Descriptions in the Discovery context.</figcaption>
</figure>

<p>
[[[#discovery-class-diagram-ontology]]] illustrates the Discovery ontology
as an extension of the Thing ontology.
</p>
<p>
The ontology includes a class for metadata that are associated with
TDs stored in a directory.
This class is called `RegistrationInformation` and described as part
of the directory specification in [[[#exploration-directory-registration-info]]].
</p>
<p>
[[[#discovery-class-diagram-ontology]]] illustrates the Discovery ontology
as an extension of the Thing ontology.
</p>
<p>
The ontology includes a class for metadata that are associated with
TDs stored in a directory.
This class is called `RegistrationInformation` and described as part
of the directory specification in [[[#exploration-directory-registration-info]]].
</p>

<p>
Moreover, the Discovery ontology defines two new Thing Description classes
that may be used to model special exploratory metadata:
</p>
<p>
Moreover, the Discovery ontology defines two new Thing Description classes
that may be used to model special exploratory metadata:
</p>

<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>
<section id="exploration-td-type-thingdirectory" class="normative">
<h4>`ThingDirectory`</h4>
<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>

<dt>Thing Directory</dt>
<dd>
<span class="rfc2119-assertion" id="exploration-directory-description-type">
A TD which describes a Thing Description Directory instance MUST use type `ThingDirectory` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingDirectory`.
</span>
<p>
[[[#directory-api-spec]]] which describes the API of the
Thing Description Directory is an example of this TD class.
</p>
</dd>

<dt>Thing Link</dt>
<dd>
<span class="rfc2119-assertion" id="exploration-link-description-type">
A TD which describes a reference to another TD MUST use type `ThingLink` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingLink`.
</span>
<span class="rfc2119-assertion" id="exploration-link-description-link">
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.
</span>
<span class="rfc2119-assertion" id="exploration-directory-description-type">
A TD which describes a Thing Description Directory instance MUST use type `ThingDirectory` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingDirectory`.
</span>
<p>
A TD of this class can be derived from Directory's Thing Model; see [[[#directory-api-spec]]].
</p>

</section>
<section id="exploration-td-type-thinglink" class="normative">
<h4>`ThingLink`</h4>
<div class="issue" data-number="148">
The type URIs used below are tentative and subject to change.
</div>

<span class="rfc2119-assertion" id="exploration-link-description-type">
A TD which describes a reference to another TD MUST use type `ThingLink` from the
discovery context or URI `https://www.w3.org/2021/wot/discovery#ThingLink`.
</span>
<span class="rfc2119-assertion" id="exploration-link-description-link">
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.
</span>

<p>
[[[#example-td-link-type]]] is an example Thing Link.
</p>
<p>
[[[#example-td-link-type]]] is an example Thing Link.
</p>

<!-- Using https://tools.ietf.org/html/rfc6963 for ID of examples -->
<aside class="example" id="example-td-link-type" title="Example of a Thing Link, referencing a remote TD">
<pre>
{
"@context": [
"http://www.w3.org/ns/td",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"@type": "ThingLink",
"id": "urn:example:link",
"links": [{
"rel": "describedby",
"href": "https://example.com/td.jsonld",
"type": "application/td+json"
}],
"security": "nosec_sc",
"securityDefinitions": {
"nosec_sc": {
"scheme": "nosec"
<!-- Using https://tools.ietf.org/html/rfc6963 for ID of examples -->
<aside class="example" id="example-td-link-type" title="Example of a Thing Link, referencing a remote TD">
<pre>
{
"@context": [
"http://www.w3.org/ns/td",
"https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
],
"@type": "ThingLink",
"id": "urn:example:link",
"links": [{
"rel": "describedby",
"href": "https://example.com/td.jsonld",
"type": "application/td+json"
}],
"security": "nosec_sc",
"securityDefinitions": {
"nosec_sc": {
"scheme": "nosec"
}
},
"title": "Example TD referencing another"
}
},
"title": "Example TD referencing another"
}
</pre>
<div class="issue" data-number="148">
The context URIs are tentative and subject to change.
</div>
</aside>
<p>
A Thing Link can be used in various scenarios. For example:
<ul>
<li>
A self-describing Thing with limited computational resources intends
to describe itself: host a minimal <a>TD</a> (Thing Link) locally
and references a larger one with the full details hosted at a
different URL, perhaps in a directory.
</li>
<li>
A self-describing Thing or proxy has a very large or dynamic description:
registers a small or static <a>TD</a> (Thing Link) in a
directory which references the actual <a>TD</a> hosted at the edge.
</li>
<!-- We decided to remove this use case, since it is probably best
handled with access controls. However, this use case AND the ones
above imply a mix of link and other metadata and affordances, not
"pure" Thing Links. So we can't in general assume Thing Links
don't have other information.
<li>
A device intends to publish an entire <a>TD</a> which contains private and
public parts: publish one <a>TD</a> (Thing Link) with only the public
information referencing another <a>TD</a> which contains the full description.
</li>
-->
</ul>
</p>
</dd>
</pre>
<div class="issue" data-number="148">
The context URIs are tentative and subject to change.
</div>
</aside>
<p>
A Thing Link can be used in various scenarios. For example:
<ul>
<li>
A self-describing Thing with limited computational resources intends
to describe itself: host a minimal <a>TD</a> (Thing Link) locally
and references a larger one with the full details hosted at a
different URL, perhaps in a directory.
</li>
<li>
A self-describing Thing or proxy has a very large or dynamic description:
registers a small or static <a>TD</a> (Thing Link) in a
directory which references the actual <a>TD</a> hosted at the edge.
</li>
<!-- We decided to remove this use case, since it is probably best
handled with access controls. However, this use case AND the ones
above imply a mix of link and other metadata and affordances, not
"pure" Thing Links. So we can't in general assume Thing Links
don't have other information.
<li>
A device intends to publish an entire <a>TD</a> which contains private and
public parts: publish one <a>TD</a> (Thing Link) with only the public
information referencing another <a>TD</a> which contains the full description.
</li>
-->
</ul>
</p>
</section>
</section>
</section>

<section id="exploration-self" class="normative">
<h2>Self-description</h2>
Expand Down

0 comments on commit a808f9b

Please sign in to comment.