WebThings

WoT Capability Schemas

webthings.io/schemas

Introduction

This web page describes a repository of Web of Things capability schemas to be used as optional semantic markup in Web Thing Descriptions.

To use a schema from this repository, a Thing Description must define a @context of "https://webthings.io/schemas", define one or more device capability types as a top level @type array and define at least the required properties, actions and events for those capabilities with an appropriate @type annotation.

Example

{
  "@context": "https://webthings.io/schemas/",
  "@type": ["Light", "OnOffSwitch"],
  "id": "https://mywebthingserver.com/things/lamp",
  "title":"My Lamp",
  "description": "A web connected lamp",
  "properties": {
    "on": {
      "@type": "OnOffProperty",
      "type": "boolean",
      "title": "On/Off",
      "description": "Whether the lamp is turned on",
      "links": [{"href": "/things/lamp/properties/on"}]
    },
    "brightness" : {
      "@type": "BrightnessProperty",
      "type": "integer",
      "title": "Brightness",
      "description": "The level of light from 0-100",
      "minimum" : 0,
      "maximum" : 100,
      "links": [{"href": "/things/lamp/properties/brightness"}]
    }
  },
  "actions": {
    "fade": {
      "@type": "FadeAction",
      "title": "Fade",
      "description": "Fade the lamp to a given level",
      "input": {
        "type": "object",
        "properties": {
          "level": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "duration": {
            "type": "integer",
            "minimum": 0,
            "unit": "milliseconds"
          }
        }
      },
      "links": [{"href": "/things/lamp/actions/fade"}]
    }
  },
  "events": {
    "overheated": {
      "title": "Overheated",
      "@type": "OverheatedEvent",
      "type": "number",
      "unit": "degree celsius",
      "description": "The lamp has exceeded its safe operating temperature",
      "links": [{"href": "/things/lamp/events/overheated"}]
    }
  },
  "links": [
    {
      "rel": "properties",
      "href": "/things/lamp/properties"
    },
    {
      "rel": "actions",
      "href": "/things/lamp/actions"
    },
    {
      "rel": "events",
      "href": "/things/lamp/events"
    },
    {
      "rel": "alternate",
      "href": "wss://mywebthingserver.com/things/lamp"
    },
    {
      "rel": "alternate",
      "mediaType": "text/html",
      "href": "/things/lamp"
    }
  ]
}

Contents

Capabilities

Alarm

A device which alerts the user with an audio or visual indicator. E.g. A smoke alarm, CO alarm, burglar alarm or alarm clock.

Properties

Type Read-Only Required
AlarmProperty See note Yes

Note: An AlarmProperty MUST be read-only if the alarm can be neither dismissed nor triggered by the user.

Actions

None.

Events

Type Required
AlarmEvent Yes

AirQualitySensor

Capability to monitor air quality. Usually monitors the concentration of harmful gases (such as CO2, CO or VOCs) together with PM2.5, PM10 dust particulates.

Properties

Type Read-Only Required Notes
ConcentrationProperty Yes Yes At least one ConcentrationProperty or DensityProperty should be defined, with a separate property for each sensed gas or particulate class.
DensityProperty Yes Yes At least one ConcentrationProperty or DensityProperty should be defined, with a separate property for each sensed gas or particulate class.

Actions

None.

Events

None.

BarometricPressureSensor

A device which can measure the barometric pressure.

Properties

Type Read-Only Required
BarometricPressureProperty Yes Yes

Actions

None.

Events

None.

BinarySensor

A simple sensor with an active (true) and inactive (false) state.

Properties

Type Read-Only Required
BooleanProperty Yes Yes

Actions

None.

Events

None.

Camera

A device which can capture images.

Properties

Type Read-Only Required
ImageProperty Yes Yes

Actions

None.

Events

None.

ColorControl

The ability to set a color, e.g. for a colored light.

Properties

Type Read-Only Required
ColorModeProperty See note No
ColorProperty No No
ColorTemperatureProperty No No

Note: A device implementing the ColorControl capability MUST include either a ColorProperty or a ColorTemperatureProperty. If both are included, the device MUST also include a ColorModeProperty.

Note: A ColorModeProperty may be read-only if the device cannot handle changing the mode directly, in which case it will serve as a status indicator.

Actions

None.

Events

None.

ColorSensor

A device which detects a color.

Properties

Type Read-Only Required
ColorProperty Yes Yes

Actions

None.

Events

None.

DoorSensor

A device which detects whether a door or window is open or closed.

Properties

Type Read-Only Required
OpenProperty Yes Yes

Actions

None.

Events

None.

EnergyMonitor

Capability to monitor current energy usage.

Properties

Type Read-Only Required
InstantaneousPowerProperty Yes Yes
InstantaneousPowerFactorProperty Yes No
VoltageProperty Yes No
CurrentProperty Yes No
FrequencyProperty Yes No

Actions

None.

Events

None.

HumiditySensor

Capability to monitor the current humidity.

Properties

Type Read-Only Required
HumidityProperty Yes Yes

Actions

None.

Events

None.

LeakSensor

A device which detects whether a water or gas leak has occurred.

Properties

Type Read-Only Required
LeakProperty Yes Yes

Actions

None.

Events

None.

Light

A device which emits light, can be turned on and off and optionally have its brightness, color and color temperature controlled.

Properties

Type Read-Only Required
OnOffProperty No Yes
BrightnessProperty No No
ColorModeProperty Yes No
ColorProperty No No
ColorTemperatureProperty No No

Actions

Type Required
ToggleAction No
FadeAction No

Events

Type Required
OverheatedEvent No

Lock

A device which fastens or secures an opening (e.g. a door or window).

Properties

Type Read-Only Required
LockedProperty Yes Yes

Actions

Type Required
LockAction No
UnlockAction No

Events

None.

MotionSensor

A device which detects moving objects.

Properties

Type Read-Only Required
MotionProperty Yes Yes

Actions

None.

Events

None.

MultiLevelSensor

A sensor with a range of values.

Properties

Type Read-Only Required
LevelProperty Yes Yes

Actions

None.

Events

None.

MultiLevelSwitch

A fader or dimmer switch with a range of levels.

Properties

Type Read-Only Required
LevelProperty No Yes
OnOffProperty No No

Actions

Type Required
FadeAction No

Events

None.

OnOffSwitch

A simple switch which has an on state and an off state.

Properties

Type Read-Only Required
OnOffProperty No Yes

Actions

Type Required
ToggleAction No

Events

None.

PushButton

A momentary switch which can be pushed and returns to an un-pushed state when released.

Properties

Type Read-Only Required
PushedProperty Yes No

Actions

None.

Events

Type Required
PressedEvent Yes
DoublePressedEvent No
LongPressedEvent No

SmartPlug

A plug or mains outlet which can control power output and optionally monitor energy usage.

Properties

Type Read-Only Required
OnOffProperty No Yes
LevelProperty No No
InstantaneousPowerProperty Yes No
InstantaneousPowerFactorProperty Yes No
VoltageProperty Yes No
CurrentProperty Yes No
FrequencyProperty Yes No

Actions

Type Required
ToggleAction No
FadeAction No

Events

None.

SmokeSensor

A device which detects smoke as part of a fire alarm system.

Properties

Type Read-Only Required
SmokeProperty Yes Yes

Actions

None.

Events

None.

TemperatureSensor

A device which can measure temperature.

Properties

Type Read-Only Required
TemperatureProperty Yes Yes

Actions

None.

Events

None.

Thermostat

A device which regulates temperature. E.g. For space heating, cooking or refrigeration.

Properties

Type Read-Only Required
TemperatureProperty Yes Yes
TargetTemperatureProperty No Yes
HeatingCoolingProperty Yes No
ThermostatModeProperty No No

Note: A device may have multiple properties of the type TargetTemperatureProperty, e.g. to provide separate heating and cooling setpoints.

Actions

None.

Events

None.

VideoCamera

A device which can capture video, and optionally still images.

Properties

Type Read-Only Required
VideoProperty Yes Yes
ImageProperty Yes No

Actions

None.

Events

None.

Properties

AlarmProperty

type boolean

BarometricPressureProperty

type number/integer
unit hectopascal

BooleanProperty

type boolean

BrightnessProperty

type number/integer
minimum 0
maximum 100
unit percent

ColorModeProperty

Defines the current color mode of the device.

type string
enum ["color", "temperature"]

ColorProperty

type string (hexadecimal RGB color code, e.g. #FF0000)

ColorTemperatureProperty

type integer
unit kelvin

ConcentrationProperty

A concentration of a gas or other volatile (like dust particulates). Used in air quality sensors.

type number
minimum 0
unit ppm

CurrentProperty

type number/integer
unit ampere

DensityProperty

A density of a gas or other volatile (like dust particulates). Used in air quality sensors.

type number
minimum 0
unit micrograms per cubic metre

FrequencyProperty

type number/integer
unit hertz

HeatingCoolingProperty

Defines the current state of a heating or cooling device. e.g. a thermostat, heater or air conditioner. Must support an "off" state and may support a "heating" state, a "cooling" state, or both.

type string
enum ["off", "heating", "cooling"]

HumidityProperty

type number/integer
minimum 0
maximum 100
unit percent

ImageProperty

type null/undefined

Note: The primitive type of an ImageProperty is null or undefined (omitted), but it must provide a mediaType in one or more link relations which link to binary representations of the image property resource.

InstantaneousPowerFactorProperty

The Power Factor describes the relationship between active and reactive power used by the circuit.

type number
minimum -1
maximum 1

InstantaneousPowerProperty

This is the active or real power measurement (see Wikipedia)

type number/integer
unit watt

LeakProperty

A LeakProperty is like a BooleanProperty, but with the added semantics that true means "leak" and false means "no leak".

type boolean

LevelProperty

type number/integer
minimum number/integer
maximum number/integer
unit (optional)

LockedProperty

Defines the current state of a lock type device which can be locked, unlocked or some intermediate state. Must support a "locked" and "unlocked" state. May optionally support an "unknown" and/or "jammed" state.

type string
enum ["locked", "unlocked", "unknown", "jammed"]

MotionProperty

A MotionProperty is like a BooleanProperty, but with the added semantics that true means "motion" and false means "no motion".

type boolean

OnOffProperty

An OnOffProperty is like a BooleanProperty, but with the added semantics that true means "on" and false means "off".

type boolean

OpenProperty

An OpenProperty is like a BooleanProperty, but with the added semantics that true means "open" and false means "closed".

type boolean

PushedProperty

A PushedProperty is like a BooleanProperty, but with the added semantics that true means "pushed" and false means "not pushed".

type boolean

SmokeProperty

A SmokeProperty is like a BooleanProperty, but with the added semantics that true means "smoke detected" and false means "no smoke".

type boolean

TargetTemperatureProperty

A TargetTemperatureProperty is like a TemperatureProperty, but defines a desired temperature rather than a current temperature.

type number/integer
unit degree celsius

TemperatureProperty

type number/integer
unit degree celsius

ThermostatModeProperty

Defines the current setting of a thermostat type device which can switch on and off a heating device and/or cooling device based on a current and desired temperature. Must support an "off" state and must support one or more of a "heat" state, "cool" state and "auto" state, where "auto" means either "heat" or "cool" depending on target and current temperatures.

type string
enum ["off", "heat", "cool", "auto"]

VideoProperty

type null/undefined

Note: The primitive type of a VideoProperty is null or undefined (omitted), but it must provide a mediaType in one or more link relations which link to binary representations of the video property resource.

VoltageProperty

type number/integer
unit volt

Actions

FadeAction

Fades a multi level switch to a given level over a given duration.

input

type object
properties
  • level
    • type: integer
    • unit: percent
    • minimum: 0
    • maximum: 100
  • duration
    • type: integer
    • unit: second
    • minimum: 0

LockAction

Transitions a lock type device to a "locked" state.

input

None.

ToggleAction

Toggles a boolean state on and off.

input

None.

UnlockAction

Transitions a lock type device to an "unlocked" state.

input

None.

Events

AlarmEvent

Indicates an alarm has been triggered.

DoublePressedEvent

Indicates a button has been double-pressed.

LongPressedEvent

Indicates a button has been long-pressed.

OverheatedEvent

Indicates a device has exceeded its safe operating temperature.

data

type number/integer
unit degree celsius

PressedEvent

Indicates a button has been single-pressed.