Mozilla IoT

WoT Capability Schemas

iot.mozilla.org/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://iot.mozilla.org/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://iot.mozilla.org/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

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
VoltageProperty Yes No
CurrentProperty Yes No
FrequencyProperty Yes No

Actions

None.

Events

None.

LeakSensor

A device which detects whether a water 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
VoltageProperty Yes No
CurrentProperty Yes No
FrequencyProperty Yes No

Actions

Type Required
ToggleAction No
FadeAction No

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

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

CurrentProperty

type number/integer
unit ampere

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"]

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.

InstantaneousPowerProperty

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

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.