Weave Schema

Weave Schema

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 grain 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:

Trait

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 group_work.

For example, an Intercom interface might comprise Speaker and Microphone traits:

Traits and Interfaces

Resources

A resource all_out 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:

Resources, Interfaces, and Traits

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 adjust 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 center_focus_weak 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 control_camera 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) storage.

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 list_alt describes the underlying data model for a Weave system.
  • The schema defines three elements:
    • Trait grain A unit of basic functionality
    • Interface group_work A group of traits that represent a new, specific function
    • Resource all_out A logical or physical thing
  • Traits comprise properties, commands, and events:
    • Property adjust The state of a resource trait
    • Commands center_focus_weak Custom request for action of a trait
    • Event control_camera Record of happenings for a trait
  • The schema is defined using Weave Schema Description Language (WDL) storage, which is based on Google Protocol Buffers v3

For more in-depth information, see: