The schema describes the underlying data model that drives the representation and interpretation of the data emitted by logical or physical devices in a Weave system.
The schema is:
- Standardized — It contains formally-approved definitions of functionality that provide a consistent interface, regardless of implementation. For example, a light bulb represented in the schema will always have core functionality such as on/off states and actions or levels of dimming.
- Composable — A user can create complex resources comprised of smaller bits of well-defined functionality. For example, a Nest Detect contains two types of sensors: motion and open/close. The functionality for these sensor types are standardized in the schema and reusable across devices.
- Extensible — A user can create custom extensions of standard functionality. For example, you might want to extend the schema's standard motion sensor functionality with additional functionality for a specific security application.
- Versioned — All changes in schema are versioned for forwards and backwards compatibility.
The schema defines three elements: traits, interfaces, and resources. Almost all functionality in the Nest ecosystem for everyday operation is defined in the schema. Let's go over each element in more depth.
Traits
A trait is a unit of basic functionality. They might be general device states or capabilities, or describe the configuration that informs its behavior. A single trait might be common to many devices, or specific to one type of device.
For example, in the schema you might define the following traits for use in Nest devices:
Interfaces
We can extend the composability of traits by grouping them together, particularly if multiple traits represent a new, specific function. Such a group of traits is called an interface .
For example, an Intercom interface might comprise Speaker and Microphone traits:
Resources
A resource represents a logical or physical thing in the schema. For example, a Nest Protect is a resource. So is a Nest Guard. Or a user, or a structure such as the user's home.
Resources comprise a set of traits that encapsulate their configuration, state, and capability.
The relationship between resources, interfaces, and traits looks like this:
As you can see, some traits, like the Motion trait, are common to different resources. And some interfaces, like the Intercom interface, are also common to different resources. Traits, interfaces, and resources are defined once in the schema and reused across different resources and devices in the Weave system.
Trait elements
Traits are further broken down into three primary elements: properties, commands, and events. Let's take a look at examples of each trait element.
Properties
Properties represent the state of a trait. Properties are either read-write or read-only.
For example:
- Software Version is a property of the Device Identity trait. It's a general trait that most devices have. Nest Thermostats, Cameras, and Protects—all of these have their own particular software version.
- Bolt State is a property of the Bolt Lock trait, but is specific to a device like the Yale x Nest Lock. You wouldn't find a bolt lock on a Nest Thermostat, for example.
Commands
Commands are trait-specific custom requests for action of a trait, with an expected response. They are commonly called custom commands and can be extended to specific state changes for properties. For example:
- Bolt Lock Change is a custom command that changes the Bolt State property of the Bolt Lock trait.
- Set User Pincode is a custom command that creates a new or updates an existing User Pincode property of the User Pincodes Settings trait.
Events
Events are records of happenings for a trait. They inform a subscriber of changes in trait properties or some other type of happening, such as a system reset.
For example, the Bolt Actuator State Change event of the Bolt Lock trait informs a subscriber of the current state of multiple Bolt Lock properties, as well as the actor who last caused the Bolt Actuator State property to change. All of this information is delivered as a single event.
Weave Schema Description Language
The schema traits, interfaces, and resources in Weave are defined and described using a domain-specific language (DSL) that leverages the syntax of Google Protocol Buffers v3. This language is called Weave Schema Description Language (WDL) .
WDL is run through a compiler that generates different platform-specific realizations and encodings. The type of code generated depends on the resource:
- Objective-C, Swift, Java, Scala — mobile apps and cloud services
- C++ with Weave TLV encodings — embedded devices and mobile apps
We'll delve deeper into WDL examples later.
Recap
What you learned:
- The schema describes the underlying data model for a Weave system.
- The schema defines three elements:
- Trait A unit of basic functionality
- Interface A group of traits that represent a new, specific function
- Resource A logical or physical thing
- Traits comprise properties, commands, and events:
- Property The state of a resource trait
- Commands Custom request for action of a trait
- Event Record of happenings for a trait
- The schema is defined using Weave Schema Description Language (WDL) , which is based on Google Protocol Buffers v3
For more in-depth information, see: