Capability Property Schemas
This document contains schemas for properties used by the Alexa interfaces.
Overview
You can express most properties as 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 values are integers from 0 – 100, inclusive.
Example brightness
{
"name": "brightness",
"value": 45
}
Color
Used for properties that represent the color of an endpoint. The structure includes 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
}
}
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 value 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:
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. Valid values: LOW , MEDIUM , HIGH |
String |
EnumeratedPowerLevel
is a descendant of a polymorphic type, the first field is a JSON @type
indicator. See PowerLevel for an example.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:
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. |
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 |
IntegralPowerLevel
is a descendant of a polymorphic type, the first field is a JSON @type
indicator. For an example, see PowerLevel.Example IntegralPowerLevel
{
"name": "IntegralPowerLevel",
"value": 5
}
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
}
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. |
Range
Use range
to represent a range of values.
Example range
{
"name": "range",
"value": {
"minimum": -100,
"maximum": 100
}
}
Temperature
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 economy mode. |
OFF |
Indicates that heating and cooling is off, but the device might still have power. |
TimeInterval
Represents a time duration. A TimeInterval
indicates when an operation should start, end and/or how long it should last. Specify one or two of the time interval fields. If you specify all three fields, an error occurs.
Field | Type | Description |
---|---|---|
start |
DateTime | The start time for this time interval |
end |
DateTime | The end time for this time interval |
duration |
Duration | The duration 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 might not support all 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 | 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, 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. |
start and duration |
The operation begins at the specified start date/time and continues for the specified duration exactly. |
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 |
A string enumeration value that indicates the unit of measure. | A volume unit string. |
Volume
is a descendant of a polymorphic type, the first field is a JSON @type
indicator. For an example, see FoodQuantity.Example Volume
The following example shows 1 1/4 liters.
{
"name" : "volume",
"value": {
"value": 1.25,
"unit": "LITER"
}
}
Volume unit values
Units 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. |
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 | Description | Type |
---|---|---|
value |
The weight in the specified units. | Number |
unit |
A string enumeration value that indicates the unit of measure. | A weight unit string. |
weight
is a descendant of a polymorphic type, the first field is a JSON @type
indicator. For an example, see FoodQuantity.Example weight
{
"name" : "weight",
"value": {
"value": 1.25,
"unit": "GRAM"
}
}
Weight unit values
Units that represent weight:
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 |
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