diff --git a/index.html b/index.html index 4424c862..658ae83b 100644 --- a/index.html +++ b/index.html @@ -227,11 +227,22 @@

Introduction

Terminology

-

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.

+ +

+ The fundamental WoT terminology such as + Thing, + Thing Description (TD), + Property, + Action, + Event + are defined in Section 3 + of the WoT Architecture specification [[?WOT-ARCHITECTURE]]. +

+ +

+ In addition, this specification introduces the following definitions: +

+
Anonymous TD
@@ -255,7 +266,11 @@

Terminology

should not directly provide metadata, and in general are designed to be open. -
Thing Description Directory (TDD) +
TDD +
+
Short for Thing Description Directory. +
+
Thing Description Directory
A directory service with a prescribed API that allows the registration, management, and search of a database of Thing Descriptions. @@ -289,12 +304,18 @@

Introduction Mechanisms

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.

+

+ The following sub-sections define assertions without + using the `rfc2119-assertion` class. +

+

Direct

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. @@ -308,8 +329,8 @@

Well-Known URIs

into the following path: /.well-known/wot-thing-description.

- When the HTTP GET access is made to the above path, the HTTP server MUST return - a Thing Description with the content-type set to application/td+json. + When a request is made at the above path, the server MUST return + a Thing Description as prescribed in [[[#exploration-self]]].

The service name in Well-Known URI (wot-thing-description) is tentative. @@ -512,9 +533,61 @@

Exploration Mechanisms

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. + 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 + as prescribed in [[[#exploration-directory]]].

+ + The self-description using the following protocols must be according + to the given specification: +
+
HTTP
+
+

+ + The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS). + + + The HTTP server MUST serve the TD with a `GET` method. + + + A successful response MUST have 200 (OK) status, contain `application/td+json` + Content-Type header, and the TD in body. + + + 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. + + + The server SHOULD serve the requests after performing necessary + authentication and authorization. + +

+ +

+ Error responses: +

    +
  • + 401 (Unauthorized): No authentication. +
  • +
  • + 403 (Forbidden): Insufficient rights to the resource. +
  • +
+

+
+
+