This document outlines the use cases and requirements for a common sub-protocol for the Web of Things, to enable ad-hoc interoperability between WoT clients and WoT devices. This includes requirements for an HTTP sub-protocol and a WebSocket sub-protocol which define a standard way to monitor and control a connected device over the World Wide Web.

Introduction

The goal of the Web of Things (WoT) is to define a standard way to communicate with connected devices using the World Wide Web, in order to provide a unifying application layer for the Internet of Things (IoT) and promote ad-hoc interoperability between devices.

The W3C [[WOT-THING-DESCRIPTION]] specification defines the first building block of the Web of Things, by defining an information model and data format for describing the capabilities of a connected device and the interfaces with which to communicate with it.

The Thing Description specification was designed to be protocol-agnostic and flexible enough to describe a broad range of existing devices, rather than specifying a fixed protocol or application programming interface (API) which all devices must implement. The downside of this open ended flexibility is that it makes ad-hoc interoperability on the Web of Things very difficult, because it's nearly impossible to create a single WoT client which is guaranteed to be able to communicate with any WoT device.

The Web Thing Protocol specification will be designed to complement the WoT Thing Description specification by defining a common sub-protocol for the Web of Things, such that any WoT client and WoT device (or "web thing") which follow the specification will be able to communicate with each other.

The Web Thing Protocol specification will define:

This document outlines the use cases and requirements for such a specification, based on existing Web of Things implementations and the collective experience of members of the Web Thing Protocol Community Group.

In addition to the WoT Thing Description specification, the Web Thing Protocol Community Group should aim for the Web Thing Protocol specification to complement other deliverables in progress by the WoT Working Group where possible, including WoT Binding Templates and WoT Profile. It's possible some of the requirements below may be fulfilled by those specifications. The Web Thing Protocol specification itself, or subsections of it, are intended to eventually join a standards track at the W3C or another standards body such as the IETF.

Use Cases

WoT Clients

A WoT client is a software agent which monitors and controls a connected device on behalf of a user. This may include but is not limited to mobile applications, desktop applications, voice agents and mixed reality agents.

Things

  1. As a WoT client developer I want to get a list of devices hosted by a web thing directory so that the user can monitor and control them.
  2. As a WoT client developer I want to get a list of web things representing devices in the physical proximity of the client so that the user can monitor and control them.
  3. As a WoT client developer I want to get a list of web things connected to the same local network as the client so that the user can monitor and control them.
  4. As a WoT client developer I want to get the Thing Description (metadata) for a device so that I know what operations can be performed on it and how to carry out those operations.
  5. As a WoT client developer I want to discover what (sub-)protocols and file formats a device supports so that I know whether my client can communicate with it or not.
  6. As a WoT client developer I want to tell a WoT device in what languages I would prefer human-readable strings to be provided in so that I can provide the user with text they can understand.
  7. As a WoT client developer I want to authenticate with a device so that my client can be authorised to monitor and control it.

Properties

  1. As a WoT client developer I want to read the property of a device or be notified when its value changes so I can report its state to the user or automatically carry out an operation based on its value.
  2. As a WoT client developer I want to set the value of a property of a device so that I can change its physical state.

Actions

  1. As a WoT client developer I want to invoke an action on a device which modifies its state in such a way that can't be achieved by simply setting the value of a property. E.g. To carry out a function which takes a period of time to complete or has a different outcome based on provided arguments or current state.
  2. As a WoT client developer I want to get a list of instances of actions requested on a device so that I can find out their status
  3. As a WoT client developer I want to get the status of a requested action so that I can report its status back to the user or otherwise act on the basis of its status.
  4. As a WoT client developer I want to cancel an action request so that I can prevent the outcome of the action from occuring before it is complete.

Events

  1. As a WoT client developer I want to be able to subscribe/unsubscribe to a particular type of event so I can choose which events I want to be notified of by a WoT device.
  2. As a WoT client developer I want to be notified when an event is emitted by a device so that I can notify the user or react accordingly (e.g. if a safety limit is reached).

WoT Devices

A WoT device or "web thing" is a virtual representation of a physical device on the web, which acts as a WoT server with which a WoT client can communicate. Examples might include an IP camera, a smart thermostat or an internet-connected robot.

Things

  1. As a WoT device developer I want to advertise the prescence of my device on a local network so that WoT clients can discover it
  2. As a WoT device developer I want to advertise the prescence of my device to WoT clients in its physical proximity so that they can discover it
  3. As a WoT device developer I want to report to WoT clients what (sub-)protocols and file formats my device supports so that they know whether they can communicate with the device
  4. As a WoT device developer I want to know what languages a WoT client would prefer for a Thing Description so that I can provide human readable strings in the most appropriate language for the end user
  5. As a WoT device developer I want to authenticate requests to my device so that only authorised clients can monitor and control it

Properties

  1. As a WoT device developer I want to be able to report the value of a property to a WoT client when the client requests its value or the value changes, so that the client can be kept up to date with the value of the property
  2. As a WoT device developer I want to provide the ability for a WoT client to set the value of a property so that the client can affect a physical change in state of the device

Actions

  1. As a WoT device developer I want to change the physical state of the device in response to an action request from a WoT client which is more complex than simply setting the value of a property (e.g. an operation which takes a period of time to complete)
  2. As a WoT device developer I want to provide a WoT client with a list of instances of requested actions on a device so that the client can find out their status
  3. As a WoT device developer I want to be able to report the status of an action request to a WoT client when requested or when the status changes so that the client can be informed whether the action has been completed
  4. As a WoT device developer I want to cancel a running action at the request of a WoT client so that an action can be stopped before it has completed

Events

  1. As a WoT device developer I want my WoT device to be informed when a WoT client wants to subscribe/unsubscribe to notifications of a particular type of event so that I only need to notify clients which have subscribed.
  2. As a WoT device developer I want to be able to notify a WoT client when an event occurs so that the client can react accordingly (e.g. if a safety limit is reached).

WoT Gateways & Directories

A WoT gateway is hardware and/or software which bridges communications with a connected device from the Web Thing Protocol to another protocol, or acts as a proxy to bridge the Web Thing Protocol from one network to another. A WoT gateway may act as both a WoT client and WoT server (when acting as a proxy), or just as a WoT server (when briding other protocols to the Web of Things).

A WoT gateway may monitor and control WoT devices based on user commands issued via a WoT client, or automatically carry out operations on behalf of users based on changes in state or other criteria. Examples might include a smart home hub, the central computer system of a vehicle, or control software for a smart city.

A WoT directory is a service which provides a list of web things and links to their Thing Descriptions.

A WoT gateway may provide a directory of web things it hosts and may be hosted on-premises with devices (e.g. in the case of bridging a PAN protocol like Zigbee or Bluetooth to the Web of Things) or on a server on separate premises to devices (e.g. in the case of a cloud service bridging another IP-based protocol to the Web of Things).

Things

  1. As a WoT directory developer I want to provide a list of web things that my directory provides so that a WoT client knows where to get their Thing Descriptions.
  2. As a WoT directory developer I want to provide a way for clients to add and remove web things from the directory so that the directory can be kept up to date.
  3. As a WoT directory developer I want to notify WoT clients when a web thing is added or removed from the directory so that they can be kept up to date with the latest list of things.
  4. As a WoT directory developer I want to notify WoT clients when the Thing Description of a web thing is updated so that they know when to retrieve a new version.
  5. As a WoT gateway developer I want to bridge non-web IoT protocols (e.g. Zigbee, Z-Wave, Bluetooth, ONVIF or MQTT) to the Web Thing Protocol so that a WoT client can monitor and control them without needing to directly support all of those protocols.
  6. As a WoT gateway developer I want to discover WoT devices on a local network so that my gateway can proxy them to another network.

Requirements

HTTP Sub-protocol

The HTTP sub-protocol SHOULD define the [[HTTP11]] requests and responses a WoT client and WoT server should use in order to carry out the the set of operations described below, including methods, headers, payloads and expected response codes. Resources SHOULD be identified and located using the http(s):// URI scheme and serialised in [[JSON]] by default.

Things

  1. MUST define that each web thing is identified by a URI that can be de-referenced to obtain a machine readable Thing Description
  2. SHOULD define a way for a WoT client to get a list of web things hosted by a WoT directory
  3. SHOULD define a way for a Thing Description to define that the web thing it describes supports the Web Thing Protocol
  4. MAY define a way for a WoT client to add and remove web things from a WoT directory
  5. MAY define a way for a WoT client to be notified when a web thing is added or removed from a WoT directory
  6. MAY define a way for a WoT client to be notified when the Thing Description of a web thing is updated
  7. MAY define a way for a WoT client to find out what other protocols and data formats a WoT device supports
  8. MAY define a way for a WoT client to authenticate with a WoT server

Properties

  1. MUST define a way for a WoT client to get the current value of a property of a WoT device
  2. MUST define a way for a WoT client to set the value of a property of a WoT device
  3. SHOULD define a way for a WoT client to get values of all properties at once
  4. MAY define a way for a WoT client to get values of multiple properties at once

Actions

  1. MUST define a way for a WoT client to invoke an action on a WoT device
  2. SHOULD define a way for a WoT client to get a list of instances of actions requested on a WoT device
  3. MUST define a way for a WoT client to get a list of instances of actions of a given type requested on a WoT device
  4. MUST define a way for a WoT client to get the status of an action requested on a WoT device
  5. MUST define a way for a WoT client to cancel an action request on a WoT device

Events

  1. MUST define a way for a WoT client to get information about the most recent instance of a given event
  2. SHOULD define a way for a WoT client to get a list of recent instances of a given event
  3. MAY define a way to get a list of recent instances of all events

Error Conditions

  1. MUST define a way for a WoT client to be notified when a given operation on a WoT device was not completed as expected

Internationalisation

  1. MAY define a way for a WoT client to express preference to a WoT server for the language in which to provide human-readable strings in a Thing Description

Caching

  1. MAY define a way for a WoT server to notify a WoT client when the cache of a Thing Description should expire
  2. MAY define a way for a WoT server to notify a WoT client when the cache of property, action and event data should expire

WebSocket Sub-protocol

The WebSocket sub-protocol SHOULD define the [[WEBSOCKETS-PROTOCOL]] messages that a WoT client and WoT server should use to carry out the following set of operations, including the messages types, payloads, error conditions and how they should be used. Messages SHOULD be serialised in [[JSON]] by default.

Things

  1. MUST define a way for a WoT client to open a WebSocket on a WoT device, using the ws(s):// URI scheme and webthing WebSocket sub-protocol
  2. MUST define a way for a WoT client to carry out operations on multiple affordances of a web thing over a single WebSocket connection
  3. MAY define a way for a WoT client to communicate with multiple web things over a single WebSocket connection.
  4. MAY define a way for a WoT directory to send a list of web things it hosts to a WoT client
  5. MAY define a way for a WoT client to add and remove web things from a WoT directory
  6. MAY define a way for a WoT client to be notified when a web thing is added or removed from a WoT directory
  7. MAY define a way for a WoT client to be notified when the Thing Description of a web thing is updated

Properties

  1. SHOULD provide a way for a WoT server to send the current values of all properties of a WoT device to a WoT client when a WebSocket is first opened
  2. MUST provide a way for a WoT client to set the value of a property of a WoT device
  3. MUST provide a way for a WoT server to notify a WoT client of the changed value of a property of a WoT device
  4. MAY provide a way for a WoT client to set multiple properties of a WoT device in one message
  5. MAY provide a way for a WoT server to notify a WoT client of the changed value of multiple properties in a single message

Actions

  1. MUST provide a way for a WoT client to invoke an action on a WoT device
  2. MUST provide a way for a WoT server to notify a WoT client of the change in status of an action requested on a WoT device

Events

  1. MUST provide a way for a WoT client to subscribe to events of a given type from a WoT device
  2. MUST provide a way for a WoT client to unsubscribe from events of a given type from a WoT device
  3. MUST provide a way for a WoT server to notify a WoT client when an event is emitted by a WoT device, including an optional payload of event data

Error Conditions

  1. MUST define a way for a WoT client to be notified when a given operation on a WoT device was not completed as expected

Privacy Considerations

The Web of Things has a range of applications, including where privacy is particularly important such as in the medical and connected home domains. The specification SHOULD document any assumptions, recommendations and potential threats.

Security Considerations

The specification will mainly rely on existing web security mechanisms such as TLS, OAuth and JSON Web Tokens. Any assumptions, recommendations and identified potential threats SHOULD be documented.

Accessibility Considerations

The specification SHOULD document any considerations for making the Web of Things work for all people, whatever their language, location or abilities.