Thing Schema

Our Thing schema provides a standard schema definition for the Things in your world, compliant with the Web of Things Thing Description and built on top of the popular "JSON Schema" definition.

It gives your application standard interfaces to communicate with Things in Category in the AnythingDB and provides a means for Things in your application to reference and communicate with entities outside of your application.

AnythingDB uses a standard schema definition to provide structure for Things in Category. These define the types of information you expect in the Thing. For example, below is a schema for a stereo.
{
	"actions": {
		"toggleOn": {
			"input": {
				"type": "boolean"
			}
		},
		"volumeChange": {
			"description": "Change the volume of the Sound Stereo System",
			"input": {
				"properties": {
					"Volumelevelduration": {
						"minimum": 0,
						"type": "integer",
						"unit": "seconds"
					},
					"level": {
						"maximum": 100,
						"minimum": 0,
						"type": "integer"
					}
				},
				"type": "object"
			},
			"title": "Change the Volume"
		}
	},
	"base": "https://api.swx.altairone.com",
	"category": "my-category",
	"created": "2021-10-11T14:05:56+00:00",
	"description": "",
	"events": {
		"overheating": {
			"data": {
				"description": "The roof. The roof.",
				"title": "Stereo Overheating",
				"type": "string"
			}
		}
	},
	"href": "/spaces/my-space/categories/my-category/things/01FHQTS842GDVVVSSGER1HSTE1",
	"id": "https://api.swx.altairone.com/spaces/my-space/categories/my-category/things/01FHQTS842GDVVVSSGER1HSTE1",
	"model": {
		"name": "",
		"version": 0
	},
	"modified": "2021-10-11T14:09:05+00:00",
	"properties": {
		"status": {
			"type": "string"
		},
		"volume": {
			"description": "The volume of the Sound Stereo System",
			"maximum": 100,
			"minimum": 0,
			"title": "Volume",
			"type": "integer"
		}
	},
	"space": "my-space",
	"title": "Office 211b Stereo",
	"uid": "01FHQTS842GDVVVSSGER1HSTE1"
}
In this definition, you can see what data is expected for this device:
  1. Several identifiers like id and title to differentiate this Thing description from others
  2. status and volume properties for describing the current state of the Thing
  3. toggleOn and volumeChange actions for adjusting the current state
  4. An overheating event to tell users that something worth noting is happening

All this helps create user experiences in applications that fit the data. You can use the "unit" definitions to populate a label in an input field, you can use the "type" definitions to determine whether a toggle switch is needed or an input field, and you can use the "maximum" and "minimum" definitions to validate that the data received is within expected bounds.

AnythingDB pairs this schema with its counterpart: the Thing. Where the schema describes what the data structure of a real-world entity should be, the Thing describes the current state of the real-world entity. For example, the Thing defined by the above schema might be:
{
	"actions": {},
	"base": "https://api.swx.altairone.com",
	"category": "my-category",
	"created": "2021-08-23T11:10:45+00:00",
	"description": "",
	"events": {},
	"href": "/spaces/myspace/categories/my-category/things/01FDSB98PRZG0PW9YH2SSJA869",
	"id": "https://api.swx.altairone.com/spaces/myspace/categories/my-category/things/01FDSB98PRZG0PW9YH2SSJA869",
	"model": {
		"name": "my-model",
		"version": 4
	},
	"modified": "2021-08-23T11:10:45+00:00",
	"properties": {},
	"space": "myspace",
	"title": "Office 211b Stereo",
	"uid": "01FDSB98PRZG0PW9YH2SSJA869"
}
You can see here that the Thing properties have real values to describe the state. You do not see the actions and events sections because these exist in the background and show up only when called. Using both the Thing and its schema, a developer can access not only a view of the current state of a real world asset, but all the things that are possible with that asset.
Note: For more information, the Web of Things is defined here by the World Wide Web ConsortiumĀ“s (W3C).
Thing schemas are made up of several building blocks. "Properties", "actions" and "events" are explained in the next topics, but the complete list of top-level building blocks which you can use to describe your Things are the following:
Table 1. Web of Things-defined, top-level metadata keys
Metadata Key Description Auto-generated? Required? Type
title Title of the entity to display in the UI No Yes string
id Unique reference ID for the Thing. Yes Yes string
description Additional content to help tell the user what the entity is. No No string
properties An object which defines the unique attributes that make up this entity. No No object
actions An object which defines the way a user can interact with the entity. No No object
events The types of events which the entity may generate on it's own. No No object
links The interfaces for establishing relation between entities. Yes Yes array
Note: In the Web of Things W3C specification you will find many other possible, top level metadata keys. These are not yet supported. These include "@context", "@type", "titles", "descriptions", "version", "created", "modified", "support", "base", "forms", "security", "securityDefinitions".
Table 2. SmartWorks IoT-defined, top-level metadata keys
Metadata Key Description Auto-generated? Required? Type
uid Unique identifier for this Thing Yes Yes string
href Relative reference point for this Thing Yes Yes string
category AnythingDB Category to which this Thing belongs. Yes Yes string
space SmartWorks space to which this Thing belongs Yes Yes string
model Model from which this Thing was created. Yes Yes object
Put another way, this is what a complete (but completely blank) schema would look like:
{
	"actions": {},
	"base": "https://api.swx.altairone.com",
	"category": "Links",
	"created": "2021-10-25T17:03:04+00:00",
	"description": "",
	"events": {},
	"href": "/spaces/my-space/categories/my-category/things/01FJW6FMVY668YWP27JFNKFZT7",
	"id": "https://api.swx.altairone.com/spaces/ my-space /categories/my-category /things/01FJW6FMVY668YWP27JFNKFZT7",
	"model": {
		"name": "my-model",
		"version": 1
	},
	"modified": "2021-10-25T17:03:04+00:00",
	"properties": {},
	"space": "demoworkspace",
	"title": "thing",
	"uid": "01FJW6FMVY668YWP27JFNKFZT7"
}

Any element that does not fall into one of the above building blocks will be ignored and removed when building your schema in SmartWorks IoT.

The above building blocks can be used to describe enormously complex assets. However, you can always create an empty Thing without filling in the fields described above (i.e empty properties, actions and events), giving you flexibility to add them to the device whenever it is desired.