Capabilities & Schemas

Hi there,

I work on Mozilla's Web of Things implementation over at iot.mozilla.org.
Apart from our open source gateway <https://github.com/mozilla-iot/gateway>
implementation which bridges existing smart home devices to the web, we now
also have a framework <https://iot.mozilla.org/things/> of re-usable
software libraries to create web things themselves using Python
<https://github.com/mozilla-iot/webthing-python>, NodeJS
<https://github.com/mozilla-iot/webthing-node>, Java
<https://github.com/mozilla-iot/webthing-java>, C++
<https://github.com/mozilla-iot/webthing-esp8266>, with a Rust library
coming soon.

These WoT implementations all expose the Web Thing API
<https://iot.mozilla.org/wot/> which, although isn't exactly the same as
the current W3C WoT Working Group's specifications, the JSON Thing
Description format is very similar to the latest Simplified WoT Thing
Description
<https://w3c.github.io/wot-thing-description/proposals/simplified-td>
proposal so we hope to gradually converge on a standard along those lines
as it emerges.

We've recently been discussing a capabilities system
<https://github.com/mozilla-iot/wot/issues/57>, such that a thing doesn't
just have a single top level "type", but can have multiple standard
"capabilities" which can be mixed and matched between different things.

I've been trying to follow along with the discussion regarding semantic
annotations and iotschema.org, but I have some questions.

*Semantic Annotation vs. Data Structure Constraints*

Firstly, I can see that there are a lot of proposed schemas
<http://iotschema.org/docs/full.html> for capabilities, properties,
actions, events and property values. Currently these just appear to have a
name and a description, but do not specify any kind of data structure in
the way that schema.org does for all of its schemas for example. To what
extent is a schema just meant to provide a semantic annotation, vs. define
a fixed data structure a client can expect from a thing to help with
interoperability? Is it just that these data constraints haven't been
defined yet, or is that not the purpose of the schemas? What is the
relationship between a JSON-LD style "@type" which is defined by an
external schema at iotschema.org and a JSON Schema style "type" which is
defined in a Thing Description? (Note the awkward name duplication in the
terms "type" and "schema").

For example, could an iotschema.org schema define that a property of @type
LevelProperty always has a type of "number" with a minimum of 0 and a
maximum of 100? Or does it just give the client a semantic hint that this
property is for setting a level? Could an iotschema.org schema define that
an action of @type FadeAction always has a LevelProperty and a
DurationProperty? That a property of @type TemperatureProperty always has a
unit of "centigrade"? That a thing of @type OnOffSwitch always has a
property of @type OnOffProperty and an action of @type ToggleAction?

*Levels of Type*

Another question I have is regarding the number of levels of @type
definitions in the data model. I joined the April 19th Community
Teleconference and understood from the presentations given in that call
that there are at least three levels of schemas being considered:

   1. Capability
   2. InteractionPattern
      1. Property
      2. Action
      3. Event
      3. DataItem

There was also some discussion around the concept of "Feature of Interest",
which I didn't fully understand.

I'm wondering what makes this number of levels necessary? Could it possible
just to have two levels of @type?

   1. Thing
   2. Property/Action/Event

I've included an example below which describes a lamp. The lamp has the top
level @types or "capabilities" of Lamp, OnOffSwitch and DimmerSwitch which
suggest that the thing will have an OnOffProperty and a LevelProperty and
that the thing is a lamp (i.e. an object which emits light).

The lamp has properties of @type OnOffProperty and LevelProperty, an action
of @type FadeAction and an event of @type OverheatedEvent. The action
accepts an input of type object, with two sub-properties of @type
LevelProperty and DurationProperty. You'll noticed that the LevelProperty
@type is re-used from the top-level LevelProperty as it has the same data
structure and constraints.

{
  "name":"My Lamp",
  "description": "A web connected lamp",
  "@context": "https://iot.mozilla.org/schemas",
  "@type": ["Lamp", "OnOffSwitch", "DimmerSwitch"],
  "properties": {
    "on": {
      "name": "On/Off",
      "description": "Whether the lamp is turned on",
      "@type": "OnOffProperty",
      "type": "boolean",
      "href": "/things/lamp/properties/on"
    },
    "level" : {
      "name": "Level",
      "description": "The level of light from 0-100",
      "@type": "LevelProperty",
      "type": "number",
      "minimum" : 0,
      "maximum" : 100,
      "href": "/things/lamp/properties/level"
    }
  },
  "actions": {
    "fade": {
      "name": "Fade",
      "description": "Fade the lamp to a given level",
      "@type": "FadeAction",
      "input": {
        "type": "object",
        "properties": {
          "level": {
            "name": "Level",
            "description": "The level to fade to",
            "@type": "LevelProperty",
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "duration": {
            "name": "Duration",
            "description": "Duration of fade",
            "@type": "DurationProperty",
            "type": "number",
            "unit": "milliseconds"
          }
        }
      },
      "href": "/things/lamp/actions/fade"
    }
  },
  "events": {
    "overheated": {
      "@type": "OverHeatedEvent",
      "type": "number",
      "unit": "celsius",
      "description": "The lamp has exceeded its safe operating temperature",
      "href": "/things/lamp/events/It seems likeoverheated"
    }
  }
}


If a property @type can also be used for sub-properties, what is the need
for @types for DataItems?

*Intended Use Cases*

At Mozilla we'd like to be able to add lightweight semantic annotations to
an otherwise plain JSON Thing Description to mark up certain standard
capabilities, defined by shared external schemas in a schema repository
like iotschema.org, in order to create interoperability between different
Web of Things implementations. Ideally these semantic annotations would
indicate that a thing meets certain data constraints, such that a web
client communicating with that thing can expect properties, actions and
events of a thing to return data in a certain format. That would include
defining constraints such as primitive data types, minimum and maximum
values and enums for a range of possible values for example.

Is this the intended use case of @context and @type annotations which
reference schemas from iotschema.org? It seems like these kinds of data
structure constraints would be necessary in order to allow ad-hoc
interoperability between web things.

Regards

Ben