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

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
    • in the Alexa namespace is used for reportable state properties;
    • but in the System namespace is used for settings.
  • The StateReport event
    • in the Alexa namespace is used for reportable state properties;
    • but in the System namespace is used for settings.

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