Definitions and Thing Descriptions

A definition is the one place that says what a kind of device can do and how to reach it. Nodelets infers nothing: it does not scan the network, probe devices or guess capabilities. What a definition does not declare cannot be called, by any credential or by the Nodelets cloud.

Why written by hand

Devices that speak HTTP or MQTT rarely describe themselves. Two devices can use the same path for different things, and one device can report a value in several places. An explicit file makes the device’s surface a decision someone made and can review, rather than whatever a probe happened to find. It also makes the definition the outer limit of every permission: a key with all operations on a device still reaches only what the definition binds. A device with no write bindings cannot be written to.

The cost is the writing. Each kind of device needs a definition before it can be used.

One definition, two halves

A definition has two halves, and they go to different places.

Capabilities: the properties, actions and events, with their value schemas and titles. The bridge publishes these to the cloud, where they become the Nodelet’s API, its permissions picker and its Thing Description.
Bindings: the paths, methods, topics and pointers. These stay on the bridge, with each device’s base URL or broker and any headers.

So the cloud knows that a heater has a setpoint between 5 and 30 that can be read and written, and nothing about where the heater is or how it is reached.

An HTTP definition describes a kind of device, and many devices can share it, each with its own base URL. MQTT topics are literal, so each MQTT device needs a definition of its own.

Values are checked twice

The definition’s schemas are checked in both directions. A write or action input that does not match is refused as INVALID_INPUT before it is sent. A device reply that does not match is refused as INVALID_DEVICE_VALUE. The bridge checks values, and the cloud checks them again before passing them on.

The Thing Description

Each Nodelet has a W3C Thing Description 1.1, generated by the cloud from its capabilities and served at GET /nodelets/{id}/td and as an MCP resource. It contains:

each property, action and event, with the definition’s schemas, titles and units
a form for each operation: the REST URL and method for reads, writes and actions, and the bridge’s WebSocket address for events
an API key security scheme, sent in the Authorization header

A Thing Description is filtered for the credential that asks. A key sees only the capabilities and forms it was given.

Limits of the Thing Description

The documents validate against the Thing Description schema. Nobody has yet tested a general-purpose Thing Description client against them.
An observable property’s observeproperty form names the property’s REST URL. Live values are delivered on the bridge’s WebSocket with the Nodelets subscription messages, which a general Thing Description client does not know.
The bridge stream needs an authenticate message after opening, which the security scheme does not describe.