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
, ornull
- a nullable<string> datatype could contain values of
"foo"
,"bar"
, ornull
- a nullable<range<int>> datatype could contain values of
{ "min": 0, "max": 100 }
ornull
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 insway
mode.wind
- The fan is inwind
mode.health
- The fan is inhealth
mode.humidity
- The fan is inhumidity
mode.eco
- The fan is ineco
mode.energy
- The fan is inenergy
mode.fresh
- The fan is infresh
mode.taste
- The fan is intaste
mode.low
- The fan is on thelow
setting.medium
- The fan is on themedium
setting.high
- The fan is on thehigh
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.
- This is an enum datatype and must be one of the following strings:
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 indehumidify
mode.airflow
- The thermostat is inairflow
mode.emergencyHeat
- The thermostat is inemergency 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.