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": "TIMECOOK"

Integer property example

 "value": 45

Object property example

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

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

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

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.

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

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