Capability Property Schemas

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

This reference contains schemas for capability properties used by the Alexa interfaces.

How to express properties

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

Note: When a specified 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

Note: When a specified 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:

EnumeratedPowerLevel
IntegralPowerLevel

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.

Note: When a specified 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.

Note: When a specified 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