Thing Description

Last updated
Thing Description
ThingDescription Logo.png
The logo of the latest version, Thing Description
Filename extension
.jsontd, .td.json, .td.jsonld
Internet media type
application/td+json
Developed by W3C
Initial releaseApril 9, 2020
Type of format JSON-LD
Standard W3C Web of Things
Open format?Yes
Website https://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]

Contents

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

Figure 1. WoT Thing Description components. WoT Thing Description Components.png
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:

Thing Description examples

Example of a Thing Description object. Thing Description W3C WoT.svg
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

Implementations using Thing Description

See also

Related Research Articles

<span class="mw-page-title-main">SOAP</span> Messaging protocol for web services

SOAP is a messaging protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses XML Information Set for its message format, and relies on application layer protocols, most often Hypertext Transfer Protocol (HTTP), although some legacy systems communicate over Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission.

A Uniform Resource Identifier (URI), formerly Universal Resource Identifier, is a unique sequence of characters that identifies an abstract or physical resource, such as resources on a webpage, mail address, phone number, books, real-world objects such as people and places, concepts. URIs are used to identify anything described using the Resource Description Framework (RDF), for example, concepts that are part of an ontology defined using the Web Ontology Language (OWL), and people who are described using the Friend of a Friend vocabulary would each have an individual URI.

The Resource Description Framework (RDF) is a World Wide Web Consortium (W3C) standard originally designed as a data model for metadata. It has come to be used as a general method for description and exchange of graph data. RDF provides a variety of syntax notations and data serialization formats, with Turtle currently being the most widely used notation.

<span class="mw-page-title-main">Atom (web standard)</span> Web standards

The name Atom applies to a pair of related Web standards. The Atom Syndication Format is an XML language used for web feeds, while the Atom Publishing Protocol is a simple HTTP-based protocol for creating and updating web resources.

A gateway is a piece of networking hardware or software used in telecommunications networks that allows data to flow from one discrete network to another. Gateways are distinct from routers or switches in that they communicate using more than one protocol to connect multiple networks and can operate at any of the seven layers of the OSI model.

Link prefetching allows web browsers to pre-load resources. This speeds up both the loading and rendering of web pages. Prefetching was first introduced in HTML5.

GRDDL is a markup format for Gleaning Resource Descriptions from Dialects of Languages. It is a W3C Recommendation, and enables users to obtain RDF triples out of XML documents, including XHTML. The GRDDL specification shows examples using XSLT, however it was intended to be abstract enough to allow for other implementations as well. It became a Recommendation on September 11, 2007.

GeoRSS is a specification for encoding location as part of a Web feed. (Web feeds are used to describe feeds of content, such as news articles, Audio blogs, video blogs and text blog entries. These web feeds are rendered by programs such as aggregators and web browsers.) The name "GeoRSS" is derived from RSS, the most known Web feed and syndication format.

Web of Things (WoT) describes a set of standards by the World Wide Web Consortium (W3C) for the interoperability of different Internet of things (IoT) platforms and application domains.

<span class="mw-page-title-main">WebFinger</span> Protocol for the discovery of information about people and things identified by a URI

WebFinger is a protocol specified by the Internet Engineering Task Force IETF in RFC 7033 that allows for discovery of information about people and things identified by a URI. Information about a person might be discovered via an acct: URI, for example, which is a URI that looks like an email address.

In computing, Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable Web service APIs in a standard way. Microsoft initiated OData in 2007. Versions 1.0, 2.0, and 3.0 are released under the Microsoft Open Specification Promise. Version 4.0 was standardized at OASIS, with a release in March 2014. In April 2015 OASIS submitted OData v4 and OData JSON Format v4 to ISO/IEC JTC 1 for approval as an international standard. In December 2016, ISO/IEC published OData 4.0 Core as ISO/IEC 20802-1:2016 and the OData JSON Format as ISO/IEC 20802-2:2016.

Constrained Application Protocol (CoAP) is a specialized UDP-based Internet application protocol for constrained devices, as defined in RFC 7252. It enables those constrained devices called "nodes" to communicate with the wider Internet using similar protocols. CoAP is designed for use between devices on the same constrained network, between devices and general nodes on the Internet, and between devices on different constrained networks both joined by an internet. CoAP is also being used via other mechanisms, such as SMS on mobile communication networks.

JSON-LD is a method of encoding linked data using JSON. One goal for JSON-LD was to require as little effort as possible from developers to transform their existing JSON to JSON-LD. JSON-LD allows data to be serialized in a way that is similar to traditional JSON. It was initially developed by the JSON for Linking Data Community Group before being transferred to the RDF Working Group for review, improvement, and standardization, and is currently maintained by the JSON-LD Working Group. JSON-LD is a World Wide Web Consortium Recommendation.

httpRange-14 is a long-running logical conundrum or design problem in the semantic web. The problem arises because when HTTP is extended from referring only to documents to talking about real-world things the domain of HTTP GET becomes undefined.

OMA Lightweight M2M (LwM2M) is a protocol from the Open Mobile Alliance for machine to machine (M2M) or Internet of things (IoT) device management and service enablement. The LwM2M standard defines the application layer communication protocol between an LwM2M Server and an LwM2M Client which is located in an IoT device. It offers an approach for managing IoT devices and allows devices and systems from different vendors to co-exist in an IoT ecosystem. LwM2M was originally built on Constrained Application Protocol (CoAP) but later LwM2M versions also support additional transfer protocols.

<span class="mw-page-title-main">Node-RED</span> Programming tool for network-aware devices

Node-RED is a flow-based, low-code development tool for visual programming developed originally by IBM for wiring together hardware devices, APIs and online services as part of the Internet of things.

SensorThings API is an Open Geospatial Consortium (OGC) standard providing an open and unified framework to interconnect IoT sensing devices, data, and applications over the Web. It is an open standard addressing the syntactic interoperability and semantic interoperability of the Internet of Things. It complements the existing IoT networking protocols such CoAP, MQTT, HTTP, 6LowPAN. While the above-mentioned IoT networking protocols are addressing the ability for different IoT systems to exchange information, OGC SensorThings API is addressing the ability for different IoT systems to use and understand the exchanged information. As an OGC standard, SensorThings API also allows easy integration into existing Spatial Data Infrastructures or Geographic Information Systems.

<span class="mw-page-title-main">Well-known URI</span>

A well-known URI is a Uniform Resource Identifier for URL path prefixes that start with /.well-known/. They are implemented in webservers so that requests to the servers for well-known services or information are available at URLs consistent well-known locations across servers.

Micropub (MP) is a W3C Recommendation that describes a client–server protocol based on HTTP to create, update, and delete posts on servers using web or native app clients. Micropub was originally developed in the IndieWebCamp community, contributed to W3C, and published as a W3C working draft on January 28, 2016.

<span class="mw-page-title-main">Verifiable credentials</span>

Verifiable credentials (VCs) are digital credentials which follow the relevant World Wide Web Consortium open standards. They can represent information found in physical credentials, such as a passport or license, as well as new things that have no physical equivalent, such as ownership of a bank account. They have numerous advantages over physical credentials, most notably that they're digitally signed, which makes them tamper-resistant and instantaneously verifiable.

References

  1. ↑ "Web of Things over IoT and Its Applications". InfoQ. Retrieved 2020-12-03.
  2. ↑ "Solution for IoT Interoperability – W3C Web of Things". DATAVERSITY - Data Education for Business and IT Professionals. 13 April 2020. Retrieved 2020-04-13.
  3. ↑ Käbisch, Sebastian; Kamiya, Takuki; McCool, Michael; Charpenay, Victor; Kovatsch, Matthias (2020-04-09). "Web of Things (WoT) Thing Description". www.w3.org. Archived from the original on 2021-10-24. Retrieved 2020-04-17.{{cite web}}: CS1 maint: bot: original URL status unknown (link)
  4. ↑ Käbisch, Sebastian; McCool, Michael; Korkan, Ege (2023-12-05). "Web of Things (WoT) Thing Description 1.1". www.w3.org. Archived from the original on 2023-12-07. Retrieved 2023-01-19.{{cite web}}: CS1 maint: bot: original URL status unknown (link)
  5. ↑ "Solution for IoT Interoperability - W3C Web of Things (WoT)". W3C. W3C Press. 9 April 2020. Retrieved 22 December 2020.
  6. ↑ Koster, Michael; Korkan, Ege (2019-01-30). "Web of Things (WoT) Binding Templates". www.w3.org. Archived from the original on 2020-04-14. Retrieved 2020-04-17.{{cite web}}: CS1 maint: bot: original URL status unknown (link)
  7. ↑ Kellogg, Gregg; Champin, Pierre-Antoine; Longley, Dave (2020-07-16). "JSON-LD Syntax 1.1".
  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.
  9. ↑ Ed., R. Shekh-Yusef; Ahrens, D.; Bremer, S. (2015). Shekh-Yusef, R. (ed.). "HTTP Digest Access Authentication". IETF. doi:10.17487/RFC7616. S2CID   11159319 . Retrieved 2020-09-01.{{cite journal}}: Cite journal requires |journal= (help)
  10. ↑ Nottingham, M. (September 2017). "Web Linking". IETF. doi:10.17487/RFC8288.{{cite journal}}: Cite journal requires |journal= (help)
  11. ↑ Wright, Austin; Andrews, Henry; Luff, Geraint. "JSON Schema Validation: A Vocabulary for Structural Validation of JSON". Ietf Datatracker. IETF.
  12. ↑ Berners-Lee, T.; Fielding, R.; Masinter, L. (2005). "Uniform Resource Identifier (URI): Generic Syntax". IETF. doi:10.17487/RFC3986. S2CID   30973664.{{cite journal}}: Cite journal requires |journal= (help)
  13. ↑ Freed, N.; Borenstein, N. (1996). "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types". IETF. doi: 10.17487/RFC2046 .{{cite journal}}: Cite journal requires |journal= (help)
  14. ↑ Eclipse edi{TD}or project, Eclipse Foundation, 2020-12-04
  15. ↑ Thing Description Playground, 2020-11-14
  16. ↑ thingweb.node-wot. W3C Web of Things implementation on NodeJS., Eclipse Foundation, 2019-11-14, 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 , retrieved 2020-01-15
  19. ↑ Toumura, Kunihiko (2019-05-21), GitHub - k-toumura/node-red-nodegen , retrieved 2020-01-15
  20. ↑ "Java-Implementation für das Web of Things veröffentlicht". sane.city. Retrieved 2020-01-28.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.