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.