An Overview of W3C Web of Things (WoT) Thing Description and Related Standards

The author, a senior Web front‑end expert at 360, presents a concise introduction to the W3C Web of Things (WoT) standards, highlighting the current status of key specifications such as WoT Architecture (CR), WoT Thing Description (CR), and WoT Scripting API (WD).

A table lists each specification and its current stage, explaining that CR indicates a relatively stable recommendation while WD denotes ongoing development and Working Group Notes are highly volatile.

The article then explains the core concept of the Thing Description (TD), which is a JSON‑LD document that describes a physical or virtual object, its properties, actions, and events. It details the three affordance types—PropertyAffordance, ActionAffordance, and EventAffordance—showing how they map to HTTP methods and media types.

{
  "@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" }]
    }
  },
  "actions": {
    "toggle": {
      "forms": [{ "href": "https://mylamp.example.com/toggle" }]
    }
  },
  "events": {
    "overheating": {
      "data": { "type": "string" },
      "forms": [{ "href": "https://mylamp.example.com/oh", "subprotocol": "longpoll" }]
    }
  }
}

The example demonstrates a property (status) accessible via a GET request, an action (toggle) via POST, and an event (overheating) using long‑polling, all protected by HTTP Basic authentication.

A second TD example shows how to extend the @context with the SAREF namespace, adding semantic tags such as saref:LightSwitch , saref:GetCommand , and saref:ToggleCommand to enrich the description.

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

The article also lists the namespaces (IRIs) for the core, data‑schema, security, and hypermedia vocabularies used by the TD information model, and explains how these vocabularies define classes, signatures, assignment functions, and type functions.

Further sections describe the formal object model (sets, mappings, arrays), default values, and the relationship between classes and instances, providing a rigorous foundation for interpreting TDs as both simple JSON structures and rich semantic resources.

Finally, a concise table enumerates the main TD vocabulary terms (e.g., @context, @type, id, title, properties, actions, events, links, forms, security, securityDefinitions) with their descriptions, requirement status, and data types, serving as a quick reference for developers.