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]

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?

[thjaeckle]

@thomas-fries-keen thanks for picking this back up! Agreement on all three points, with one refinement:

readallproperties: agreed — it returns only properties, never desiredProperties. It's a read op, and desired & reported are the same property (there's also no native WoT readalldesiredproperties to map to).

The extension: let's go with ditto:desired, but as a JSON object rather than a boolean — future-proof (add fields without a breaking value-type change) and consistent with our latest extension, ditto:deprecationNotice, which is already object-valued.

readOnly/writeOnly: instead of a separate ditto:useDesired flag, fold desired-side access control into the object. The standard readOnly/writeOnly describe the reported side and typically invert for the desired one (a read-only reported sensor value has a writable desired target), so keeping them independent is cleaner:

"roomTemperature": {
  "type": "number",
  "readOnly": true,                 // reported: device writes, consumer reads
  "ditto:category": "configuration",
  "ditto:desired": {
    "enabled": true,                // optional; presence already implies "desired"
    "readOnly": false,              // desired: consumer may read the target back
    "writeOnly": false              // desired: consumer sets the target
  }
}

TD generation then yields both affordances from one property entry — no desired_ naming hacks:

/features/<f>/properties/configuration/roomTemperature          -> GET (+ observe)
/features/<f>/desiredProperties/configuration/roomTemperature   -> GET + PUT/PATCH (+ observe)

For a first iteration I'd keep it minimal: a desired property always shadows a reported one (no "desired-only" mode), and desired properties are never in readallproperties. Skeleton generation on thing creation would not emit desired values by default — I don't think that's the common case — but we could make it optionally configurable later.

wdyt?

[sebastiankb]

the "ditto:desired" sounds a good solution here, however, I'm not sure if it needs to be as an object with a nested readOnly again, which could conflict with the one at the top level (may confuses the reader at least).

Btw., in building automation desired values are defined with setpoints:

"roomTemperature": {
  "type": "number",
  "readOnly": true
},
"roomTemperatureSetpoint": {
  "type": "number",
  "readOnly": false
}

[thomas-fries-keen]

Agree with @sebastiankb : I would not repeat readOnly in the nested ditto:desired object, because it could be redundant and inconsistent?

"roomTemperature": {
  "type": "number",
  "readOnly": false,
}

results in:

/features/<f>/properties/configuration/roomTemperature          -> GET + PUT/PATCH (+ observe)

"roomTemperature": {
  "type": "number",
  "readOnly": false,
  "ditto:desired": {
    "enabled": true,                // optional; presence already implies "desired"
  }
}

results in:

/features/<f>/properties/configuration/roomTemperature          -> GET (+ observe)
/features/<f>/desiredProperties/configuration/roomTemperature   -> GET + PUT/PATCH (+ observe)

If readOnly=false then PUT/PATCH is not allowed

Your first iteration scope sounds good to me, too.

[thomas-fries-keen]

@thjaeckle: There is another topic I would like to discuss:

Not sure if ditto:category was intended to separate status and configuration only. But for me it would be helpful to use it as a flexible way to navigate in the thing json to a WoT property. So:

• use ditto:category=myGroupOfProperties (already works I think)
• use ditto:category=groupLevel1/groupLevel2 (not tried yet)
• use for attributes also: In case of a property of a thing it would be also nice if insert ditto:category as a path to the ditto attribute

So kind of a ditto:path. But ditto:category is ok, if it just allows nesting and can also be used for attributes (I even saw copilot searching for a ditto:path extension to solve "my problem")