Capability Property Schemas

This document contains schemas for properties used by the Alexa interfaces.

Overview

Many properties can be expressed as either 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 value is an integer 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. One of the following: LOW, MEDIUM, HIGH String

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

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
}

PlaybackState

Use playbackState to indicate the state of an endpoint that plays media.

Example: playbackState:

{
  "name": "playbackState",
  "value": {
    "state": "PLAYING"
  }
}

Playback state values

The following are the valid playback state values:

Value Description
PLAYING The endpoint is playing the media.
PAUSED The endpoint paused the media.
STOPPED The endpoint is not playing the media.

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

RecordingState

Use recordingState to represent the recording state of an endpoint. The valid values are RECORDING and NOT_RECORDING.

Example RecordingState

{
  "name": "recordingState",
  "value": "RECORDING"
}

Temperature

A structure that contains a value and a scale that's 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 economical 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. One or two of the fields of a time interval can be specified, but if all three are specified, an error will occur.

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 may not support all of 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(s) 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, you should 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, but only the time once the endpoint begins an operation.
start
and
duration		 The operation begins at the specified start date/time and continues for exactly the specified duration
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 An string enumeration value that indicates the unit of measure. A volume unit string.

Example Volume

The following example shows 1 1/4 liters.

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

Volume unit values

Units that are 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/Value Description Type
value The weight in the specified units. Number
unit An string enumeration value that indicates the unit of measure. A weight unit string.

Example weight

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

Weight unit values

Units that are sent from Alexa to skills or can be sent to Alexa:

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