ClearBlade Message Spec

ClearBlade Message Specification

The ClearBlade Message Spec allows messages gathered from IoT sensors to be self-documenting. Consequently, a developer can leverage out-of-the-box message processing microservices to accelerate the development of IoT proof-of-concepts and pilots.

Specifically, this specification increases the speed and success rate of passing the following phases of IoT Maturity Model
- Phase 1: Connectivity and Capture
- Phase 2: Interpretation of Information & Structures

This spec defines the sensor data itself, and also metadata in the form of JSON Schema.

Top-level Key	Type	Purpose
$data	Object[]	Contains sensor data values
$schema	Object	Metadata schema for $data

Full Example

{
  "$data": [
    {
      "name": "pump",
      "id": "214wsafd21-42112-1dfdsfsd-243-ddff",
      "amps": 244,
      "description": "some description",
      "enabled": true,
      "last_update": "2019-09-04T17:57:16.875586669Z",
      "setup_file": "askfdhfidajriane3o25n4otrnofgndlasfqr3n24o5lgnwslgfdbrelrq4m2tes",
      "location": { "latitude": 12.132233, "longitude": 123.1234 }
    }
  ],
  "$schema": {
    "$id": "https://example.com/device.schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Pump",
    "type": "object",
    "required": ["name", "id", "location"],
    "properties": {
      "name": { "type": "string", "description": "The device's name.", "units": "Lumens", "scaleFactor": 5.44 },
      "id": { "type": "string", "format": "uuid", "description": "The device's id." },
      "amps": {
        "type": "number",
        "description": "Current in Amperes for the pump device",
        "minimum": 0,
        "maximum": 500
      },
      "description": { "type": "string", "description": "Centrifugal Coolant Pump" },
      "enabled": { "type": "boolean", "description": "Displays whether the device is enabled or not" },
      "last_update": { "type": "string", "format": "date-time" },
      "setup_file": {
        "type": "string",
        "contentEncoding": "base64",
        "contentMediaType": "application/json",
        "description": "base64 encoded setup file"
      },
      "location": {
        "type": "object",
        "required": ["latitude", "longitude"],
        "properties": {
          "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
          "longitude": { "type": "number", "minimum": -180, "maximum": 180 }
        }
      }
    }
  }
}

Notes

1. Appending keys to $schema

The following keys are officially supported for JSON Schema Property keys:

Key	Type	Description	Example
units	string	Corresponding units for a data value	kW
scaling_factor	number	Scaling factor used to convert raw data into human ingestible values	1000

2. More on JSON Schema & ClearBlade Collection Columns

When processing the data itself, the data types will be converted in the following way:

JSON Type, format	ClearBlade Collection Column Type
string, n/a	string
integer, n/a	int
boolean, n/a	bool
string, date-time	timestamp
number, n/a	float

3. Support for Non-JSON data

https://json-schema.org/understanding-json-schema/reference/non_json_data.html