?
Support

Property Schemas for State Reporting

This document contains the schemas for property values that are used to indicate state changes.

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/Value 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
    }
}

ColorTemperatureInKelvin

The ColorTemperature schema is used for properties that represent the color temperature of an endpoint. It an integer with a valid range from 1000 to 10000 inclusive, indicating the color temperature in degrees Kelvin. Used by endpoints that support tunable white light.

Some example customer requests and resulting kelvin values:

Shades of White colorTemperatureInKelvin value
warm, warm white 2200
incandescent, soft white 2700
white 4000
daylight, daylight white 5500
cool, cool white 7000

Example colorTemperatureInKelvin

{
    "name": "colorTemperatureInKelvin",
    "value": 7500
}

CookingMode

Represents the a cooking mode for a cooking appliance like a microwave oven. CookingMode is an enumeration with the following valid values:

Field/Value Description
DEFROST Indicates a cooking appliance’s automated defrost mode.
OFF Indicates 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.

Example TIMECOOK mode

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

Example OFF

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

Connectivity

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

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

Example Connectivity

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

DateTime

Represents a specific date and time in Coordinated Universal Time (UTC). The DateTime is a string in ISO 8601 date and time format, with the RFC 3339 variant applied. DateTime strings are always specified in UTC with no offsets, like the following “YYYY-MM-DDTHH:MM:SSZ”.

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 as follows: PTHHMMSSS

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.

Following is an example of a 3 minute, 15 second duration: PT3M15S

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

The following shows a duration that represents a delta of -30 seconds.

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

EnumeratedPowerLevel

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

Field/Value 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"
}

FoodCount

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

Field/Value Description Type
value Required quantity of food items Number, meaning value can be an integer or a floating point number.
size Optional string enumeration value that indicates the size of the units described. The meaning of this property depends on the customer’s locale. String value from the Size Enumeration

Example when a customer specifies one dozen:

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

Example object notation when a customer specifies one dozen, large

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

FoodCount.Size Enumeration

Value Description for selected food items
EXTRA_EXTRA_LARGE In Australia, used for eggs that weigh 71.7 - 78.5 grams (same as King and Mega)
JUMBO Eggs: In US/Canada, weight more than 2.5 oz or 70 grams
EXTRA_LARGE Eggs: US/Canada, weight more than 2.25 oz or 63 grams
Potato: US, diameter of 2 3/4 to 4 1/2 inches, same as “Chef” size
LARGE Eggs: In US/Canada, weight more than 2 oz or 56 grams
Whole Chicken: US/Canada, same as “Roaster”
Potato: In US, diameter of 3 to 4 1/2 inches
MEDIUM Eggs: In US/Canada, describes eggs that weigh more than 1.75 oz or 49 grams
Whole Chicken: In US/Canada, same as “Broiler”
Potato: In US, diameter between 2 1/4 and 3 1/4 inches
SMALL Eggs: In US/Canada, describes eggs with weight more than 1.5 oz. or 42 grams
Whole Chicken: In US/Canada, same as “Fryer”
Potato: In US, diameter between 1 3/4 and 2 1/2 inches
EXTRA_SMALL In US/Canada, describes eggs with weight more than 1.25 oz. or 42 grams (same as Peewee)
Whole Chicken: Indicates a juvenile chicken or Poussin
Potato: In US, a diameter between 3/4 and 1 5/8 inches, also known as “Creamer”
SIZE_A Potato: In US, diameter greater than 1 7/8 inches
SIZE_B Potato: In US, diameter between 1 1/2 and 2 1/4 inches

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. Used by the Cooking.

In addition, a FoodItem contains a foodQuantity, which is the number of items of food, or the food by weight or volume.

Field/Value Description Type
foodName Indicates the name of the food item specified by the user. String
foodCategory Describes the food category as determined by Alexa String enumeration value. One of the following values: BEEF, BEVERAGE, CHICKEN, FISH, MEAT, PASTA, PIZZA, POPCORN, PORK, POTATO, SHRIMP, SOUP, TURKEY, WATER, UNKNOWN
foodQuantity The amount of food to be cooked, which can be specified by count, weight or volume. A descendant of the polymorphic FoodQuantity; either FoodCount, Weight or Volume. Specify the type of object the field contains with the @type field.

Example FoodItem

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

FoodQuantity

A polymorphic type for indicating a quantity of food. When a FoodQuantity is described, it contains a @type field that identifies the food quantity type. Use the @type value to determine the other fields that you can expect for that foodQuantity. FoodQuantity can have the following descendants:

Example FoodQuantity

The following example shows a foodQuantity type that contains a Weight.

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

The following example shows a foodQuantity type that contains a FoodCount

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

The following example shows a foodQuantity type that contains a Volume

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

Input

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

Example Input

{
    "name": "input",
    "value": "HDMI1"
}

IntegralPowerLevel

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

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

Example IntegralPowerLevel

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

LockState

The LockState schema is used for properties that represent the state of a lock. It is a string with the following valid values:

Field/Value Description
LOCKED Indicates that the appliance is currently locked.
UNLOCKED Indicates that the appliances is currently unlocked.
JAMMED Indicates that the lock cannot complete its transition to “LOCKED” or “UNLOCKED” because the locking mechanism is jammed.

Example LockState

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

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
}

Percentage

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

Example percentage

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

PowerState

Represents the power state of a device. Two valid string values:

  • “ON”
  • “OFF”

Example powerState

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

PowerLevel

A polymorphic type for representing a power level. When a powerLevel is described, it contains a @type field that identifies the descendant type. Use the @type field to determine the other values you can expect for that powerLevel. PowerLevel can contain one of the following descendant types:

Example PowerLevel that contains an EnumeratedPowerLevel

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

Example PowerLevel that contains an IntegralPowerLevel

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

Temperature

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

Field/Value Description
value An double representing the numerical temperature value in the scale specified.
scale String either “CELSIUS”, “FAHRENHEIT” or “KELVIN”

Example lowerSetpoint temperature

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

ThermostatMode

Used for properties that represent the mode of a thermostat. Valid values are strings, and listed in the table that follows. When ThermostatMode is “CUSTOM”, you must provide an addition field, customName.

Field/Value Description
AUTO Automatic heat or cool selection based on the temperature reading and the setpoint
COOL cooling mode
HEAT heating mode
ECO economical mode
OFF heating/cooling is turned off, but the device may still have power
CUSTOM A custom mode specified by an additional field customName
customName String indicating a custom mode or friendly name specific to the endpoint or manufacturer.

The customName attribute specifies a friendly name for the custom temperature mode. The value for this field is specific to your implementation/device and you must contact Amazon to provide a custom name.

customName is required when value is set to CUSTOM, optional otherwise. When used with a predefined mode such as AUTO, the customName specifies a manufacturer’s preferred name for the mode. When used with the CUSTOM mode, customName specifies a manufacturer’s custom mode for the thermostat that is not already represented by other modes.

Example

{
    "name": "thermostatMode",
    "value": "AUTO"
}

Example customName with Predefined Mode:

{
  "name": "thermostatMode",
  "value": {
    "value": "AUTO",
    "customName": "VENDOR_HEAT_COOL"
  }
}

Example with CUSTOM, customName:

{
  "name": "thermostatMode",
  "value": {
    "value": "CUSTOM",
    "customName": "VENDOR_HEAT_COOL"
  }
}

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/Value Description Type
value The volume in the specified units number
unit An string enumeration value that indicates the unit of measure. String value from Volume.Unit

Volume.Unit Enumeration

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.

Example Volume

The following example shows how you might represent 1 1/4 liters.

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

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.   String value from Weight.Unit

Weight.Unit Enumeration

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

Example for 1 1/4 grams

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