From ae44ffecf5fcfbdabaa4c5292d9af82adf8e54e7 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Sat, 6 Feb 2021 20:29:10 +0100 Subject: [PATCH 1/4] add self-description spec --- index.html | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 4424c862..340d6914 100644 --- a/index.html +++ b/index.html @@ -512,8 +512,38 @@

Exploration Mechanisms

Self-description

-

+ + Self-describing devices are those which serve a Thing Description + and expose it at a URL. The URL may be advertised via one of the + [[[#introduction-mech]]] or a [[[#exploration-directory]]]. + +

+ + A self-describing device MUST expose its TD over HTTPS (HTTP Over TLS) + via an HTTP `GET` method. + + + A successful response MUST have 200 (OK) status, contain `application/td+json` + Content-Type header, and the TD in body. + + + The server SHOULD serve the requests after performing necessary + authentication and authorization. + +

+ +

+ Error responses: +

From 9c5bec608618fd181f3f338c899a4b57256ac400 Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Sun, 7 Feb 2021 16:20:25 +0100 Subject: [PATCH 2/4] add fundamental terminology, separate tdd acronym --- index.html | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 340d6914..3dd52096 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. From 4088a1de5f8c172aada175e03e267d82ba5583cf Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Sun, 7 Feb 2021 16:21:11 +0100 Subject: [PATCH 3/4] extend self-description, reference in introduction mechanisms --- index.html | 89 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 28 deletions(-) diff --git a/index.html b/index.html index 3dd52096..f3b139ed 100644 --- a/index.html +++ b/index.html @@ -304,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. @@ -323,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. @@ -530,36 +536,63 @@

Self-description

- Self-describing devices are those which serve a Thing Description - and expose it at a URL. The URL may be advertised via one of the - [[[#introduction-mech]]] or a [[[#exploration-directory]]]. -

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

- Error responses: -

    -
  • - 401 (Unauthorized): No authentication. -
    • -
  • - 403 (Forbidden): Insufficient rights to the resource. -
    • -
+ The self-description must use secure protocols guaranteeing + System User Data + authenticity and confidentiality (see [[?WOT-SECURITY]]).

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

+ + The HTTP-based self-description MUST 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. +
    • +
+

+
+
From 0ee7abcb632e3fc1c802f4ed643f3ab6e9e7d4bd Mon Sep 17 00:00:00 2001 From: Farshid Tavakolizadeh Date: Sun, 14 Feb 2021 17:27:13 +0100 Subject: [PATCH 4/4] remove external security reference, fix typo --- index.html | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index f3b139ed..658ae83b 100644 --- a/index.html +++ b/index.html @@ -540,18 +540,12 @@

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 + 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 must use secure protocols guaranteeing - System User Data - authenticity and confidentiality (see [[?WOT-SECURITY]]). -

- The self-description using the following protocols must be according to the given specification:
@@ -559,7 +553,7 @@

Self-description

- The HTTP-based self-description MUST be over HTTPS (HTTP Over TLS). + The HTTP-based self-description SHOULD be over HTTPS (HTTP Over TLS). The HTTP server MUST serve the TD with a `GET` method. @@ -593,6 +587,7 @@

Self-description

+