Capability Property Schemas Reference

This reference contains the definitions for properties shared by Alexa capability interfaces.

How to represent properties

Alexa interfaces define most capability properties as strings, integers, or objects.

String property example

"cookingMode": "BAKE"

Integer property example

 "value": 45

Object property examples

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

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

Brightness

Indicates the brightness of an appliance, such as a smart light bulb. Valid values are integers from 0 – 100, inclusive.

Brightness example

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

Color

Object that represents 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

Color example

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

Count example

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

DateTime

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

DateTime example

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

Duration

The Duration property represents a period of time 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.

Three minute and 15 second duration example

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

Delta of –30 seconds example

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

Percentage

Use percentage to represent an amount as a percent. Integer with a valid range of 0 – 100.

Percentage example

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

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.

lowerSetpoint temperature example

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

ThermostatMode example

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

ThermostatMode values

The following table shows the mode values for thermostats. A thermostat might not support all modes.

Value	Description
`AUTO`	Automatic heating or cooling based on the current temperature and the setpoint.
`COOL`	Cooling mode.
`ECO`	Economy mode.
`EM_HEAT`	Emergency heating mode. This mode uses a backup heat source as an additional heat source. For example, a customer might use emergency heat in extreme cold or when the heat pump is broken. Customers can set this mode in device settings in the Alexa app.
`HEAT`	Heating mode.
`OFF`	Heating and cooling are 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. A capability might not support all the combinations. You should check the documentation for a capability to understand what field combinations you can 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, the 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 example

The following example shows 1 1/4 liters.

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

Volume unit values

The following table shows the valid values for volume units.

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.
`METRIC_CUP`	Metric	250 MILLILITER.
`METRIC_TEASPOON`	Metric	5 MILLILITER.
`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.
`CUBIC_INCH`	Imperial and U.S. Customary	Defined as exactly 16.387064 MILLILITER. Also 1/231 US_FLUID_GALLON
`CUBIC_FOOT`	Imperial and U.S. Customary	Defined as exactly 28.316846592 LITER. Also 1728 CUBIC_INCH or 576/77 US_FLUID_GALLON.
`CUBIC_YARD`	Imperial and U.S. Customary	Defined as exactly 764.55 LITER. Also 27 CUBIC_FOOT or 201.974029 US_FLUID_GALLON
`UK_GALLON`	Imperial	Exactly 4.54609 liters
`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_FLUID_OUNCE)
`UK_FLUID_OUNCE`	Imperial	1/160 UK_GALLON
`UK_OUNCE`	Imperial	1/160 UK_GALLON
`UK_DRAM`	Imperial	1/8 UK_FLUID_OUNCE
`US_FLUID_GALLON`	U.S. Customary	Exactly 3.785411784 liters
`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_FLUID_OUNCE`	U.S. Customary	1/128 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_GALLON`	U.S. Customary	Exactly 4.40488377086 liters
`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
`US_DRY_OUNCE`	U.S. Customary	1/128 US_DRY_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 example

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

Weight unit values

The following table shows the unit values 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
`METRIC_POUND`	Metric	500 GRAM
`MICROGRAM`	Metric	1/1000 MILLIGRAM
`MILLIGRAM`	Metric	1/1000 GRAM

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

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Capability Property Schemas Reference

How to represent properties

String property example

Integer property example

Object property examples

Brightness

Brightness example

Color

Color example

Count

Count example

DateTime

DateTime example

Duration

Three minute and 15 second duration example

Delta of –30 seconds example

Percentage

Percentage example

Temperature

lowerSetpoint temperature example

Temperature scales

ThermostatMode

ThermostatMode example

ThermostatMode values

TimeInterval

Volume

Volume example

Volume unit values

Weight

Weight example

Weight unit values

Alexa units of measure

​How to represent properties

​String property example

​Integer property example

​Object property examples

​Brightness

​Brightness example

​Color

​Color example

​Count

​Count example

​DateTime

​DateTime example

​Duration

​Three minute and 15 second duration example

​Delta of –30 seconds example

​Percentage

​Percentage example

​Temperature

​lowerSetpoint temperature example

​Temperature scales

​ThermostatMode

​ThermostatMode example

​ThermostatMode values

​TimeInterval

​Volume

​Volume example

​Volume unit values

​Weight

​Weight example

​Weight unit values

​Alexa units of measure

​Related topics

How to represent properties

String property example

Integer property example

Object property examples

Brightness

Brightness example

Color

Color example

Count

Count example

DateTime

DateTime example

Duration

Three minute and 15 second duration example

Delta of –30 seconds example

Percentage

Percentage example

Temperature

lowerSetpoint temperature example

Temperature scales

ThermostatMode

ThermostatMode example

ThermostatMode values

TimeInterval

Volume

Volume example

Volume unit values

Weight

Weight example

Weight unit values

Alexa units of measure

Related topics