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 Required
AlarmProperty 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 Required
BooleanProperty 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 Required
ColorProperty No
ColorTemperatureProperty No

Note: A device implementing the ColorControl capability MUST include either a ColorProperty or a ColorTemperatureProperty.

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 Required
InstantaneousPowerProperty Yes
VoltageProperty No
CurrentProperty No
FrequencyProperty 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 Required
OnOffProperty Yes
BrightnessProperty No
ColorProperty No
ColorTemperatureProperty 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 Required
LevelProperty Yes

Actions

None.

Events

None.

MultiLevelSwitch

A fader or dimmer switch with a range of levels.

Properties

Type Required
LevelProperty Yes
OnOffProperty No

Actions

Type Required
FadeAction No

Events

None.

OnOffSwitch

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

Properties

Type Required
OnOffProperty 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 Required
OnOffProperty Yes
LevelProperty No
InstantaneousPowerProperty No
VoltageProperty No
CurrentProperty No
FrequencyProperty 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

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.