[#1332] incorporated feedback on WoT blogpost + documentation

* also replaced links to the spec to the now published "WoT TD W3C Working Draft 11 March 2022" to have an immutable version Signed-off-by: Thomas Jaeckle <thomas.jaeckle@bosch.io>
eclipse-ditto · Mar 11, 2022 · bed885c · bed885c
1 parent 33d8849
commit bed885c
Show file tree

Hide file tree

Showing 8 changed files with 62 additions and 55 deletions.
diff --git a/documentation/src/main/resources/_posts/2022-03-03-wot-integration.md b/documentation/src/main/resources/_posts/2022-03-03-wot-integration.md
@@ -13,6 +13,9 @@ toc: true
 The upcoming Eclipse Ditto **version 2.4.0** will add support for [W3C WoT (Web of Things)](https://www.w3.org/WoT/) 
 integration by referencing WoT Thing Model in Ditto managed twins describing the Things' capabilities.
 
+Using this integration, Ditto managed digital twins can be linked to WoT "Thing Models" from which Ditto can create 
+WoT "Thing Descriptions" containing the API descriptions of the twins.
+
 By integrating WoT, Ditto takes a big step forward towards:
 * increased interoperability
 * introspection of twins to find out their capabilities 
@@ -32,9 +35,9 @@ To learn more about WoT (Web of Things), please visit: [Web of Things in a Nutsh
 The WoT integration in Ditto covers several aspects:
 * referencing HTTP(s) URLs to WoT Thing Models in [Thing Definitions](basic-thing.html#definition) and in [Feature Definitions](basic-feature.html#feature-definition)
 * generation of WoT Thing Descriptions for Thing and Feature instances based on referenced Thing Models
-    * resolving potential [extensions via `tm:extends` and imports via `tm:ref`](https://www.w3.org/TR/wot-thing-description11/#thing-model-extension-import)
-    * resolving potential Thing level [compositions via `tm:submodel`](https://www.w3.org/TR/wot-thing-description11/#thing-model-composition)
-    * resolving potential [TM placeholders](https://www.w3.org/TR/wot-thing-description11/#thing-model-td-placeholder)
+    * resolving potential [extensions via `tm:extends` and imports via `tm:ref`](https://www.w3.org/TR/2022/WD-wot-thing-description11-20220311/#thing-model-extension-import)
+    * resolving potential Thing level [compositions via `tm:submodel`](https://www.w3.org/TR/2022/WD-wot-thing-description11-20220311/#thing-model-composition)
+    * resolving potential [TM placeholders](https://www.w3.org/TR/2022/WD-wot-thing-description11-20220311/#thing-model-td-placeholder)
 * upon creation of new Things, generation of a "JSON skeleton" following the WoT Thing Model, including referenced 
   TM submodels as Features of the Thing
 
@@ -53,10 +56,10 @@ For a full example of the different aspects of the WoT integration, please check
 [WoT integration example](basic-wot-integration-example.html).
 
 To summarize:
-* "link" a Thing with a public available WoT Thing Model by specifying the URL in its [Thing Definition](basic-thing.html#definition).
+* "link" a Thing with a publicly available WoT Thing Model by specifying the URL in its [Thing Definition](basic-thing.html#definition).
 * creation of a new Thing can use a Thing Model (e.g. the example model [https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld](https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld)) in order to generate a JSON skeleton:
     ```bash
-    curl --location --request PUT -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
+    curl --location --request PUT -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "definition": "https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld"
@@ -164,12 +167,12 @@ To summarize:
   the existing endpoint<br/>
   `GET /api/2/things/<thingId>` with the `Accept` header `application/td+json`:
   ```bash
-  curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
+  curl --location --request GET -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
   --header 'Accept: application/td+json'
   ```
 * Features of Things are handled as WoT "submodels" and also can describe themselves with the same approach, e.g.: 
   ```bash
-  curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1' \
+  curl --location --request GET -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1' \
   --header 'Accept: application/td+json'
   ```
 

diff --git a/documentation/src/main/resources/pages/ditto/basic-feature.md b/documentation/src/main/resources/pages/ditto/basic-feature.md
@@ -216,8 +216,8 @@ The capabilities or behavior of this "lamp" feature would be defined as [message
 ### The link to W3C WoT (Web of Things)
 
 If a [feature definition](#feature-definition) has the form of an HTTP(s) URL, this URL pointing to a resource may be
-interpreted as the link to a [W3C WoT (Web of Things)](https://www.w3.org/TR/wot-thing-description11/) 
-[Thing Model](https://www.w3.org/TR/wot-thing-description11/#thing-model) in [JSON-LD](https://www.w3.org/TR/json-ld11/) 
+interpreted as the link to a [W3C WoT (Web of Things)](https://www.w3.org/TR/2022/WD-wot-thing-description11-20220311/) 
+[Thing Model](https://www.w3.org/TR/2022/WD-wot-thing-description11-20220311/#thing-model) in [JSON-LD](https://www.w3.org/TR/json-ld11/) 
 format.
 
 For a detailed explanation how WoT and its concepts link to Ditto, please have a look at the 

diff --git a/documentation/src/main/resources/pages/ditto/basic-wot-integration-example.md b/documentation/src/main/resources/pages/ditto/basic-wot-integration-example.md
@@ -50,7 +50,7 @@ To create a Thing (instance) and create the Thing JSON skeleton following the Wo
 a Thing via the Ditto HTTP API (e.g. `PUT /api/2/things/<thingId>`):
 
 ```bash
-curl --location --request PUT -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
+curl --location --request PUT -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
 --header 'Content-Type: application/json' \
 --data-raw '{
     "definition": "https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld"
@@ -168,7 +168,7 @@ You see that:
 The Thing we just created can now be asked for its capabilities / interaction affordances by sending the following request:
 
 ```bash
-curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
+curl --location --request GET -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
 --header 'Accept: application/td+json'
 ```
 
@@ -189,7 +189,7 @@ That should result in an HTTP status code `200` (OK) and return the following bo
     "instance": "1.0.0"
   },
   "id": "urn:io.eclipseprojects.ditto:floor-lamp-0815",
-  "base": "http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815",
+  "base": "https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815",
   "links": [
     {
       "rel": "type",
@@ -531,7 +531,7 @@ You see that:
 In order to inspect which capabilities / interaction affordances now a Feature provides, simply perform such a query:
 
 ```bash
-curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1' \
+curl --location --request GET -u ditto:ditto 'https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1' \
 --header 'Accept: application/td+json'
 ```
 
@@ -550,11 +550,11 @@ That should result in an HTTP status code `200` (OK) and return the following bo
     "instance": "1.0.0"
   },
   "id": "urn:io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1",
-  "base": "http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1",
+  "base": "https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1",
   "links": [
     {
       "rel": "collection",
-      "href": "http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815",
+      "href": "https://ditto.eclipseprojects.io/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815",
       "type": "application/td+json"
     },
     {