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. It is a structure containing hue, saturation and brightness fields, which are each double precision numbers. For use by endpoints that are able to change color.

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

EnumeratedPowerLevel

Provides a cooking power level from a list of values. A descendant of the polymorphic PowerLevel.

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:

IntegralPowerLevel

Provides a power level represented as an integer on a number scale. A descendant of the polymorphic PowerLevel.

Example IntegralPowerLevel

{
  "name": "IntegralPowerLevel",
  "value": 5
}

Name

Use name to represent the name of a person.

Name details

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:

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.

Example quantity

"quantity":
{
  "value": 2.5,
  "unit": "MILLILITER"
}

Quantity unit values

You can use the following values for quantity unit. The values are strings.

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 is used for properties that represent a temperature.

Example lowerSetpoint temperature

{
    "name": "lowerSetpoint",
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

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.

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.

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.

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.

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:

Additional units Alexa understands:

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.

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:

Additional units that Alexa understands:

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