Thing Description

From HandWiki
Thing Description
ThingDescription
The logo of the latest version, Thing Description
Filename extension.jsontd , .td.json , .td.jsonld
Internet media typeapplication/td+json
Developed byW3C
Initial releaseApril 9, 2020
Type of formatJSON-LD
StandardW3C Web of Things
Websitehttps://www.w3.org/TR/wot-thing-description/

The Thing Description (TD) (or W3C WoT Thing Description (TD)) is a royalty-free, open information model with a JSON based representation format for the Internet of Things (IoT). A TD provides a unified way to describe the capabilities of an IoT device or service with its offered data model and functions, protocol usage, and further metadata. Using Thing Descriptions help reduce the complexity of integrating IoT devices and their capabilities into IoT applications.[1]

The TD originated from the Web of Things (WoT) initiative of the international standards organization of the W3C which has the intention to increase the interoperability in the IoT.[2] Since April 2020, the Thing Description[3] is a W3C recommendation (W3C WoT Thing Description 1.0).

In December 2023, the W3C published 1.1 version of the Thing Description recommendation.[4]

Principles

The major principle of the Thing Description is to provide a human-readable and machine-interpretable interface description of an IoT device/Thing. In that context, the WoT Thing Description is to the IoT what index.html is to a website: it can be considered as the entry point of a physical or virtual Thing/device.[5] Thing Description are not limited to a specific communication protocol, rather it provides a framework called a WoT Binding Template.[6] Such a Protocol Binding defines the mapping from an Interaction Affordance to concrete messages of a specific IoT protocol such as MQTT, HTTP, CoAP, Modbus or OPC UA.

The WoT Thing Description defines 3 kinds of Interaction Affordances, named Property, Action and Event:

Property

An Interaction Affordance that exposes state of an IoT device. This state can then be retrieved (read) and optionally updated (write). Devices can also choose to make Properties observable by pushing the new state after a change.

Action

An Interaction Affordance that allows to invoke a function of an IoT device, which manipulates state (e.g., toggling a lamp on or off) or triggers a process on the device (e.g., dim a lamp over time).

Event

An Interaction Affordance that describes an event source, which asynchronously pushes event data to the subscribers of the event (e.g., overheating alerts).

Components and standard technologies

WoT Thing Description components: Context Extension Framework, Security Framework, Things Relation Definitions, WoT Interaction Model (containing Properties, Actions and Evens), Data Model, Binding Templates.
Figure 1. WoT Thing Description components.

In general, the Thing Description is designed to reuse and rely on established Internet and Web standards, this includes:

  • Serialization: The JSON serialization of the TD information model is aligned with the syntax of JSON-LD 1.1.[7] JSON-LD opens the opportunity of context extension and enrich the Thing Description instances with additional (e.g., domain-specific) semantics such as from Schema.org. This also supports the extraction and the understanding of relevant information such as in discovery scenarios in IoT applications[8]
  • Security: The Thing Description comes with a framework that allows to provide metadata to follow existing security scheme such as OAuth2 or Digest Access Authentication.[9] Due to the context extension concept of the Thing Description specific security schemes can be imported.
  • Linking: Things may have references to other Things or like to link to further information. For defining such kind of relations the Thing Description relies on the well know Web Linking[10] concept.
  • Interactions: The offered data and/or functions of a Thing are assigned to the corresponding interaction affordance Properties, Actions, and Events.
  • Data Schema: For modeling the Thing's data that can be exchanged, the concept of JSON schema[11] is embedded in the Thing Description.
  • Bindings: The binding templates define the specific protocol and serialization method for the properties, actions, and events of the Thing. As protocol identification and addressing method URI Identifier[12] are used. For announcing the serialization encoding (e.g., JSON, CBOR, XML, Efficient XML Interchange) of the payload that is specified by the data schema, Media Type[13] assignment is applied in the Thing Description.

Thing Description examples

Example of a Thing Description object.

Below is an example TD serialized in JSON-LD format, which has one property, one action and one event. The IoT device represented by this TD uses the HTTP protocol but a TD can represent any protocol with a URI scheme, as shown in the example below.

{
    "@context": "https://www.w3.org/2019/wot/td/v1",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "title": "MyLampThing",
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic", "in":"header"}
    },
    "security": ["basic_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{
                "href": "https://mylamp.example.com/status",
                "htv:methodName":"GET"
            }]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{
                "href": "https://mylamp.example.com/toggle",
                "htv:methodName":"POST"
            }]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "htv:methodName":"GET",
                "subprotocol": "longpoll"
            }]
        }
    }
}

This TD represents an Internet connected lamp, which could be thought as a simple version of a Philips Hue lamp.

From this TD example, a client knows that there exists one Property affordance with the title status (lines 10-16). In addition, information is provided in lines 13-14 that this Property is readable with an HTTP GET request to the URI https://mylamp.example.com/status, and will return a string-based status value. In a similar manner, an Action affordance is specified to toggle the switch status using the POST method on the https://mylamp.example.com/toggle resource. The Event affordance enables a mechanism for asynchronous messages to be sent by a Thing. Here, a subscription to be notified upon a possible overheating event of the lamp can be obtained by using HTTP with its long polling subprotocol on https://mylamp.example.com/oh. The use of the GET or POST method is stated explicitly but can be omitted using the default assumptions stated in the TD specification. It can be seen that the HTTP methods are defined using the "htv:methodName" vocabulary terms. This vocabulary terms for HTTP are included in the TD vocabulary that is found in the "@context" value.

This example also specifies the basic security scheme, requiring a username and password for access. A security scheme is first given a name and its corresponding scheme in the securityDefinitions and then activated by specifying that name in a security section. In combination with the use of the HTTP this example demonstrates the use of Basic access authentication.

Below is the same connected lamp but using MQTT protocol and no security.

{
    "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        {"mqv": "http://www.example.org/mqtt-binding#"}
    ],
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "title": "MyLampThing",
    "securityDefinitions": {
        "nosec_sc": {"scheme": "nosec"}
    },
    "security": ["nosec_sc"],
    "properties": {
        "status" : {
            "type": "string",
            "forms": [{
                "href": "mqtt://mylamp.example.com/status",
                "mqv:controlPacketValue": "SUBSCRIBE"
            }]
        }
    },
    "actions": {
        "toggle" : {
            "forms": [{
                "href": "mqtt://mylamp.example.com/toggle",
                "mqv:controlPacketValue": "PUBLISH"
            }]
        }
    },
    "events":{
        "overheating":{
            "data": {"type": "string"},
            "forms": [{
                "href": "mqtt://mylamp.example.com/oh",
                "mqv:controlPacketValue": "SUBSCRIBE"
            }]
        }
    }
}

Differently from the last TD, here the forms include MQTT protocol as specified by the WoT Binding Templates. More specifically, lines 17, 25 and 34 describe what message types should be used to use the affordances. For example, instead of HTTP GET and longpoll subprotocol to observe the overheating event, a client can subscribe to this event using the MQTT protocol. Furthermore, a WoT device with MQTT protocol can be both a publisher and a subscriber. For the property and event affordances, it would publish the values, whereas for action affordances it would subscribe to the action topics that other MQTT publishers can trigger by publishing to these topics.

Implementations

Thing Description editing and validation tools

  • Eclipse edi{TD}or:[14] A tool for simply designing W3C Thing Descriptions and Thing Models
  • TD Playground:[15] Playground for validation of Thing Description instances

Implementations using Thing Description

  • Eclipse node-wot:[16] An implementation of W3C WoT technologies in Node.js
  • WoTify:[17] A library of WoT implementation that support a Thing Description
  • wot-py:[18] An implementation of W3C WoT technologies in Python
  • Node-RED node-gen:[19] Generates nodes based on a Thing Description in Node-RED
  • SANE:[20] An implementation of W3C WoT technologies in Java

See also

References

  1. "Web of Things over IoT and Its Applications" (in en). https://www.infoq.com/articles/web-of-things-iot-apps/. 
  2. "Solution for IoT Interoperability – W3C Web of Things" (in en). 13 April 2020. https://www.dataversity.net/solution-for-iot-interoperability-w3c-web-of-things/. 
  3. Käbisch, Sebastian; Kamiya, Takuki; McCool, Michael; Charpenay, Victor; Kovatsch, Matthias (2020-04-09). "Web of Things (WoT) Thing Description". https://www.w3.org/TR/wot-thing-description10/. 
  4. Käbisch, Sebastian; McCool, Michael; Korkan, Ege (2023-12-05). "Web of Things (WoT) Thing Description 1.1". https://www.w3.org/TR/wot-thing-description11/. 
  5. "Solution for IoT Interoperability - W3C Web of Things (WoT)". W3C Press. https://www.w3.org/2020/04/pressrelease-wot-rec.html.en. 
  6. Koster, Michael; Korkan, Ege (2019-01-30). "Web of Things (WoT) Binding Templates". https://www.w3.org/TR/wot-binding-templates/. 
  7. Kellogg, Gregg; Champin, Pierre-Antoine; Longley, Dave (2020-07-16). "JSON-LD Syntax 1.1". https://www.w3.org/TR/json-ld11/. 
  8. Serena, Fernando; Poveda-Villalón, María; García-Castro, Raúl (22 February 2018). Semantic Discovery in the Web of Things. Cham, Switzerland: Springer. doi:10.1007/978-3-319-74433-9_2. ISBN 978-3-319-74433-9. https://link.springer.com/chapter/10.1007/978-3-319-74433-9_2. 
  9. Ed., R. Shekh-Yusef; Ahrens, D.; Bremer, S. (2015). HTTP Digest Access Authentication. IETF. doi:10.17487/RFC7616. https://tools.ietf.org/html/rfc7616. Retrieved 2020-09-01. 
  10. Nottingham, M. (September 2017). Web Linking. IETF. doi:10.17487/RFC8288. https://tools.ietf.org/html/rfc8288. 
  11. Wright, Austin; Andrews, Henry; Luff, Geraint. "JSON Schema Validation: A Vocabulary for Structural Validation of JSON". Ietf Datatracker (IETF). https://tools.ietf.org/html/draft-handrews-json-schema-validation-01. 
  12. Berners-Lee, T.; Fielding, R.; Masinter, L. (2005). Uniform Resource Identifier (URI): Generic Syntax. IETF. doi:10.17487/RFC3986. https://tools.ietf.org/html/rfc3986. 
  13. Freed, N.; Borenstein, N. (1996). Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. IETF. doi:10.17487/RFC2046. https://tools.ietf.org/html/rfc2046. 
  14. Eclipse edi{TD}or project, Eclipse Foundation, 2020-12-04, https://github.com/eclipse/editdor/ 
  15. Thing Description Playground, 2020-11-14, http://plugfest.thingweb.io/playground/ 
  16. thingweb.node-wot. W3C Web of Things implementation on NodeJS., Eclipse Foundation, 2019-11-14, https://github.com/eclipse/thingweb.node-wot, retrieved 2019-11-17 
  17. Korkan, Ege; Hassine, Hassib Belhaj; Schlott, Verena Eileen; Käbisch, Sebastian; Steinhorst, Sebastian (2019-09-07). "WoTify: A platform to bring Web of Things to your devices". arXiv:1909.03296 [cs.DC].
  18. Mangas, Andrés García (2020-01-08), Experimental implementation of a W3C Web of Things runtime: agmangas/wot-py, https://github.com/agmangas/wot-py, retrieved 2020-01-15 
  19. Toumura, Kunihiko (2019-05-21), GitHub - k-toumura/node-red-nodegen, https://github.com/k-toumura/node-red-nodegen, retrieved 2020-01-15 
  20. "Java-Implementation für das Web of Things veröffentlicht" (in en-us). https://sane.city/news/2019/11/19/wot_servient/.