Capability Property Schemas

This document contains the schemas for properties that are used by the Alexa interfaces. For more information, see List of Alexa Interfaces and Supported Locales.

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

Example property object

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

Example property string

"cookingMode": "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
 }

Channel

Represents a channel as a number or call sign. It is a structure containing number, callSign and affiliateCallSign attributes. Only one of these attributes is required for the channel to be valid. Used by the ChannelController interface.

Field Description Type
number String representing a floating point number that identifies the channel such as 13.1. String
callSign The call sign of the channel such as PBS. String
affiliateCallSign The local affiliate call sign for the channel such as KBTC. String

Example Channel

{
   "name":"channel",
   "value": {
    "number": "6",
    "callSign": "PBS",
    "affiliateCallSign": "KBTC"
  }
}

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.

Field Description Type
hue Indicates the hue attribute of the color. A double that ranges from 0.0 to 360.0, inclusive. Double
saturation Indicates the saturation attribute of the color. A double that ranges from 0.0 to 1.0, inclusive. Double
brightness Indicates the brightness attribute of the color. A double that ranges from 0.0 to 1.0, inclusive. Double

Example color

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

Connectivity

Represents the connectivity state of an endpoint. Used by the EndpointHealth interface.

Field Description Type
value Indicates the status of the endpoint. String enumeration value. Either: OK, UNREACHABLE

Example Connectivity

{
    "name": "connectivity",
    "value":
     {
      "value" : "UNREACHABLE"
     }
}

CookingMode

CookingMode represents the cooking mode for a cooking appliance like a microwave oven. CookingMode can be an object or a string. For the list of valid values, see CookingMode Values.

CookingMode Object Format

You can use the full object format for the CookingMode. You must use the object format to include the optional customName attribute. Smart Home always sends the CookingMode to your lambda function in the object format.

Example object format

"cookingMode":
{
  "value": "TIMECOOK"
}

Example object format with custom name

"cookingMode":
{
  "value": "REHEAT",
  "customName": "QUICK_REHEAT"
}

CookingMode String Format

You can also abbreviate CookingMode as a string instead of an object.

Example string format

"cookingMode": "TIMECOOK"

CookingMode Values

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

Value Description
DEFROST Indicates a cooking appliance's automated defrost mode.
OFF Indicates that a cooking appliance is off.
PRESET Indicates a cooking appliance's preset mode or other automated cooking.
REHEAT Indicates a cooking appliance's automated reheating mode.
TIMECOOK Indicates a time and power level cooking setting.

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"
}

DetectionState

Represents the detection state of a sensor. Used by the MotionSensor and ContactSensor capabilities.

Example Detection

{
  "name": "detectionState",
  "value": "DETECTED"
}

Detection state values

The following are the valid detection state values:

Value Description
DETECTED Indicates that a change in the sensor has been detected.
NOT_DETECTED Indicates that a change in the sensor has not been detected.

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"
}

Enablement Mode

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

Enablement mode values

The following are the valid enablement mode values:

Value Description
ENABLED Indicates that the feature is enabled.
DISABLED Indicates that the feature is disabled.

EnumeratedPowerLevel

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

Field Description Type
value A string enumeration value that indicates the power level. One of the following: LOW, MEDIUM, HIGH String

Example EnumeratedPowerLevel

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

EqualizerBands

Represents equalizer band configurations. EqualizerBands provides a list of bands and their values. Each list element has two fields:

Field Description Type
name The name of the equalizer band supported by the endpoint. String. Supported values: BASS, TREBLE, MIDRANGE.
value The discrete frequency value for the equalizer band. Integer

Example EqualizerBands

This example reports the value of 3 bands.

[
    {
        "name": "BASS",
        "value": -2
    },
    {
        "name": "MIDRANGE",
        "value": 4
    },
    {
        "name": "TREBLE",
        "value": 0
    }
]

EqualizerMode

Represents an equalizer mode. The following modes are supported: MOVIE, MUSIC, NIGHT, SPORT, or TV.

Field Description Type
value The mode or equalizer mode supported by the endpoint. String. Supported values: MOVIE, MUSIC, NIGHT, SPORT, or TV.

Example EqualizerMode

{
  "name": "mode",
  "value": "MUSIC"
}

FeatureAvailability

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

Feature availability values

The following are the valid feature availability values:

Value Description
ENABLED Indicates that the feature is enabled.
DISABLED Indicates that the feature is disabled.
SUBSCRIPTION_REQUIRED Indicates that the feature is available, but the user must purchase a subscription before they can use the feature.

FoodCategory

FoodCategory represents a category of food. You can use the following values for foodCategory. The values are strings.

BEEF, BEVERAGE, CHICKEN, FISH, MEAT, PIZZA, POPCORN, PORK, POTATO, SHRIMP, SOUP, STEAK, TURKEY, VEGETABLE, WATER

FoodCount

Indicates the number of pieces of food. A descendant type of the polymorphic FoodQuantity.

Field Description Type
value Required quantity of food items Number, meaning value can be an integer or a floating point number.

Example food count

{
    "@type": "FoodCount",
    "value": 12
}

FoodItem

Represents a food item. A food item consists of the name specified by the user and the category that Alexa determines for that name. For example, if a user specified "pork chop", the category determined by Alexa would be PORK.

Field Description Type
foodName Indicates the name of the food item specified by the user. String
foodCategory Describes the food category as determined by Alexa. A food category value.
foodQuantity The amount of food to be cooked, specified by count, weight or volume. A food quantity object.

Example FoodItem

{
  "name": "foodItem",
  "value": {
    "foodName": "Copper river salmon",
    "foodCategory": "FISH",
    "foodQuantity": {
      "@type": "Weight",
      "value": "2.5",
      "unit": "POUND"
    }
  }
}

FoodQuantity

Use foodQuantity to represent a quantity of food. Use the @type field to indicate the type of quantity: FoodCount, Volume, or Weight.

Example foodQuantity with count

"foodQuantity":
{
    "@type": "FoodCount",
    "value": 12
}

Example foodQuantity with volume

"foodQuantity":
{
    "@type": "Volume",
    "value": 1.25,
    "unit": "LITER"
},

Example foodQuantity with weight

"foodQuantity":
{
    "@type": "Weight",
    "value": "2.5",
    "unit": "POUND"
},

Input

Represents the input state of an audio or video endpoint. Its value is a string that indicates the input device. Used by the InputController interface.

Example Input

{
  "inputs": [
    {
      "name": "HDMI 1"
    },
    {
      "name": "HDMI 2"
    }
  ]
}

Input values

The following are the valid values for input name:

AUX 1, AUX 2, AUX 3, AUX 4, AUX 5, AUX 6, AUX 7, BLURAY, CABLE, CD, COAX 1, COAX 2, COMPOSITE 1, DVD, GAME, HD RADIO, HDMI 1, HDMI 2, HDMI 3, HDMI 4, HDMI 5, HDMI 6, HDMI 7, HDMI 8, HDMI 9, HDMI 10, HDMI ARC, INPUT 1, INPUT 2, INPUT 3, INPUT 4, INPUT 5, INPUT 6, INPUT 7, INPUT 8, INPUT 9, INPUT 10, IPOD, LINE 1, LINE 2, LINE 3, LINE 4, LINE 5, LINE 6, LINE 7, MEDIA PLAYER, OPTICAL 1, OPTICAL 2, PHONO, PLAYSTATION, PLAYSTATION 3, PLAYSTATION 4, SATELLITE, SMARTCAST, TUNER, TV, USB DAC, VIDEO 1, VIDEO 2, VIDEO 3, XBOX

IntegralPowerLevel

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

Field Description Type
value A number indicating the power level. Integer

Example IntegralPowerLevel

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

LockState

Use lockState to represent the state of a lock.

Example LockState

{
  "name": "lockState",
  "value": "LOCKED"
}

Lock state values

The following are the valid lock state values:

Value Description
LOCKED Indicates that the appliance is currently locked.
UNLOCKED Indicates that the appliances is currently unlocked.
JAMMED Indicates that the lock can't transition to locked or unlocked because the locking mechanism is jammed.

MuteState

Represents the mute state of an audio device. A single boolean value where true indicates the device is muted and false indicates the device is not muted. Used by the Speaker interface.

Example MuteState

{
    "name": "muted",
    "value": false
}

Name

Use name to represent the name of a person.

Name details

Field Description Type
firstName The first name of the person. String
lastName The last name of the person. String
nickNames An array of nicknames for the person. The values are strings. Array

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:

Value Description
PLAYING The endpoint is playing the media.
PAUSED The endpoint paused the media..
STOPPED The endpoint is not playing the media.

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:

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.

Field Description
value The amount of liquid.
unit The unit of the 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.

Value System Description
MILLILITER Metric 1/1000 of a liter.
US_FLUID_OUNCE U.S. Customary 1/128 of a gallon.

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.

Field Description Type
value The temperature. Double
scale The scale of the temperature. A temperature scale string.

Example lowerSetpoint temperature

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

Temperature scales

Value Description
CELSIUS The Celsius temperature scale.
FAHRENHEIT The Fahrenheit temperature scale.
KELVIN The Kelvin temperature scale.

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.

Value Description
AUTO Indicates automatic heating or cooling based on the current temperature and the setpoint.
COOL Indicates cooling mode.
HEAT Indicates heating mode.
ECO Indicates economical mode.
OFF Indicates that heating and cooling is turned off, but the device may still have power.

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.

Field Type Description
start DateTime The start time for this time interval
end DateTime The end time for this time interval
duration Duration The time period of this time interval

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.

Field(s) Result description
start only Makes a change at the specified date/time and continue the change for an indefinite duration. Used to make a settings change at a specified time, and change again when the next regularly scheduled event occurs. If no regularly scheduled event occurs, then change is applied until the user makes another settings change.
end only Make a change to a current setting, and end that change at a specified time. The start time is inferred to be immediate.
duration only The operation begins immediately, or as soon as possible, after the request occurs and continues for the specified duration. When an endpoint can't immediately begin the operation, you should continue the operation for the specified duration from the actual start time, and not from the requested time. In other words, don't include the warm up period for an operation, but only the time once the endpoint begins an operation.
start
and
duration
The operation begins at the specified start date/time and continues for exactly the specified duration
end
and
duration
The operation continues for the specified duration, ending at the specified date/time.

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.

Field Description Type
value The volume in the specified units number
unit An string enumeration value that indicates the unit of measure. A volume unit string.

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:

Unit System Description
LITER Metric ISO Standard unit of volume. Can be sent to Alexa as LITRE.
MILLILITER Metric 1/1000 LITER. Can be sent to Alexa as MILLILITRE.
TEASPOON Metric 5 MILLILITER.
UK_GALLON Imperial Exactly 4.54609 liters
US_FLUID_GALLON U.S. Customary Exactly 3.785411784 liters
US_FLUID_OUNCE U.S. Customary 1/128 US_FLUID_GALLON
US_DRY_GALLON U.S. Customary Exactly 4.40488377086 liters
US_DRY_OUNCE U.S. Customary 1/128 US_DRY_GALLON


Additional units Alexa understands:

Unit System Description
UK_TABLESPOON Metric 15 MILLILITER, also equal to 3 TEASPOON
AU_TABLESPOON Metric 20 MILLILITER, also equal to 4 TEASPOON
CUBIC_CENTIMETER or CUBIC_CENTIMETRE Metric 1 MILLILITER. Note that Alexa recognizes both spellings.
CUBIC_METER or CUBIC_METRE Metric 1000 LITER. Note that Alexa recognizes both spellings.
UK_OUNCE Imperial 1/160 UK_GALLON
UK_QUART Imperial 1/4 UK_GALLON (2 UK_PINT)
UK_PINT Imperial 1/8 UK_GALLON (2 UK_CUP)
UK_CUP Imperial 1/16 UK_GALLON (2 UK_GILL)
UK_GILL Imperial 1/32 UK_GALLON (5 UK_OUNCE)
UK_OUNCE Imperial 1/160 UK_GALLON
UK_DRAM Imperial 1/8 UK_OUNCE
US_FLUID_QUART U.S. Customary 1/4 US_FLUID_GALLON
US_FLUID_PINT U.S. Customary 1/8 US_FLUID_GALLON
US_FLUID_CUP U.S. Customary 1/16 US_FLUID_GALLON
US_TABLESPOON U.S. Customary 1/2 US_FLUID_OUNCE
US_TEASPOON U.S. Customary 1/6 US_FLUID_OUNCE
US_DRAM U.S. Customary 1/8 US_FLUID_OUNCE
US_DRY_QUART U.S. Customary 1/4 US_DRY_GALLON
US_DRY_PINT U.S. Customary 1/8 US_DRY_GALLON
US_DRY_CUP U.S. Customary 1/16 US_DRY_GALLON
CUBIC_INCH Imperial & U.S. Customary Defined as exactly 16.387064 MILLILITER. Also 1/231 US_FLUID_GALLON
CUBIC_FOOT Imperial & U.S. Customary Defined as exactly 28.316846592 LITER. Also 1728 CUBIC_INCH or 576⁄77 US_FLUID_GALLON.

VolumeLevel

Used for properties that represent the audio volume level on a scale from 0 to 100. Its value is a single integer ranging from 0-100. Used by the Speaker interface.

Example VolumeLevel

{
   "name":"volume",
   "value":"50"
}

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.

Field/Value Description Type
value The weight in the specified units. Number
unit An string enumeration value that indicates the unit of measure. A weight unit string.

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:

Unit System Description
GRAM Metric 1/1000 KILOGRAM
KILOGRAM Metric ISO Standard unit of mass/weight
OUNCE Imperial 1/16 POUND.
POUND Imperial Exactly 0.45359237 KILOGRAM


Additional units that Alexa understands:

Unit System Description
METRIC_POUND Metric 500 GRAM
MICROGRAM Metric 1/1000 MILLIGRAM
MILLIGRAM Metric 1/1000 GRAM
OUNCE Imperial 1/16 POUND