Capability Property Schemas

This document contains the schemas for the following properties used by the Alexa interfaces.

Overview

Many properties can be expressed as either a string or an object.

Example with property expressed as a string

"cookingMode": "TIMECOOK"

Example with property expressed as an object

{
    "name": "cookingMode",
    "value": "TIMECOOK"
}

Brightness

Indicates the brightness of an appliance such as a smart light bulb. Valid value is an integer from 0-100, inclusive.

Example brightness

{
  "name": "brightness",
  "value": 45
 }

Color

Used for properties that represent the color of an endpoint. It is a structure containing hue, saturation and brightness fields, which are each double precision numbers. For use by endpoints that are able to change color.

Example color

{
    "name": "color",
    "value": {
        "hue": 350.5,
        "saturation": 0.7138,
        "brightness": 0.6524
    }
}

Count

Represents the count of an item, such as the number of doughnuts in a box, or the number of pages in a ream of paper.

Example Count

{
    "name": "count",
    "value": 12
}

DateTime

Represents a specific date and time in Coordinated Universal Time (UTC). The DateTime is a string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. DateTime strings are always specified in UTC with no offsets.

Example DateTime

{
  "name": "cookCompletionTime",
  "value": "2017-08-30T01:18:21Z"
}

Duration

Represents a time period. The time period is represented in ISO 8601 duration format. For cooking operations, you should limit the duration value to the time portion only. This can be a positive or negative value.

The format is PT*H*H*M*M*SS*S, where:

• P: Required and indicates a duration.
• T: Required and indicates a time.
• H: Indicates hour and is preceded by the number of hours, if hours are specified.
• M: Indicates minutes, and is preceded by the number of minutes, if minutes are specified.
• S: Indicates seconds, preceded by the number of seconds, if seconds are specified.

Example 3 minute and 15 second duration

{
  "name": "cookDuration",
  "value": "PT3M15S"
}

Example delta of -30 seconds

{
  "name": "cookDurationDelta",
  "value": "PT-30S"
}

EnablementMode

Use enablementMode to represent the state of a feature of an endpoint.

Enablement mode values

The following are the valid enablement mode values:

EnumeratedPowerLevel

Provides a cooking power level from a list of values. A descendant of the polymorphic PowerLevel.

Example EnumeratedPowerLevel

{
  "name": "EnumeratedPowerLevel",
  "value": "MEDIUM"
}

Use featureAvailability to represent whether a feature is available for an endpoint.

Feature availability values

The following are the valid feature availability values:

IntegralPowerLevel

Provides a power level represented as an integer on a number scale. A descendant of the polymorphic PowerLevel.

Example IntegralPowerLevel

{
  "name": "IntegralPowerLevel",
  "value": 5
}

Name

Use name to represent the name of a person.

Name details

Name example

{
    "name": {
      "firstName": "Jane",
      "lastName": "Doe",
      "nickNames": ["Janie"]
    }
}

Percentage

Represent a percentage value. Integer with a valid range of 0-100.

Example percentage

{
 "name": "percentage",
 "value": 74
}

PlaybackState

Use playbackState to indicate the state of an endpoint that plays media.

Example: playbackState:

{
  "name": "playbackState",
  "value": {
    "state": "PLAYING"
  }
}

Playback state values

The following are the valid playback state values:

PowerLevel

Use powerLevel to represent the power level of a device. The powerLevel object contains a type field that identifies the descendant type. The @type field determines the values that you can specify for the powerLevel. The valid types are the following:

• EnumeratedPowerLevel
• IntegralPowerLevel

Example powerLevel that contains an EnumeratedPowerLevel

{
"powerLevel": {
    "@type": "EnumeratedPowerLevel",
    "value": "MEDIUM"
  }
}

Example powerLevel that contains an IntegralPowerLevel

{
"powerLevel": {
    "@type": "IntegralPowerLevel",
    "value": 5
  }
}

PowerState

Use powerState to indicate whether the power to a device is on or off. The valid values are ON or OFF.

Example powerState

{
  "name": "powerState",
  "value": "OFF"
}

Quantity

Use the quantity object to represent an amount of liquid.

Example quantity

"quantity":
{
  "value": 2.5,
  "unit": "MILLILITER"
}

Quantity unit values

You can use the following values for quantity unit. The values are strings.

Range

Use range to represent a range of values.

Example range

{
  "name": "range",
  "value": {
    "minimum": -100,
    "maximum": 100
  }
}

RecordingState

Use recordingState to represent the recording state of an endpoint. The valid values are RECORDING and NOT_RECORDING.

Example RecordingState

{
  "name": "recordingState",
  "value": "RECORDING"
}

Temperature

A structure that contains a value and a scale that is used for properties that represent a temperature.

Example lowerSetpoint temperature

{
    "name": "lowerSetpoint",
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

ThermostatMode

ThermostatMode represents the heating and cooling modes for a thermostat. For the list of valid values, see ThermostatMode Values.

Example

"thermostatMode":
{
  "value": "HEAT"
}

ThermostatMode Values

You can use the following values for ThermostatMode. The values are strings.

TimeInterval

Represents a time duration. A TimeInterval indicates when an operation should start, end and/or how long it should last. One or two of the fields of a time interval can be specified, but if all three are specified, an error will occur.

Example with start and end

{
    "start":"2017-10-04T14:00Z",
    "end":"2017-10-04T14:15Z"
}

Example with start and duration

{
    "start":"2017-10-04T14:00Z",
    "duration":"PT30M"
}

Example with duration only

{
     "duration":"PT30M"
}

The following table lists the supported field combinations, and describes the result. Note that a capability may not support all of the combinations and you should check the documentation for a capability to understand what field combinations you could expect to receive in a directive.

VerificationsRequired

If your device requires user verification for certain directives, use the verificationsRequired property to specify the directives and verification types. The verificationsRequired property contains an array of verification objects, each of which specifies the required verification for a directive.

Currently this property is supported only on the Alexa.ThermostatController and Alexa.PowerController interfaces.

The method object is a polymorphic object that represents a verification method. It contains an @type field that identifies the descendant type. The @type field determines the values that you can specify for the method.

Example VerificationsRequired

For a complete discovery example, see Discover response example for an air conditioner with verification required.

{
  "verificationsRequired": [
    {
      "directive": "SetThermostatMode",
      "methods": [{
        "@type": "Confirmation"
      }]
    },
    {
      "directive": "SetTargetTemperature",
      "methods": [{
        "@type": "Confirmation"
      }]
    }
  ]
}

Volume

Indicates a quantity as a unit of volume in one of several different standard units. Can be a descendant type of the polymorphic FoodQuantity.

Example Volume

The following example shows 1 1/4 liters.

{
"name" : "volume",
  "value": {
      "value": 1.25,
      "unit": "LITER"
  }
}

Volume unit values

Units that are sent from Alexa to a skill:

Additional units Alexa understands:

Weight

Indicates a quantity as a unit of weight or mass in one of several different standard units. Can be a descendant type of the polymorphic FoodQuantity.

Example weight

{
"name" : "weight",
  "value": {
      "value": 1.25,
      "unit": "GRAM"
  }
}

Weight unit values

Units that are sent from Alexa to skills or can be sent to Alexa:

Additional units that Alexa understands:

Alexa Units of Measure

You can use the following units of measure:

• Alexa.Unit.Angle.Degrees
• Alexa.Unit.Angle.Radians
• Alexa.Unit.Distance.Feet
• Alexa.Unit.Distance.Inches
• Alexa.Unit.Distance.Kilometers
• Alexa.Unit.Distance.Meters
• Alexa.Unit.Distance.Miles
• Alexa.Unit.Distance.Yards
• Alexa.Unit.Mass.Grams
• Alexa.Unit.Mass.Kilograms
• Alexa.Unit.Percent
• Alexa.Unit.Temperature.Celsius
• Alexa.Unit.Temperature.Degrees
• Alexa.Unit.Temperature.Fahrenheit
• Alexa.Unit.Temperature.Kelvin
• Alexa.Unit.Volume.CubicFeet
• Alexa.Unit.Volume.CubicMeters
• Alexa.Unit.Volume.Gallons
• Alexa.Unit.Volume.Liters
• Alexa.Unit.Volume.Pints
• Alexa.Unit.Volume.Quarts
• Alexa.Unit.Weight.Ounces
• Alexa.Unit.Weight.Pounds