Definition format

A definition is a JSON object. The bridge checks it against the version 1 format and the rules on this page when you run nodelets definition install, and refuses it with a reason if anything fails.

Top level

Field	Required	Value
formatVersion	Yes	1
id	Yes	Lowercase letters, digits and -, starting with a letter or digit, at most 64 characters
title	Yes	A non-empty string
description	No	A string
driver	Yes	http or mqtt
properties	See below	An object of property schemas, by name
actions	See below	An object of actions, by name
events	See below	An object of events, by name
bindings	Yes	How the bridge reaches each property, action and event

A definition must declare at least one property, action or event. No other fields are allowed.

Property, action and event names start with a letter, then letters, digits, _ or -, at most 64 characters in all.

Value schemas

Properties, action inputs and outputs, and event data are described with a subset of JSON Schema. type is required.

type	Further keywords
boolean	none
number	minimum, maximum
integer	minimum, maximum
string	minLength, maxLength
object	properties, required, additionalProperties (a boolean)
array	items (required), minItems, maxItems
null	none

Every type also accepts enum, title, description and unit. No other keywords are allowed.

Rules:

• A minimum may not exceed its maximum, for numbers, lengths and item counts.
• For an integer, bounds and enum values must be whole numbers within ±9,007,199,254,740,991.
• Every name in required must appear in properties.
• enum values must be unique and must each match the rest of the schema.

Properties

A property is a value schema with three extra flags. Each defaults to false.

Flag	Meaning
readOnly	The property cannot be written. It may not have a writeproperty binding
writeOnly	The property cannot be read. It may not have a readproperty binding. Its values are not kept on the record and not collected for history
observable	The property has live values. It must have an observeproperty binding

A property cannot be both readOnly and writeOnly. Only a property’s top level takes these flags.

Actions

Field	Required	Value
title, description	No	Strings
input	No	A value schema. Without it, the action takes no input
output	No	A value schema. Without it, the action returns null

Events

Field	Required	Value
title, description	No	Strings
data	Yes	A value schema for each event’s data

Bindings

"bindings": {
  "properties": { "name": { "readproperty": {}, "writeproperty": {}, "observeproperty": {} } },
  "actions": { "name": { "invokeaction": {} } },
  "events": { "name": { "subscribeevent": {} } }
}

• Each binding must name a declared property, action or event.
• Every property needs at least one binding.
• Every action needs exactly one invokeaction binding, and every event exactly one subscribeevent binding.
• An operation with no binding is not offered by the Nodelet, to any credential.

HTTP bindings

Paths are literal, start with a single /, and contain no # or line breaks. The bridge adds them to the device’s base URL.

Operation	Fields
readproperty	method: GET. path. Optional responsePointer
writeproperty	method: PUT, POST or PATCH. path. No responsePointer
invokeaction	method: POST. path. Optional responsePointer, which needs a declared output
observeproperty	method: GET. path. stream: sse. Optional responsePointer and event
subscribeevent	method: GET. path. stream: sse. Optional responsePointer and event

responsePointer is a JSON Pointer into the device’s reply, or into each event’s data. Without it, the whole reply is the value. event keeps only server-sent events of that name.

A write sends the value as the JSON body, and an action sends its input as the JSON body, with Content-Type: application/json.

MQTT bindings

An MQTT definition declares properties only, with readproperty and writeproperty bindings. It cannot declare actions, events or observeproperty.

Operation	Fields
readproperty	request: {"topic", "payload"}. reply: {"topic", "pointer"}
writeproperty	request: {"topic", "valuePointer"}. confirm: {"topic", "pointer"}

Topics are 1 to 1,024 characters with no +, # or NUL. payload is any JSON value. Pointers are JSON Pointers; an empty valuePointer sends the value itself.

Device settings

The definition describes a kind of device. Each device’s address is given to nodelets thing add and stays on the bridge.

Driver	Setting	Value
http	Base URL	http:// or https://, a host and an optional port, with no path, query, fragment or user information
http	Headers	Optional name and value pairs sent with every request. Host, Content-Length, Connection and Transfer-Encoding are not allowed
mqtt	Broker	mqtt://host, or mqtt://host:port when the port is not 1883

Installing and changing

• Installing a file identical to an installed definition changes nothing.
• Installing a different file under an installed id fails with DEFINITION_CONFLICT.

See Write a definition for a worked example and for moving devices to a changed definition.