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.

      BetaConnectivityStatus Datatype

      (enum) Possible connectivity status values for a device.

      Details

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

      • unknown - The connectivity status has not been reported.
      • online - The connectivity status of the device is online.
      • offline - The connectivity status of the device is offline.

      CardCredentialCreateItem Datatype

      (object) Encapsulates card credential data

      Details

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

      • id (string) - A unique identifier (UUID) to address this card credential.
        • credential (string) - A card credential.

          CardCredentialItem Datatype

          (object) Encapsulates card credential data

          Details

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

          • id (string) - A unique identifier (UUID) to address this card credential.
            • credential (string) - A 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.

                      LockNotification Datatype

                      (object) Notification that the lock has changed states.

                      Details

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

                      • eventType (enum) - What triggered the change in lock state.
                        • This is an enum datatype and must be one of the following strings:
                          • autoRelock - The lock automatically locked after a preset delay.
                          • oneTouchLocking - A button on the lock was pressed.
                          • thumbturn - The lock was manually turned.
                          • virtualKey - An command was received from the cloud, such as from a mobile app.
                      • isLocked (boolean) - Whether the lock is locked after the auto relock

                        PinCodeAlreadyExistsNotificationDatatype Datatype

                        (object) Notification that a PIN code cannot be saved because it is not unique.

                        Details

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

                        • pinCode (string) - The PIN Code that was already in use.

                          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.

                              PinCodeCredentialCreateItem Datatype

                              (object) Encapsulates PIN code credential data

                              Details

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

                              • id (string) - A unique identifier to address this PIN code credential.
                                • pinCode (string) - A PIN code.
                                  • 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.

                                      PinCodeCredentialItem Datatype

                                      (object) Encapsulates PIN code credential data

                                      Details

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

                                      • id (string) - A unique identifier to address this PIN code credential.
                                        • pinCode (string) - A PIN code.
                                          • 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.

                                              PinCodeCredentialListItem 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.
                                                • 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.

                                                    PinCodeInUseNotification Datatype

                                                    (object) Notification that a PIN code cannot be saved because it is not unique.

                                                    Details

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

                                                    • pinCode (string) - The PIN Code that was already in use.

                                                      PinCodeNameAlreadyExistsNotificationDatatype Datatype

                                                      (object) Notification that a PIN code name cannot be saved because it is not unique.

                                                      Details

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

                                                      • name (string) - The PIN Code name that was already in use.

                                                        PinCodeNameInUseNotification Datatype

                                                        (object) Notification that a PIN code name cannot be saved because it is not unique.

                                                        Details

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

                                                        • name (string) - The PIN Code name that was already in use.

                                                          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.
                                                                  • emergencyHeat - The thermostat is in emergency heat 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).

                                                                      UpdateAvailability Datatype

                                                                      (enum) The various possible update availabilities for a device.

                                                                      Details

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

                                                                      • available - An update is available for this device.
                                                                      • unavailable - No update available for this device.
                                                                      • unknown - An updateAvailability state has not been reported.
                                                                      • unsupported - This device does not support this trait.