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 examples

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

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

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, 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
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
Was this page helpful?

Last updated: Mar 01, 2024