Reportable State Properties
Some AVS capability interfaces define a special kind of context entry called a "reportable state property".
When a capability defines a state property, it is an instance of a property schema, and it follows a defined set of mechanics for reporting and setting property values.
Examples include
- Alexa.PowerController's
powerState
- Alexa.ToggleController's
toggleState
- Alexa.RangeController's
rangeValue
- Alexa.ModeController's
mode
Contrast to Generic Device Context
Generic context entries are typically used to help Alexa interpret user utterances at runtime by providing information about on-device activities. For example, if a user says "Alexa, stop", device context might tell Alexa whether an alert is firing (AlertsState
) or music is playing (PlaybackState
). That allows Alexa to interpret the utterance correctly and respond with the appropriate directive to the device.
By contrast, reportable state properties are device or endpoint states that aren't inherently implicated in synchronous voice interactions. For example, the power state of a light switch might be modeled as a reportable state property. The device might proactively report the state if the user physically flips a switch, return a fresh state whenever requested by Alexa, or change the state based on a directive.
JSON Representation
Reportable state properties follow a consistent paradigm for JSON representation.
Property Object
When a device sends the values of reportable state properties to Alexa through an event, it provides an object that includes metadata about the sampling of the state property:
Sample Object
{ "namespace": "{{STRING}}", "instance": "{{STRING}}", "name": "{{STRING}}", "value": {{OBJECT}} | "{{STRING}}" | {{LONG}}, "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }
Object Parameters
Parameter | Description | Type |
---|---|---|
namespace | The namespace of the capability interface defining the reportable state property. | string |
instance | If the namespace is for a generic controller, the identifier of the instance of the controller. | string |
name | The name of the reportable state property, as defined by the capability interface. | string |
value | The value of the reportable state property. | various |
timeOfSample | The time at which the property value was recorded, in ISO 8601 YYYY-MM-DDThh:mm:ssZ format. |
string |
uncertaintyInMilliseconds | The number of milliseconds that have elapsed since the property value was last confirmed. For example, if the device sampled the property value from the endpoint 60 seconds ago, the uncertaintyInMilliseconds would be 60000 . |
long |
Each capability interface's documentation describes this object for any reportable state properties it defines.
The object can be provided in several different lists, depending on event definitions and developer choice:
In events such as ChangeReport
, the payload
defines a properties
list for the changed states:
"properties": [ { "namespace": "{{STRING}}", "instance": "{{STRING}}", "name": "{{STRING}}", "value": "{{STRING}}" | {{LONG}} | {{OBJECT}} | {{LIST}}, "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }, // additional reportable state properties ]
In any event that calls for context, reportable state properties may be included, as the definition of the event requires or allows:
{ "context": [ { "namespace": "{{STRING}}", "instance": "{{STRING}}", "name": "{{STRING}}", "value": "{{STRING}}" | {{LONG}} | {{OBJECT}} | {{LIST}}, "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }, // additional reportable state properties // and generic context entries, if permitted/required ], "event": {...} }
Note: Developers have the option to report context
as an object with a subordinate properties
list to send both reportable state properties and generic context entries. See the note about alternative JSON format for context for more information.
Property Key
When Alexa sends a directive to the device instructing it to change the value of a state, the payload
of the directive may have the reportable state property's name as the JSON key:
Sample Payload
{ "{{STRING}}": "{{STRING}}" | {{LONG}} | {{OBJECT}} | {{LIST}} }
The "{{STRING}}"
key is the name of the reportable state property, corresponding to the name
field of the property object.
The value, represented above by "{{STRING}}" | {{LONG}} | {{OBJECT}} | {{LIST}}
, is the value of the reportable state property, corresponding to the value
field of the property object.
Alexa.ModeController and its mode
property are an example of a capability interface and state property that use the property keys format in directives. For instance, the SetMode
directive's payload
has a single mode
field. Its value can be any of the value
fields included in the configuration.supportedModes
objects of the capability assertion.
In general, each capability interface's documentation describes the property key for any directive that can control reportable state property values.
Note: The namespace
and instance
(if applicable) are sent in the header
object of the directive.
State Reporting
When a device asserts support for a capability interface through Alexa.Discovery, it also reports the ways in which the state property's values can be reported and set.
Proactive Reporting
The proactivelyReported
boolean field in the capability assertion object defined by a particular interface describes whether the device will proactively send Alexa updates about changes to the state property's value.
When the field is set to true
, the device must send the ChangeReport
event whenever it detects a change to the state.
Retrieval
The retrievable
boolean field in the capability assertion object defined by a particular interface describes whether the device can sample and return the state property's value on demand, in response to the ReportState
directive.
The device must always send the StateReport
event in response to the ReportState
directive. When the field is set to true
for a particular state property, the property must be included in the StateReport
event. Otherwise, it must be omitted.
Controllability
The nonControllable
boolean field in the capability assertion object defined by a capability describes whether the state property is read-only.
When the field is set to true
, Alexa will not attempt to change the state. Therefore, no directives will be sent for that capability to change the value of the state property.
When the field is omitted or set to false
, Alexa may send directives defined by the capability to change the value of the state property. The device then replies to these control directives with a Response
event that reflects the changed state property value.
The individual capability documentation will specify whether the nonControllable
field can be used.
Contrast to Per-Interface Settings
Reportable state properties and per-interface settings share similar semantics and mechanics. Be sure to refer to the documentation of individual capability interfaces to understand which to use.
In particular, be aware of the difference between similarly named messages in the Alexa and System capability interfaces. For example,
- The
ReportState
directive - The
StateReport
event
Property Schemas
A property schema defines the structure and range of values, of which a particular state property may be one instance.
For example, the Temperature
property schema defines that for any state property name
that is an instance of the schema, the value
will have the following definition:
{ "value": {{LONG}}, "scale": "{{STRING}}" }
value
represents the numeric magnitude of the temperature, and scale
specifies whether the units are CELSIUS
, FAHRENHEIT
, or KELVIN
.
A particular capability interface may define a state property that is an instance of this Temperature
schema. Alexa.TemperatureSensor may define a temperature
property, while Alexa.ThermostatController may define targetSetpoint
, lowerSetpoint
, and upperSetpoint
. All these properties, across capability interfaces, all share the same definition.
Sample Property Object
{ "namespace": "Alexa.TemperatureSensor", "name": "temperature", "value": { "value": {{LONG}}, "scale": "{{STRING}}" }, "timeOfSample": "{{STRING}}", "uncertaintyInMilliseconds": {{LONG}} }
In the above example, the structure of the value
object would remain invariant if the namespace
and name
were Alexa.ThermostatController
and targetSetpoint
, respectively.
In some cases, a capability interface may need to define a reportable state property that cannot fit a preexisting, general property schema. In such cases, a new property schema may be defined. For example, Alexa.ThermostatController requires a thermostatMode
state property, so the ThermostatMode
property schema was created to accommodate that need.
Refer to the property schemas page of the Smart Home Skills Kit documentation, where they are used extensively by Smart Home capabilities.
Last updated: Jan 22, 2021