Trait Datatypes

This is the reference documentation for the datatypes used in Traits at Yonomi. For a comprehensive reference to all traits, properties, actions, and states, see the Traits Reference documentation. For a more detailed walk-through of how you can interact with your devices via Traits, see the Traits Overview Guide.

Basic Datatypes

The following datatypes are the basic types that power Traits.

boolean Datatype

The boolean datatype is a boolean value.

Examples

  • true
  • false

int Datatype

The int datatype is any whole number.

Examples

  • 55
  • 0
  • -5

float Datatype

The float datatype is any number.

Examples

  • 3
  • 3.14
  • -55

string Datatype

The string datatype is any string.

Examples

  • "Hello, World!"
  • "Hello\nEarth!"
  • ""

enum Datatype

The enum datatype is exactly like a string, except it can only be one of a specific set of values. The allowed values are defined within the definition document where it is referenced.

Examples

There are examples of enum datatypes in the Datatype Reference documentation.

object Datatype

The object datatype is any object with keys defined with specific datatypes themselves. The HSBColorValue compound datatype is an example of this.

Examples

  • { "foo": 123 }
  • { "type": "hsb", "h": 240, "s": 75, "b": 50 }

rrule Datatype

The rrule datatype is a string that represents an RFC 5545 recurrence rule string (https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html). The recurrence rule is one of many features of the broader iCalendar specifications and therefore only enables a subset of scheduling functionality. Currently, we do not support hh:mm time ranges that do not start or end at the top of the hour. For example,

  • Supported Monday through Friday from 12:00 to 13:00 - RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,FR;BYHOUR=12
  • Not supported - Monday through Friday from 12:45 to 17:30

nullable Datatype

The nullable datatype is a parametric datatype (a datatype that takes another datatype as a parameter) that is used whenever a value can either be a specific datatype, or null.

Examples

  • a nullable<float> datatype could contain values of 5, -5, or null
  • a nullable<string> datatype could contain values of "foo", "bar", or null
  • a nullable<range<int>> datatype could contain values of { "min": 0, "max": 100 } or null

range Datatype

The range datatype is a parametric datatype (a datatype that takes another datatype as a parameter) representing a range of numbers, and can accept either int or float types.

The range expressed by this datatype is inclusive.

It is represented as an object with a min and a max property.

Examples

  • { "min": 0, "max": 100 } - a range<int> datatype
  • { "min": -0.5, "max": 0.5 } - a range<float> datatype

set Datatype

The set datatype is a parametric datatype (a datatype that takes another datatype as a parameter) that is effectively an array with no duplicated items.

It is possible to have a set datatype over int, float, string, or enum types.

Examples

  • [1, 2, 5] - a set<int> datatype
  • ["foo", "bar", "baz"] a set<string> datatype
  • INCORRECT: [1, 2, 3, 3] an invalid set, cannot repeat items

list Datatype

The list datatype is a parametric datatype (a datatype that takes another datatype as a parameter) that is a collection of key-value items uniquely identified and referenceable by key.

The type of the key must be a string, while the type of the value may be any of the available datatypes.

Examples

  • { "a": "foo", "b": "baz" } - a list<string> datatype
  • { "123": { "a": "foo" }, "234": { "b": "bar" } } - a list<object> datatype
  • INCORRECT { "123": "foo", "123": "bar" } - an invalid list, cannot have items with the same key

union Datatype

A union datatype is used whenever a value can be exactly one of multiple datatypes. This is used whenever a single value can be modeled in one of several ways.

Examples

See the ColorValue datatype, which is a union of all the various color value representations.

literal Datatype

The literal datatype is just a string that can only ever take a single value. It is use as a “tag” of sorts, generally to distinguish object payloads in union types.

Examples

See the HSBColorValue and TemperatureColorValue compound datatypes, which use a literal datatype for the tag key in order to distinguish between the different representations of colors in the ColorValue datatype.

Compound Datatypes

In addition to the above basic datatypes, there are compound, named datatypes that are implemented to better capture frequently-used types across the traits system.

BatteryStatus Datatype

(enum) The various possible battery statuses for a device.

Details

This is an enum datatype and must be one of the following strings:

  • unknown - The battery status has not been reported.
  • normal - The battery on this device is at a normal level of charge.
  • low - The battery on this device is at a low level of charge.
  • critical - The battery on this device is at a critically low level of charge.

BetaCardCredential Datatype

(object) Encapsulates card credential data

Details

This is a object datatype, which is an object with the following properties:

  • credential (string) - A card credential.
    • id (string) - A unique identifier (UUID) for the card credential.

      DynamicFloatRange Datatype

      (object) This represents a range of floating point numbers with min and max values that are dynamic.

      Details

      This is a object datatype, which is an object with the following properties:

      • min (float) - The minimum floating point number value allowed.
        • max (float) - The maximum floating point number value allowed.

          DynamicIntRange Datatype

          (object) This represents a range of integers with min and max values that are dynamic.

          Details

          This is a object datatype, which is an object with the following properties:

          • min (int) - The minimum integer value allowed.
            • max (int) - The maximum integer value allowed.

              FanMode Datatype

              (enum) The various possible fan modes for a device.

              Details

              This is an enum datatype and must be one of the following strings:

              • on - The fan is always on.
              • auto - The fan runs when needed.
              • circulate - The fan runs in order circulate air.
              • sway - The fan is in sway mode.
              • wind - The fan is in wind mode.
              • health - The fan is in health mode.
              • humidity - The fan is in humidity mode.
              • eco - The fan is in eco mode.
              • energy - The fan is in energy mode.
              • fresh - The fan is in fresh mode.
              • taste - The fan is in taste mode.
              • low - The fan is on the low setting.
              • medium - The fan is on the medium setting.
              • high - The fan is on the high setting.

              HSBColorValue Datatype

              (object) Represents a color in terms of its hue, saturation, and brightness.

              Details

              This is a object datatype, which is an object with the following properties:

              • h (int) - The value of the hue attribute for this color.
                • Value must be between 0 and 359, inclusive.
              • s (int) - The value of the saturation percentage attribute for this color.
                • Value must be between 0 and 100, inclusive.
              • b (int) - The absolute brightness percentage value for this color.
                • Value must be between 0 and 100, inclusive.

              LightEffects Datatype

              (enum) The various possible light effects for a device

              Details

              This is an enum datatype and must be one of the following strings:

              • brightnessWithTransition - The device can change it’s brightness over a transition period.
              • colorWithTransition - The device can change it’s color over a transition period.
              • colorTempWithTransition - The device can change it’s color temperature over a transition period.

              PinCodeCredential Datatype

              (object) Encapsulates PIN code credential data

              Details

              This is a object datatype, which is an object with the following properties:

              • pinCode (string) - A PIN code. This is also the unique identifier for the PIN code credential data.
                • name (string) - A human-readable name for the PIN code credential data.
                  • schedules (set<rrule>) - A set of schedules by which the device may be accessed via the PIN code credential.
                    • This is a set datatype, which is an array (of rrule items) that cannot have any repeated items.

                  PinCodeCredentialItem Datatype

                  (object) Encapsulates PIN code credential data

                  Details

                  This is a object datatype, which is an object with the following properties:

                  • pinCode (string) - A PIN code. This is also the unique identifier for the PIN code credential data.
                    • name (string) - A human-readable name for the PIN code credential data.
                      • alwaysActive (boolean) - Indicates that the PIN code credential should always permit access.
                        • recurringSchedules (set<RecurringSchedule>) - list of schedules that detail a repeated pattern when the PIN code credential should allow access.
                          • This is a set datatype, which is an array (of RecurringSchedule items) that cannot have any repeated items.
                          • See the RecurringSchedule datatype documentation.
                        • temporarySchedules (set<TemporarySchedule>) - A set of schedules that provide one-time access using this PIN code credential.
                          • This is a set datatype, which is an array (of TemporarySchedule items) that cannot have any repeated items.
                          • See the TemporarySchedule datatype documentation.

                        RecurringSchedule Datatype

                        (object) A schedule that repeats based on an RRULE recurrance pattern.

                        Details

                        This is a object datatype, which is an object with the following properties:

                        • duration (int) - The number of minutes the schedule should last for. Begins at every time specified by a recurrance rule.
                          • rrule (rrule) - Repetition rule that describes when the defined schedule repeats.

                            TemporarySchedule Datatype

                            (object) A schedule that grants access only within the start date-time and end date-time.

                            Details

                            This is a object datatype, which is an object with the following properties:

                            • startDatetime (datetime) - The ISO 8601 compliant start date of the schedule.
                              • endDatetime (datetime) - The ISO 8601 compliant end date of the schedule.

                                ThermostatMode Datatype

                                (enum) The various modes a thermostat can be set to.

                                Details

                                This is an enum datatype and must be one of the following strings:

                                • off - All activity is suspended.
                                • auto - Both heating and cooling mode can engage in order to support keeping the temperature within a specific range.
                                • heat - The heater can engage.
                                • cool - The A/C can engage.
                                • fanonly - Neither the heater nor A/C is engaged, but the fan is running.
                                • dehumidify - The thermostat is in dehumidify mode.
                                • airflow - The thermostat is in airflow mode.

                                ThermostatRange Datatype

                                (object) The range of a thermostat in auto mode.

                                Details

                                This is a object datatype, which is an object with the following properties:

                                • setPointLow (float) - The low temperature, in Celsius, to set on the device while in a TargetTemperatureRange mode (auto).
                                  • setPointHigh (float) - The high temperature, in Celsius, to set on the device while in a TargetTemperatureRange mode (auto).