This document describes an experimental plain JSON serialization of the [[wot-thing-description]] data model. The Thing Description provides machine readable metadata describing a physical device connected to the World Wide Web.

This document builds upon the JSON serializations proposed in the [[web-thing-model]] and [[web-thing-api]] member submissions and the [[building-web-of-things]] book.

Introduction

The Web of Things is intended as a unifying application layer for the Internet of Things to bridge together underlying IoT protocols. The goal is to create a decentralized Internet of Things by giving connected devices URLs on the web to make them linkable and discoverable, and defining a standard data model and APIs to make them interoperable.

In this document we propose a plain JSON serialisation of a [[wot-thing-description]] with a default semantic context denoted by an application/thing+json media type (not yet submitted for IANA registration). The basic description format can be extended with semantic annotations using JSON-LD.

Web Thing Description

The Thing Description provides a vocabulary for describing physical devices connected to the World Wide Web in a machine readable format.

Example
{
  "name":"My Lamp",
  "type": "thing",
  "description": "A web connected lamp",
  "properties": {
    "on": {
      "type": "boolean,
      "description": "Whether the lamp is turned on",
      "href": "/things/lamp/properties/on"
    },
    "brightness" : {
      "type": "number",
      "description": "The level of light from 0-100",
      "minimum" : 0,
      "maximum" : 100,
      "href": "/things/lamp/properties/brightness"
    }
  },
  "actions": {
    "toggle": {
      "description": "Toggle the lamp on and off"
    }
  },
  "events": {
    "overheating": {
      "description": "The lamp has exceeded its safe operating temperature"
    }
  },
  "links": {
    "properties": "/thing/lamp/properties",
    "actions": "/things/lamp/actions",
    "events": "/things/lamp/events"
  }
}
        

name member

The name member is a human readable string which identifies the device. This can be set to any value by the device creator and may include a brand name or model number.

type member

The type member defines the type of device described by the Thing Description. Some primitive thing types may be defined as part of a default web thing context (e.g. onOffSwitch and binarySensor). The type system is extensible via schemas using JSON-LD, see Extensibility with JSON-LD.

description member

The description member is a human readable string which describes the device and its functions. This can be set to any value by the device creator.

properties member

The properties member is a map of property objects which describe readable and/or writable attributes of a device. Examples might include an on/off state, a brightness level or a temperature value.

actions member

The actions member is a map of action objects which describe functions that can be carried out on a device. Actions are used when the setting of properties alone is not sufficient to affect a required change in state, such as actions which have a different outcome depending on provided arguments or previous state, or take a certain amount of time to complete. Examples might include fading in a light, toggling an on/off switch, moving a robot or brewing a cup of coffee.

events member

The events member is a map of event objects which define the types of events which may be emitted by a device when a certain condition is met. Examples might include a temperature sensor or fill level sensor reaching a certain threshold.

links member

The links member provides a map of URLs for Properties, Actions and Events resources. It can also contain a WebSocket URL to be used for the Thing's WebSocket API. Entries in this map have a key which can be one of properties, actions, events and a string value representing a URL.

Property object

A property object describes an attribute of a Thing. It contains a href reference to a URL for getting the value of the property as well as all the fields of a value object.

Example
"brightness" : {
  "name": "Brightness",
  "type": "number",
  "description": "The level of light from 0-100",
  "minimum" : 0,
  "maximum" : 100,
  "href": "/things/lamp/properties/brightness"
}

Action object

An action object describes a function which can be carried out on a device. An action may include parameters as a data field containing a value object.

Example
"fade" : {
  "name": "Fade",
  "description": "Fade from one brightness to another",
  "data": {
    "from": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "to": {
      "type: number",
      "minimum": 0,
      "maximum": 100
    },
    "duration": {
      "type": "number",
      "unit": "milliseconds",
    }
  },
  "href": "/things/lamp/actions/fade"
}

Event object

An event object describes a type of event which may be emitted by a device. An event includes parameters as a data field containing a value object. An event may also have name and a human readable description which describes what the event was about.

Example
"overheated": {
  "name": "Overheated",
  "description": "The device exceeded its maximum safe operating temperature",
  "data": {
    "temperature": {
      "type": "number",
      "unit": "celcius"
    }
  }
}

Value object

Several objects also embed a value object. A value object contains metadata about a value such as its type and unit. This may include unit (value using one the case-insensitive full names defined in the International System of Units [[SI]], e.g. "meter per second squared"), mininum value, maximum value, human readable description and type.

Where type is one of: string, number, boolean, object, array, as specified in [[json-schema]].

Alternative Encodings

The JSON serialization is just one encoding for the Thing description, but other encodings such as XML, JSON-LD or CBOR may be used. Alternative encodings are beyond the scope of this specification but may be defined separately.

References to alternative available encodings may be provided using Link HTTP response headers with the alternate link relation. A client can express a preference for a particular encoding using HTTP content negotiation.

Extensibility with JSON-LD

The Web Thing Description format uses a schema based system which allows anyone to define their own Web Thing types and share them with others in order to encourage interoperability. JSON-LD notation is used to add semantic annotations to a Thing Description in order to establish a shared semantic context and define a Web Thing type.

Example
{
  "@context": "http://iot.schema.org",
  "@type": "Toaster",
  "name":"Acme Toaster",
  "description": "A web connected toaster",
  "properties": {
    "on": {
      "type": "boolean",
      "description": "Whether the toaster is currently heating bread",
      "href": "/properties/on"
    },
    "timeRemaining": {
      "type": "number",
      "unit": "seconds",
      "href": "/properties/timeRemaining"
    }
  },
  "actions": {
    "pop": {
      "description": "Pop up the toast"
    }
  },
  "events": {
    "ready": {
      "description": "Your toast is ready!"
    }
  }
}

The @context property provides an IRI which defines a globally unique "context" within which types are defined. The optional @type property specifies a Web Thing type from that context to be applied to the thing being described.

When no @context property is supplied, a default Web Thing context is assumed and type is equivalent to @type. Using @type overrides the type property.