Skip to content

Commit

Permalink
Merge pull request #115 from farshidtz/self-description
Browse files Browse the repository at this point in the history 
Specify self-described exploration
  • Loading branch information
@mmccool
mmccool authored Feb 15, 2021
2 parents b122b36 + 0ee7abc commit 603557d
Showing 1 changed file with 83 additions and 10 deletions.
93 changes: 83 additions & 10 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,11 +227,22 @@ <h1>Introduction</h1>
<section id="conformance"></section>
<section id="terminology" class="informative">
<h1>Terminology</h1>
<p>The present document uses the terminology defined in
the WoT Architecture [[wot-architecture]] document,
and also the additional terms defined here.
The WoT prefix is used to avoid ambiguity for terms that are
(re)defined specifically for Web of Things concepts.</p>

<p>
The fundamental WoT terminology such as
<dfn>Thing</dfn>,
<dfn>Thing Description</dfn> (<dfn>TD</dfn>),
<dfn>Property</dfn>,
<dfn>Action</dfn>,
<dfn>Event</dfn>
are defined in <a href="https://www.w3.org/TR/wot-architecture/#terminology">Section 3</a>
of the WoT Architecture specification [[?WOT-ARCHITECTURE]].
</p>

<p>
In addition, this specification introduces the following definitions:
</p>

<dl>
<dt><dfn data-lt="WoT Anonymous Thing Description">Anonymous TD</dfn>
</dt>
Expand All @@ -255,7 +266,11 @@ <h1>Terminology</h1>
should not directly provide metadata, and in general are designed to be
open.
</dd>
<dt><dfn data-lt="WoT Thing Description Directory">Thing Description Directory (TDD)</dfn>
<dt><dfn data-lt="WoT TDD">TDD</dfn>
</dt>
<dd>Short for Thing Description Directory.
</dd>
<dt><dfn data-lt="WoT Thing Description Directory">Thing Description Directory</dfn>
</dt>
<dd>A directory service with a prescribed API that allows the
registration, management, and search of a database of Thing Descriptions.
Expand Down Expand Up @@ -289,12 +304,18 @@ <h1>Introduction Mechanisms</h1>
The following mechanism is provided by the Thing or the Directory Service so that
Consumer can discover the Thing Description or a URL that point to the Thing Description.
</p>
<p class="ednote" title="Missing assertion blocks">
The following sub-sections define assertions without
using the `rfc2119-assertion` class.
</p>

<section id="introduction-direct" class="normative">
<h2>Direct</h2>
<p>Any mechanism that results in a single URL.
This includes Bluetooth beacons, QR codes, and written URLs to be
typed by a user.
A GET on all such URLs MUST result in a TD.
A request on all such URLs MUST result in a TD as prescribed in
[[[#exploration-self]]].
For self-describing Things, this can be the TD of the Thing itself.
If the URL references a Directory, this MUST be the TD of the
Directory service.
Expand All @@ -308,8 +329,8 @@ <h2>Well-Known URIs</h2>
into the following path:
<code>/.well-known/wot-thing-description</code>.
<p>
When the HTTP GET access is made to the above path, the HTTP server MUST return
a Thing Description with the <code>content-type</code> set to <code>application/td+json</code>.
When a request is made at the above path, the server MUST return
a Thing Description as prescribed in [[[#exploration-self]]].
</p>
<p class="ednote" title="Registration of Well-known URI">
The service name in Well-Known URI (<code>wot-thing-description</code>) is tentative.
Expand Down Expand Up @@ -512,9 +533,61 @@ <h1>Exploration Mechanisms</h1>

<section id="exploration-self" class="normative">
<h2>Self-description</h2>
<p class="ednote" title="Self-Description Overview">
<!-- <p class="ednote" title="Self-Description Overview">
To do: Describe mechanisms for devices to self-describe, hosting their own TDs.
</p> -->
<p>
The self-description is an exploration mechanism in which a <a>Thing</a>
hosts its own <a>TD</a> and exposes it at a URL or
through others 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 <a>Thing Description Directory</a>
as prescribed in [[[#exploration-directory]]].
</p>

The self-description using the following protocols must be according
to the given specification:
<dl>
<dt>HTTP</dt>
<dd>
<p>
<span class="rfc2119-assertion" id="self-http-secure">
The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS).
</span>
<span class="rfc2119-assertion" id="self-http-method">
The HTTP server MUST serve the TD with a `GET` method.
</span>
<span class="rfc2119-assertion" id="self-http-resp">
A successful response MUST have 200 (OK) status, contain `application/td+json`
Content-Type header, and the TD in body.
</span>
<span class="rfc2119-assertion" id="self-http-alternate-content">
The server MAY provide alternative representations through
server-driven content negotiation, that is by honouring the
request's Accept header and responding with the supported
TD serialization and equivalent Content-Type header.
</span>
<span class="rfc2119-assertion" id="self-http-access-control">
The server SHOULD serve the requests after performing necessary
authentication and authorization.
</span>
</p>

<p>
Error responses:
<ul>
<li>
401 (Unauthorized): No authentication.
</li>
<li>
403 (Forbidden): Insufficient rights to the resource.
</li>
</ul>
</p>
</dd>
</dl>
<!-- add additional protocols for self-description here -->

</section>
<section id="exploration-directory" class="normative">
Expand Down

0 comments on commit 603557d

Please sign in to comment.