Integrating W3C WoT and Eclipse Ditto

[thjaeckle]

We would like to start a discussion about how Web of Things and Ditto could play together / be integrated, etc.
The Ditto project is already in contact with W3C WoT, e.g. providing feedback regarding the use of composition in the new "Thing Model" here: w3c/wot-thing-description#1177

I'd like to copy a table already created in another Ditto issue #1034 as a starting point on how to map WoT to Ditto concepts:

WoT concept	Ditto concept
Properties	Feature properties + Feature desired properties
Actions	Feature "inbox" (TO the thing) messages
Events	Feature "outbox" (FROM the thing) messages

Thing level

An idea is currently to allow in the definition of a Ditto thing - which is currently limited to the format <namespace>:<name>:<version> to also allow inserting an URL.
This way an URL to a WoT Thing Model could be inserted.
Once w3c/wot-thing-description#1177 is added to the WoT TM specification, the TM can also include "subcomponents" which would map to Ditto features.

Feature level

The definition of a Ditto feature (belonging to a thing) is currently also limited to being an array of string in the format <namespace>:<name>:<version>.
As one Ditto feature maps really good to a WoT Thing Model / Thing Description, we could also allow putting URLs in that array as well which would define:
This feature follows the WoT "contract" defined by all referenced links to "Thing Models".

Outlook: Creation of Thing Definitions

Ditto could use the links to "Thing Models" in the thing definition and feature definition in order to:

• fetch the referenced "Thing Model" via HTTP
• cache/persist it
• automatically generate,cache and provide a "Thing Description" for each Ditto thing:
  • containing all retrievable/settable TD properties and their schema
    • the TD "forms" contain the HTTP URL to the actual property (e.g. a GET /api/2/things/my.namespace:my-thing-name/features/temperature/properties/value)
  • containing all invokable TD actions and their schema
    • the TD "forms" contain the HTTP URL to the invokable action (e.g. a POST /api/2/things/my.namespace:my-thing-name/features/temperature/inbox/messages/resetMinMax)
  • containing all emitted TD events and their schema
• returning that Thing Description e.g. by defining the "Accept" header application/td+json in a request for retrieving a thing:
  • GET /api/2/things/my.namespace:my-thing-name with header: Accept: application/td+json would return the WoT Thing Description of the complete thing (all properties / actions / events)

---

So much for our current ideas about how to integrate WoT and Ditto.
Sharing of any ideas / requirements / feedback on that would be highly appreciated as we are still in a "brainstorming" phase.

[thjaeckle]

Pinging/inviting @sebastiankb from WoT to also join on this discussion 😀

[sebastiankb]

A great idea :-)

I think a good starting point would be to use a simple example in Ditto, such as a temperature sensor, a switch, and/or a lamp thing. Let's define this as a Ditto Thing and derive the equivalent as a TM then.

@thjaeckle can you prepare such an example? Then I can support with the TM definition.

[tobias-zeptio]

Would this work include having a WoT payload mapper?

[thjaeckle]

Could you point me to a link to the WoT spec defining a WoT payload mapper? Don't know that concept, to be honest.

[tobias-zeptio]

I would assume there isn't one, that's why I asked. :) Right now we are working with a custom message format into ditto, so have to do payload mapping. But if we were to use wot, the format would be specified and a general mapper could be used.

[thjaeckle]

As far as I understood WoT, there is nothing like a WoT defined "payload" for devices.
There is the "Thing Description" which defines (using JSON-LD and a subset of JsonSchema) what the JSON of a "Thing" (and the actions/events the Thing accepts/emits) looks like - so this should already match to Ditto's payload if the "Thing Description" is defined correctly.

[thjaeckle]

@sebastiankb good idea with the example, I'll add it to the "main" thread here.

Example

We want to model a simple Ditto "Thing" with "Features" and add a WoT "Thing Model" (and I assume also a TD) for that afterwards.

Ditto Thing

{
  "thingId": "org.eclipse.ditto.example:smart-motion-detector",
  "policyId": "org.eclipse.ditto.example:smart-motion-detector-policy",
  "definition": "https://ditto.eclipseprojects.io/example-models/MotionDetector.tm.jsonld",
  "attributes": {
    "manufacturer": "ACME Inc",
    "serialNumber": "837499231"
  },
  "features": {
    "motion-detection": {
      "definition": [
        "https://ditto.eclipseprojects.io/example-models/MotionDetection.tm.jsonld",
        "https://ditto.eclipseprojects.io/example-models/Switch.tm.jsonld"
      ],
      "properties": {
        "on": true,
        "detection-sensitivity": 44.3,
        "last-detection-time": "2021-09-07T09:38:43Z"
      }
    },
    "environment-sensor": {
      "definition": [
        "https://ditto.eclipseprojects.io/example-models/TemperatureWithHumidity.tm.jsonld"
      ],
      "properties": {
        "temperature": 23.4,
        "humidity": 54
      }
    },
    "status-led": {
      "definition": [
        "https://ditto.eclipseprojects.io/example-models/Light.tm.jsonld",
        "https://ditto.eclipseprojects.io/example-models/Switch.tm.jsonld"
      ],
      "properties": {
        "on": true,
        "color": {
          "red": 255,
          "green": 0,
          "blue": 0
        }
      }
    }
  }
}

Features and their supported messages

Ditto features can receive and emit messages. Receiving messages can be defined using WoT "actions" and emitting events with WoT "events".
For the example, let's assume that the features support the following messages:

• motion-detection
  • inbox message (aka. "action"): pause-detection
    • description: temporarily pauses the motion detection for a given time interval
    • payload:

    {
      "amount": 1,
      "unit": "h"
    }

  • outbox message (aka. "event"): motion-detected
    • description: emitted when a motion was detected including the detection time in ISO-8601
    • payload:

    "2021-09-07T09:38:43Z"

• status-led
  • inbox message (aka. "action"): toggle
    • description: switches the led off when it's on and vice versa
    • payload: none

[thjaeckle]

I just had an exchange with @sebastiankb from WoT regarding the Thing Models for that example and that's a current first rough idea:

Top level TM "Motion Detector"

expand to open Thing Model

{
  "@context": [
    "http://www.w3.org/ns/td",
    {"ditto": "https://ditto.eclipseprojects.io"}
  ],
  "@type": "tm:ThingModel",
  "title": "Motion Detector",
  "version" : { "model" : "1.0.0" },
  "links": [
    {
      "rel": "tm:submodel",
      "href": "https://ditto.eclipseprojects.io/example-models/MotionDetection.tm.jsonld",
      "type": "application/tm+json",
      "instanceName": "motion-detection"
    },
    {
      "rel": "tm:submodel",
      "href": "https://ditto.eclipseprojects.io/example-models/TemperatureWithHumidity.tm.jsonld",
      "type": "application/tm+json",
      "instanceName": "environment-sensor"
    },
    {
      "rel": "tm:submodel",
      "href": "https://ditto.eclipseprojects.io/example-models/Light.tm.jsonld",
      "type": "application/tm+json",
      "instanceName": "detection-led"
    }
  ],
  "base": "{{ DITTO_HTTP_ENDPOINT }}/api/2/things/{{ DITTO_THING_ID }}",
  "ditto:thingId": "{{ DITTO_THING_ID }}",
  "properties": {
    "policyId": {
      "type": "string",
      "description":  "Reference to a policy containing the authorization information for accessing the thing"
    },
    "attributes": {
      "type": "object",
      "properties": {
        "manufacturer": {
          "type": "string",
          "description": "The manufacturing company"
        },
        "serialNumber": {
          "type": "string",
          "description": "The unique serial number of the device"
        }
      }
    }
  }
}

Sub TM "MotionDetection"

expand to open Thing Model

{
  "@context": "http://www.w3.org/ns/td",
  "@type": "tm:ThingModel",
  "title": "Motion Detection",
  "version" : { "model" : "1.0.0" },
  "links": [{
      "rel": "tm:extends",
      "href": "https://ditto.eclipseprojects.io/example-models/Switch.tm.jsonld",
      "type": "application/tm+json"
  }],
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "detection-sensitivity": {
          "type": "double",
          "minimum": 0.0,
          "maximum": 100.0,
          "description": "The sensitivity of the motion detection"
        },
        "last-detection-time": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp of the last detected motion"
        }
      }
    }
  },
  "actions": {
    "pause-detection": {
      "description": "Pauses the motion detection for a specified time",
      "input": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "ms",
              "s",
              "m",
              "h",
              "d"
            ],
            "description": "The temporal unit"
          }
        }
      }
    }
  },
  "events": {
    "motion-detected": {
      "description":  "Event emitted when a motion was detected",
      "data": {
        "type": "string",
        "format": "date-time",
        "description": "The current timestamp"
      }
    }
  }
}

TM "Switch"

expand to open Thing Model

{
  "@context": "http://www.w3.org/ns/td",
  "@type": "tm:ThingModel",
  "title": "Switch",
  "version" : { "model" : "1.0.0" },
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "on": {
          "type": "boolean",
          "description": "Whether the switch is tuned on or off"
        }
      }
    }
  }
}

Sub TM "TemperatureWithHumidity"

expand to open Thing Model

{
  "@context": [
    "http://www.w3.org/ns/td",
    { "om": "http://www.ontology-of-units-of-measure.org/resource/om-2/" }
  ],
  "@type": "tm:ThingModel",
  "title": "Temperature with Humidity",
  "version" : { "model" : "1.0.0" },
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "temperature": {
          "type": "double",
          "description": "The measured temperature",
          "unit": "om:degreeCelsius"
        },
        "humidity": {
          "type": "double",
          "description": "The measured humidity",
          "minimum": 0.0,
          "maximum": 100.0,
          "unit": "om:percent"
        }
      }
    }
  }
}

Sub TM "Light"

expand to open Thing Model

{
  "@context": "http://www.w3.org/ns/td",
  "@type": "tm:ThingModel",
  "title": "Light",
  "version" : { "model" : "1.0.0" },
  "links": [{
      "rel": "tm:extends",
      "href": "https://ditto.eclipseprojects.io/example-models/Switch.tm.jsonld",
      "type": "application/tm+json"
  }],
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "color": {
          "type": "object",
          "description": "The color of the lamp in RGB",
          "properties": {
            "r": {
              "type": "integer",
              "minimum": 0,
              "maximum": 255,
              "description": "The red amount"
            },
            "g": {
              "type": "integer",
              "minimum": 0,
              "maximum": 255,
              "description": "The green amount"
            },
            "b": {
              "type": "integer",
              "minimum": 0,
              "maximum": 255,
              "description": "The blue amount"
            }
          }
        }
      }
    }
  },
  "actions": {
    "toggle": {
      "description": "Toggles the current 'on' state of Switch"
    }
  }
}

@sebastiankb what do you think? Is this heading in the right direction?

[sebastiankb]

Yes, this looks quite good. It is cool that you also use the semantic context extension to link common units of measurements.

As already discussed, the properties defined at the top level of the TM can also be defined at the root level with placeholders for instantiations. In this approach, however, these properties are not represented as separate resources.

Just small bug fixes in Sub TM "TemperatureWithHumidity": min --> minimum and max --> maximum

Now, my job is to include the subModel concept in the Thing Description specification. A first draft should be available end of this month. The PR for this work can be found here.

[thjaeckle]

@sebastiankb I was thinking about how the TD could look like based on the given TM examples from above.
What is not quite clear yet to me (and also was raised as question in your PR w3c/wot-thing-description#1207 (comment) ) is how the linked "subthings" would be merged into the toplevel TD.

I think that the example Thing Models from above could look like the following Thing Descriptions for a concrete Ditto managed Thing:

expand to open Thing Description

{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {"ditto": "https://ditto.eclipseprojects.io"}
  ],
  "title": "Motion Detector Thing Description",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": [
    "nosec_sc"
  ],
  "base": "https://ditto.eclipseprojects.io/api/2/things/org.eclipse.ditto:my-motion-detector-1",
  "ditto:thingId": "org.eclipse.ditto:my-motion-detector-1",
  "properties": {
    "policyId": {
      "type": "string",
      "description": "Reference to a policy containing the authorization information for accessing the thing",
      "forms": [
        {
          "op": "readproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "attributes": {
      "type": "object",
      "properties": {
        "manufacturer": {
          "type": "string",
          "description": "The manufacturing company",
          "forms": [
            {
              "op": "readproperty",
              "href": "/attributes/manufacturer",
              "contentType": "application/json",
              "htv:methodName": "GET"
            },
            {
              "op": "writeproperty",
              "href": "/attributes/manufacturer",
              "contentType": "application/json",
              "htv:methodName": "PUT"
            }
          ]
        },
        "serialNumber": {
          "type": "string",
          "description": "The unique serial number of the device",
          "forms": [
            {
              "op": "readproperty",
              "href": "/attributes/serialNumber",
              "contentType": "application/json",
              "htv:methodName": "GET"
            },
            {
              "op": "writeproperty",
              "href": "/attributes/serialNumber",
              "contentType": "application/json",
              "htv:methodName": "PUT"
            }
          ]
        }
      },
      "forms": [
        {
          "op": "readproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection:on": {
      "type": "boolean",
      "description": "Whether the switch is tuned on or off",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/on",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/on",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection:detection-sensitivity": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 100.0,
      "description": "The sensitivity of the motion detection",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/detection-sensitivity",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/detection-sensitivity",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection:last-detection-time": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of the last detected motion",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/last-detection-time",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/last-detection-time",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "environment-sensor:temperature": {},
    "environment-sensor:humidity": {},
    "detection-led:on": {},
    "detection-led:color": {}
  },
  "actions": {
    "motion-detection:pause-detection": {
      "description": "Pauses the motion detection for a specified time",
      "input": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "ms",
              "s",
              "m",
              "h",
              "d"
            ],
            "description": "The temporal unit"
          }
        }
      },
      "forms": [
        {
          "op": "invokeaction",
          "href": "/features/motion-detection/messages/inbox/pause-detection",
          "htv:methodName": "POST"
        }
      ]
    },
    "detection-led:toggle": {}
  },
  "events": {
    "motion-detection:motion-detected": {
      "description": "Event emitted when a motion was detected",
      "data": {
        "type": "string",
        "format": "date-time",
        "description": "The current timestamp"
      },
      "forms": [
        {
          "op": "subscribeevent",
          "href": "/features/motion-detection/messages/outbox/pause-detection",
          "htv:methodName": "GET",
          "contentType": "text/event-stream",
          "subprotocol": "sse"
        }
      ]
    }
  }
}

In that example, all properties/actions/events from the linked "subthings" would be flattened into the TD and would get a prefix of the "instanceName" provided in the link followed by e.g. a colon :

Does this make sense?

[sebastiankb]

This is an option, which a TM to TD generator can provide you when you prefer a self-contained single TD. However, the default approach would be of keeping the hierarchy representation in the Thing Descriptions. That means you can use the link container and refer to your sub-things in the same way as you know it from the TM definition:

See Top level TD "Motion Detector"

{
 "@context": [
   "https://www.w3.org/2019/wot/td/v1",
   {"ditto": "https://ditto.eclipseprojects.io"}
 ],
 "title": "Motion Detector Thing Description",
 "securityDefinitions": {
   "nosec_sc": {
     "scheme": "nosec"
   }
 },
 "security": [
   "nosec_sc"
 ],
 "links": [{
     "rel": "item",
     "href": "path/to/MotionDetection.td.json",
     "type": "application/td+json"
 },
 {
     "rel": "item",
     "href": "path/to/Switch.td.json",
     "type": "application/td+json"
 },
 {
     "rel": "item",
     "href": "path/to/TemperatureWithHumidity.td.json",
     "type": "application/td+json"
 }
 ,
 {
     "rel": "item",
     "href": "path/to/Light.td.json",
     "type": "application/td+json"
 }  
 ],
 "base": "https://ditto.eclipseprojects.io/api/2/things/org.eclipse.ditto:my-motion-detector-1",
 "ditto:thingId": "org.eclipse.ditto:my-motion-detector-1",
 "properties": {
   "policyId": {
     "type": "string",
     "description": "Reference to a policy containing the authorization information for accessing the thing",
     "forms": [
       {
         "op": "readproperty",
         "href": "/policyId",
         "contentType": "application/json",
         "htv:methodName": "GET"
       },
       {
         "op": "writeproperty",
         "href": "/policyId",
         "contentType": "application/json",
         "htv:methodName": "PUT"
       }
     ]
   },
   "attributes": {
     "type": "object",
     "properties": {
       "manufacturer": {
         "type": "string",
         "description": "The manufacturing company",
         "forms": [
           {
             "op": "readproperty",
             "href": "/attributes/manufacturer",
             "contentType": "application/json",
             "htv:methodName": "GET"
           },
           {
             "op": "writeproperty",
             "href": "/attributes/manufacturer",
             "contentType": "application/json",
             "htv:methodName": "PUT"
           }
         ]
       },
       "serialNumber": {
         "type": "string",
         "description": "The unique serial number of the device",
         "forms": [
           {
             "op": "readproperty",
             "href": "/attributes/serialNumber",
             "contentType": "application/json",
             "htv:methodName": "GET"
           },
           {
             "op": "writeproperty",
             "href": "/attributes/serialNumber",
             "contentType": "application/json",
             "htv:methodName": "PUT"
           }
         ]
       }
     },
     "forms": [
       {
         "op": "readproperty",
         "href": "/attributes",
         "contentType": "application/json",
         "htv:methodName": "GET"
       },
       {
         "op": "writeproperty",
         "href": "/attributes",
         "contentType": "application/json",
         "htv:methodName": "PUT"
       }
     ]
   }
}}

We would use item as the relation type here, since it is already registered by IANA.

[thjaeckle]

Based on the input @sebastiankb provided, for Ditto it would make sense to provide 2 options (maybe even both) for "TD generation":

1. Each Thing provides a TD and links to TDs provided by features

E.g. HTTP resource /api/2/things/org.eclipse.ditto:my-motion-detector-1 provides:

• GET /api/2/things/org.eclipse.ditto:my-motion-detector-1 with HTTP header: Accept: application/td+json
  • this resource returns a generated TD based on the TM contained in the "definition" of the Thing
  • all "tm:submodel" linked submodels in the TD are links to TD provided by the features of the Thing
  • the toplevel TD contains links with "rel": "item" to the TDs provided by the features
• GET /api/2/things/org.eclipse.ditto:my-motion-detector-1/features/motion-detection with HTTP header: Accept: application/td+json
  • this resource returns a generated TD based on the TM contained in the "definition" of the Feature motion-detection
  • the toplevel TD is added to the "links" with "rel": "container"
• GET /api/2/things/org.eclipse.ditto:my-motion-detector-1/features/environment-sensor with HTTP header: Accept: application/td+json
  • this resource returns a generated TD based on the TM contained in the "definition" of the Feature environment-sensor
  • the toplevel TD is added to the "links" with "rel": "container"
• GET /api/2/things/org.eclipse.ditto:my-motion-detector-1/features/detection-led with HTTP header: Accept: application/td+json
  • this resource returns a generated TD based on the TM contained in the "definition" of the Feature status-led
  • the toplevel TD is added to the "links" with "rel": "container"

Example Thing level TD

{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {"ditto": "https://ditto.eclipseprojects.io"}
  ],
  "title": "Motion Detector Thing Description",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": [
    "nosec_sc"
  ],
  "base": "https://ditto.eclipseprojects.io/api/2/things/org.eclipse.ditto:my-motion-detector-1",
  "ditto:thingId": "org.eclipse.ditto:my-motion-detector-1",
  "links": [
     {
       "rel": "item",
       "href": "./features/motion-detection",
       "type": "application/td+json"
     },
     {
       "rel": "item",
       "href": "./features/environment-scanner",
       "type": "application/td+json"
     },
     {
       "rel": "item",
       "href": "./features/detection-led",
       "type": "application/td+json"
     }
  ],
  "properties": {
    "policyId": {
      "type": "string",
      "description": "Reference to a policy containing the authorization information for accessing the thing",
      "forms": [
        {
          "op": "readproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "attributes": {
      "type": "object",
      "properties": {
        "manufacturer": {
          "type": "string",
          "description": "The manufacturing company"
        },
        "serialNumber": {
          "type": "string",
          "description": "The unique serial number of the device"
        }
      },
      "forms": [
        {
          "op": "readproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    }
  }
}

Example feature level TD

{
  "@context": "http://www.w3.org/ns/td",
  "@type": "Thing",
  "title": "Motion Detection instance",
  "links": [{
      "rel": "container",
      "href": "../../",
      "type": "application/td+json"
  }],
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "on": {
          "type": "boolean",
          "description": "Whether the switch is tuned on or off"
        },
        "detection-sensitivity": {
          "type": "double",
          "minimum": 0.0,
          "maximum": 100.0,
          "description": "The sensitivity of the motion detection"
        },
        "last-detection-time": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp of the last detected motion"
        }
      }
    },
    "forms": [
      {
        "op": "readproperty",
        "href": "/properties",
        "contentType": "application/json",
        "htv:methodName": "GET"
      },
      {
        "op": "writeproperty",
        "href": "/properties",
        "contentType": "application/json",
        "htv:methodName": "PUT"
      }
    ]
  },
  "actions": {
    "pause-detection": {
      "description": "Pauses the motion detection for a specified time",
      "input": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "ms",
              "s",
              "m",
              "h",
              "d"
            ],
            "description": "The temporal unit"
          }
        }
      }
    },
    "forms": [
      {
        "op": "invokeaction",
        "href": "./messages/inbox/pause-detection",
        "htv:methodName": "POST"
      }
    ]
  },
  "events": {
    "motion-detected": {
      "description":  "Event emitted when a motion was detected",
      "data": {
        "type": "string",
        "format": "date-time",
        "description": "The current timestamp"
      }
    },
    "forms": [
      {
        "op": "subscribeevent",
        "href": "./messages/outbox/motion-detected",
        "htv:methodName": "GET",
        "contentType": "text/event-stream",
        "subprotocol": "sse"
      }
    ]
  }
}

Benefits of this approach:

• the "default" way to do it
• each feature is addressable by itself in Ditto as subresource of a Thing, so it makes sense to have also a self-contained TD for a specific feature only
• separation of concerns/aspects

2. The Thing provides a single TD in which all contained "tm:submodel" TDs are merged into

E.g. HTTP resource /api/2/things/org.eclipse.ditto:my-motion-detector-1 provides:

• GET /api/2/things/org.eclipse.ditto:my-motion-detector-1 with HTTP header: Accept: application/td+json
  • this resource returns a generated TD based on the TM contained in the "definition" of the Thing and of all contained features, inlining all TDs into this single provided TD

Example Thing level inlining/"super" TD

{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {"ditto": "https://ditto.eclipseprojects.io"}
  ],
  "title": "Motion Detector Thing Description",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": [
    "nosec_sc"
  ],
  "base": "https://ditto.eclipseprojects.io/api/2/things/org.eclipse.ditto:my-motion-detector-1",
  "ditto:thingId": "org.eclipse.ditto:my-motion-detector-1",
  "properties": {
    "policyId": {
      "type": "string",
      "description": "Reference to a policy containing the authorization information for accessing the thing",
      "forms": [
        {
          "op": "readproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/policyId",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "attributes": {
      "type": "object",
      "properties": {
        "manufacturer": {
          "type": "string",
          "description": "The manufacturing company"
        },
        "serialNumber": {
          "type": "string",
          "description": "The unique serial number of the device"
        }
      },
      "forms": [
        {
          "op": "readproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/attributes",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection_on": {
      "type": "boolean",
      "description": "Whether the switch is tuned on or off",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/on",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/on",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection_detection-sensitivity": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 100.0,
      "description": "The sensitivity of the motion detection",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/detection-sensitivity",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/detection-sensitivity",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "motion-detection_last-detection-time": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of the last detected motion",
      "forms": [
        {
          "op": "readproperty",
          "href": "/features/motion-detection/properties/last-detection-time",
          "contentType": "application/json",
          "htv:methodName": "GET"
        },
        {
          "op": "writeproperty",
          "href": "/features/motion-detection/properties/last-detection-time",
          "contentType": "application/json",
          "htv:methodName": "PUT"
        }
      ]
    },
    "environment-sensor_temperature": {...},
    "environment-sensor_humidity": {...},
    "detection-led_on": {...},
    "detection-led_color": {...}
  },
  "actions": {
    "motion-detection_pause-detection": {
      "description": "Pauses the motion detection for a specified time",
      "input": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "ms",
              "s",
              "m",
              "h",
              "d"
            ],
            "description": "The temporal unit"
          }
        }
      },
      "forms": [
        {
          "op": "invokeaction",
          "href": "/features/motion-detection/messages/inbox/pause-detection",
          "htv:methodName": "POST"
        }
      ]
    },
    "detection-led_toggle": {...}
  },
  "events": {
    "motion-detection_motion-detected": {
      "description": "Event emitted when a motion was detected",
      "data": {
        "type": "string",
        "format": "date-time",
        "description": "The current timestamp"
      },
      "forms": [
        {
          "op": "subscribeevent",
          "href": "/features/motion-detection/messages/outbox/pause-detection",
          "htv:methodName": "GET",
          "contentType": "text/event-stream",
          "subprotocol": "sse"
        }
      ]
    }
  }
}

Benefits of this approach:

• a Ditto "Thing" TD contains all possible properties, actions, events in a single place, without the need to do other HTTP lookups of "sub" TDs

[LLLLimbo]

From the documentation, actions are used to define the functions that the device can call from the outside, but in some cases the direction is reversed, for example in our case the face recognition device needs to periodically call the interface of a service located in the cloud to synchronize the face data. (I didn't know WoT before, maybe I misunderstood.) In our current digital twin specification, we added direction to indicate the direction of invocation, as follows :

Expand for JSON example

"functions": [
    {
      "id": "getAuz",
      "name": "Pull permissions",
      "direction": 0,
      "inputData": [
        {
          "id": "currDate",
          "name": "current timestamp",
          "dataType": "long",
          "description": ""
        },
        {
          "id": "pid",
          "name": "batch",
          "dataType": "long",
          "description": ""
        }
      ],
      "outputData": [
        {
          "id": "clrLocal",
          "name": " clear the local data",
          "dataType": "bool",
          "description": ""
        },
        {
          "id": "pid",
          "name": "pid",
          "dataType": "long",
          "description": ""
        },
        {
          "id": "newTs",
          "name": "new timestamp",
          "dataType": "long",
          "description": ""
        },
        {
          "id": "auzData",
          "name": "permission data",
          "dataType": "array",
          "description": ""
        }
      ]
    },
    {
      "id": "getDevLog",
      "name": "get device log",
      "direction": 1,
      "inputData": [
        {
          "id": "startTs",
          "name": "start time",
          "dataType": "long",
          "description": ""
        },
        {
          "id": "endTs",
          "name": "end time",
          "dataType": "long",
          "description": ""
        }
      ],
      "outputData": [
        {
          "id": "logUrl",
          "name": "oss address",
          "dataType": "String",
          "description": ""
        },
        {
          "id": "startTs",
          "name": "start time",
          "dataType": "long",
          "description": ""
        },
        {
          "id": "endTs",
          "name": "end time",
          "dataType": "long",
          "description": ""
        }
      ]
    }
]

[sebastiankb]

For periodically data exchange WoT offers the events interaction affordance. Depending on the underlying protocol, events definitions are typically used to send data periodically to a specific location or to make subscriptions.

[sebastiankb]

just for information: the composition section is ready for review https://pr-preview.s3.amazonaws.com/w3c/wot-thing-description/pull/1207.html#thing-model-composition

[thjaeckle]

I'll have a look tomorrow, cool 👍

[thjaeckle]

I updated the example "thread" above with the latest changes made to the WoT TM composition: #1163 (reply in thread)

[thfries]

I did some first steps with the currently implemented support for WoT and it works well 👍. One question that came up:

Wouldn't it make sense to have a similar support to create a single Ditto feature from a TM like it is already possible for creating a Ditto thing? So that I can add a new "aspect" or "capability" to an existing arbitrary thing? Or even more important: to use the feature TM independent of the "containing" thing. Does that make sense?

[thjaeckle]

Hi @thfries

Thanks for the feedback. 👍
Yes, I understand - and also think that this would make sense - but only if creating a new feature which was not there before.
I would like to do an additional extension soon, integrating the "ditto:category" to WoT TM properties - then I can look into if the feature creation based on a TM also fits in.

[ThomasSchwarzBT-VS]

Hi @thjaeckle, do you already have an idea how to model desiredProperties in WoT TM? I didn't found any examples including desiredProperties yet. Thanks!

[thjaeckle]

Hi Thomas.
The idea behind desired properties is that they follow the same model as normal properties, however all desired properties are optional.

The current WoT integration in Ditto does not explicitly handle desired properties, eg when a new thing is created, no skeleton json for desired properties is created.
I think that is OK for the initial thing.

The other WoT TM based function, creating TDs could (and probably should) be enhanced to also describe desired properties.
However some things are not yet clear to me, eg WoT has an operation "readallproperties" which currently contains eg the link to GET /<thingId>/features/<featureId>/properties.
When desired properties would also be part of the TD describing a feature, they should strictly speaking also be contained in the "all properties".

As a user of the WoT integration: what would be your expectation?

[ThomasSchwarzBT-VS]

Thanks for the quick response. I'm just getting started with the WoT integration, so I'm not clear about my expectations yet. Maybe I can provide some snippets / ideas today or in cw 1.

[ThomasSchwarzBT-VS]

Ok, I don't think I have the whole picture yet, but I could imagine something like this. To my understanding, everything that is in "featureID/properties" is written by the device, so this must be readOnly from consumer point of view. Everything that is in "featureID/desiredProperties" is written by the consumer (e.g. Ditto / Cloud Backend), so this must be writeOnly from consumer point of view. But I don't know if this is realistic. What do you think?

{
    "@context": [
        "https://www.w3.org/2022/wot/td/v1.1",
        {
            "ditto": "https://ditto.eclipseprojects.io/wot/ditto-extension#",
        }
    ],
    "description": "writeOnly && category:configuration is mapped to desiredProperties/configuration, readOnly && category:configuration is mapped to properties/configuration, category:status is mapped to properties/status",
    "properties": {
        "someStateProperty": {
            "type": "string",
            "readOnly": true,
            "ditto:category": "status"
        },
        "someConfigProperty": {
            "type": "string",
            "writeOnly": true,  
            "ditto:category": "configuration"
        }
    }
}

[thjaeckle]

That would be problematic as desired properties have the same name as their reported ones.
E.g. think about the "roomTemperature" of a thermostat.. Would be available both as reported and desired porpery (the desired one as the configured target temperature).
One could of course work with a prefix/suffix of the WoT property name, indicating the difference of default/reported and desired property.
E.g.:

• "roomTemperature" (as read only true, with the "href" of the generated TD pointing to /<featureId>/properties/roomTemperature
• "desired_roomTemperature" of the generated TD with href pointing to /<featureId>/desiredProperties/roomTemperature

However, as this desired concept is not native to the WoT specification, these are always "hacks".

What also would be an option is to enhance the Ditto extension of WoT (already containing "ditto:category") with another category for properties (reported vs desired) in order to not only rely on naming conventions.

[thomas-fries-keen]

@thjaeckle, coming back to the "desiredProperties" discussion as we are back on WoT modelling:

• not sure if your question above was answered. My expectation would be: for readallproperties I would NOT expect to return the desiredProperties. As you pointed out: desired & reported refer to the same property. Also, as the operation is "read" I would only expect properties and not desiredProperties
• I agree to your final proposal to have another ditto-extension like ditto:desired with default false - would be a very flexible approach and would cause not much impact.
• Nonetheless a solution with the standard readOnly or writeOnly attributes would be also nice. E.g. if readOnly = false then just assume write operations to use desiredProperties instead of properties. But this would enforce use of desiredProperties which is rather just an option. So also here there would be need for a ditto extension to control the behaviour (e.g. ditto:useDesired = true AND readOnly=false leads to desiredProperties in the generated paths

wdyt?