Events

Events main function is to monitor the changes that cause a change in a Thing's property by providing a log of all these changes emitted from the real-world entity.

Events are used primarily when a subscription to a change in the Thing property is not enough. Events are usually read only.

Below is an example of an event:

{
    ...
    "events": {
        "overheating": {
            "data": {
                "type": "string",
                "description": "The error body for an overheating event."
            },
            "title": "",
            "description": ""
        }
    }
}

Events are defined similarly to Properties and Actions. They allow for several metadata keys to describe what the event is, and those metadata keys follow a standard format.

The following keys can be used to describe an event:

Table 1. All Events can use the following metadata keys
Metadata Definition	Description	Required?	Type
`title`	Title of the event displayed in the UI	No	`string`
`description`	Additional content to tell the user what the event is for.	No	`string`
`data`	Defines the expected format of the event body.	No	`object`

The difference in defining Events is the data key. The data key is what houses the information that describes what each event should look like. The information expected in an event (as defined in the data key of the thing description) can be any one of the following primitive types:

array: Expects a list of results
boolean: Expects a true/false
number: Expects any real number
integer: Expects any whole number
object: Expects a JSON object with additional properties defined.
Note: Using Object type properties, you can nest properties within properties to create rich structures.
string: Expects a series of letters and/or numbers
null: Expects no value

Each of these primitive types can be further defined by any or all of the following metadata keys.

Table 2. All data types can use the following metadata keys
Metadata Definition	Description	Required?	Type
`title`	Title of the event data displayed in the UI.	No	`string`
`description`	Additional content to tell the user what the event data is for.	No	`string`
`type`	Primitive data type for validation of the event data.	No	`string`
`unit`	Provides a reference unit, especially for numbers and integers.	No	`string`
`readOnly`	Validates that a value should not be written to.	Yes (default is `false`)	`boolean`

Note: In the Web of Things specification from W3C, many more metadata keys are allowed. Those are not yet supported. These include "enum", "titles", "descriptions", "@type", "const", "oneOf", "writeOnly", and "format". Nor do we support "items", "minItems" or "maxItems" on Arrays, as well as "properties" or "required" on Objects yet.

Table 3. Number data types can also use the following metadata keys (plus those in "All")
Metadata Definition	Description	Required?	Type
`minimum`	Minimum value. Used for validation.	No	`number`
`maximum`	Maximum value. Used for validation.	No	`number`

Table 4. Integer data types can also use the following metadata keys (plus those in "All")
Metadata Definition	Description	Required?	Type
`minimum`	Minimum value. Used for validation.	No	`integer`
`maximum`	Maximum value. Used for validation.	No	`integer`

Note: "String", "boolean" and "null" event data types do not offer any additional definition beyond what is allowed in "all"

Add the Events to a Thing

In the Overview panel of a Thing, click the plus icon next to Events.
The New Event dialog opens.
Enter the Event Key value. This should be a descriptor of the Event.
In the Title field, enter a title for the Event.
If desired, enter any optional descriptors for this Event.

Figure 1.
Click Create.
The information is added to the schema.

Figure 2.

In addition, the Event Data Structure and Event Log is created and displayed.

Figure 3.
Once the Event has been created, you can click on the Edit icon to make further changes to this Event.

Figure 4.