Deine Alexa Konsolen
?
Support
Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Capability Property Schemas

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 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.

Example when a customer specifies one dozen:

{
    "@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. 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
}

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. LockState is a string enumeration that contains the following 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
}

PlaybackState

Defines a single property, state, which represents the playback state of an endpoint. Valid values for state are: PLAYING, PAUSED, STOPPED.

Example: playbackState:

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

PowerState

Represents the power state of a device. PowerState is an enumeration that contains two 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
 }
}

RecordingState

Represents the recording state of an endpoint. RecordingState is an enumeration that contains two string values:

  • RECORDING
  • 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/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

Represents the mode of a thermostat. Valid values are strings, and listed in the table that follows.

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

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

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.

Example with start

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

Example with start and duration

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

Example with duration

{
     "duration":"PT30M"
}

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