W3C Web of Things (WoT): Thing Description (TD)

IoT deployments routinely mix Zigbee sensors, MQTT-speaking gateways, CoAP-based constrained nodes, and cloud REST APIs — each with its own data model and interaction pattern. Integrating a new device today usually means reading a vendor PDF, guessing at field names, and writing bespoke glue code per protocol. The W3C Web of Things (WoT) initiative attacks this at the semantic layer: it doesn't replace MQTT, CoAP, or HTTP, it standardizes a machine-readable description of what a device does and how to talk to it, so that generic software (not hand-written drivers) can discover and use any "Thing." The centerpiece of that standard is the Thing Description (TD).

The Problem WoT Solves

IoT interoperability failures usually aren't at the wire level — TCP/IP and HTTP are universal enough. They're at the application semantics level: does temp mean Celsius or Fahrenheit? Is /led a GET-to-read or POST-to-write endpoint? Is the payload JSON, CBOR, or a raw byte? Every platform (AWS IoT, Azure IoT Hub, a private oneM2M deployment) answers these questions differently, and each answer is usually locked inside proprietary SDKs.

WoT's approach, standardized by the W3C WoT Working Group, is to describe a device's capabilities in a self-contained, machine-readable document — the Thing Description — using a common vocabulary (JSON-LD based on the WoT Thing Model). Any WoT-aware consumer (a browser, a gateway, a cloud rules engine) can fetch a TD and immediately know how to interact with that Thing, without a device-specific driver.

Anatomy of a Thing Description

A TD is a JSON(-LD) document with a fixed top-level structure:

The forms block is the key interoperability mechanism — it maps an abstract interaction ("read temperature") to a concrete protocol operation (GET http://192.168.1.20/temp, content type application/json), or equally to a CoAP or MQTT binding. The abstract model stays protocol-agnostic; only forms is protocol-specific.

Worked Example: A Smart Thermostat TD

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "id": "urn:dev:thermo-42",
  "title": "Living Room Thermostat",
  "securityDefinitions": {
    "basic_sc": { "scheme": "basic" }
  },
  "security": ["basic_sc"],
  "properties": {
    "temperature": {
      "type": "number",
      "unit": "degreeCelsius",
      "readOnly": true,
      "forms": [
        { "href": "https://192.168.1.20/temp", "op": "readproperty" }
      ]
    },
    "targetTemp": {
      "type": "number",
      "unit": "degreeCelsius",
      "forms": [
        { "href": "https://192.168.1.20/target", "op": ["readproperty", "writeproperty"] }
      ]
    }
  },
  "actions": {
    "boost": {
      "input": { "type": "integer", "unit": "minute" },
      "forms": [
        { "href": "https://192.168.1.20/boost", "op": "invokeaction", "htv:methodName": "POST" }
      ]
    }
  },
  "events": {
    "overheat": {
      "data": { "type": "number" },
      "forms": [
        { "href": "https://192.168.1.20/events/overheat", "subprotocol": "sse" }
      ]
    }
  }
}

A generic WoT consumer reading this TD knows, without any prior integration work:

1. Authentication — HTTP Basic auth is required (security: basic_sc).
2. Reading state — GET temperature returns a number in °C.
3. Writing state — targetTemp accepts both GET and PUT-style writes at /target.
4. Invoking behavior — POST an integer (minutes) to /boost to trigger a boost action.
5. Subscribing to events — Server-Sent Events at /events/overheat deliver overheat notifications.

Verification check: every interaction affordance (properties, actions, events) has at least one forms entry with a resolvable href and an op — this is the mandatory minimum for a TD to be actionable, per the WoT TD spec. If a forms entry were missing, the property would be described semantically but unreachable — a common validation bug caught by TD linters (e.g., the W3C-provided TD Playground validator).

WoT Architecture: The Core Specifications

The WoT family is more than TD alone. The core specs are WoT Architecture, WoT Thing Description, WoT Discovery, WoT Binding Templates, and the informative WoT Scripting API:

• WoT Architecture: the overarching document defining the abstract WoT model, terminology, and how the other specs relate.
• Thing Description (TD): the metadata/interaction contract, as above. As of TD 1.1, this specification also defines the Thing Model (TM) — an abstract, reusable TD template (no concrete forms/network bindings) — useful for describing a product line before deployment-specific network details are known. TM is not a separate top-level spec; it's part of TD.
• Discovery: mechanisms (DNS-SD, CoRE Link Format, well-known URIs) for finding TDs on a network.
• Binding Templates: normative guidance and examples for mapping TD's abstract forms vocabulary onto concrete protocols (HTTP, CoAP, MQTT, Modbus, etc.).
• Scripting API / WoT Runtime (informative): a JavaScript-based API for exposing/consuming Things, used by reference implementations like the Eclipse Thingweb node-wot stack.

Where TD Fits Versus Other Standards

TD's differentiator is that it's not tied to one transport or one vertical — the same abstract property/action/event model can bind to HTTP, CoAP, MQTT, or even Modbus via custom forms extensions, which makes it attractive as a semantic interoperability layer sitting above heterogeneous transport standards rather than competing with them directly.

Practical Design Implications

• Constrained devices (RFC 7228 Class 0/1) typically can't host a TD server themselves; a gateway or cloud proxy holds and serves the TD on their behalf, translating abstract operations into the device's native low-power protocol.
• Content negotiation matters: a TD can list multiple forms for the same property (e.g., JSON over HTTP and CBOR over CoAP), letting a consumer pick the most efficient encoding it supports.
• Versioning and drift: because TDs are static-ish documents, firmware updates that change the interaction surface must republish an updated TD — treat TD publication as part of the device lifecycle/OTA process, not a one-time artifact.
• Security is explicit but not enforced by TD itself — securityDefinitions documents the scheme; actual authentication/authorization is still implemented by the underlying protocol stack.

Key Takeaways

• The W3C WoT Thing Description is a standardized, JSON-LD-based metadata document describing a device's properties, actions, and events plus how to invoke them (forms).
• TD solves application-layer semantic interoperability, not transport interoperability — it sits above existing protocols (HTTP, CoAP, MQTT) rather than replacing them.
• Every interaction affordance needs at least one valid forms entry with href and op to be usable by a generic WoT consumer — this is the practical minimum to check when authoring or validating a TD.
• The Thing Model (TM) variant lets vendors publish protocol-agnostic templates before network-specific details (IP addresses, ports) are known.
• For constrained (Class 0/1) devices, a gateway typically hosts and serves the TD on the device's behalf, since the device itself can't run a TD server.