Re: Capabilities & Schemas

Hi Ben,

You hit a lot of the interesting design points. We're working on some explaining material for iot.schema.org that also addresses some of these questions. Discussion in line.

> On May 4, 2018, at 11:04 AM, Benjamin Francis <bfrancis@mozilla.com> wrote:
> 
> Hi there,
> 
> I work on Mozilla's Web of Things implementation over at iot.mozilla.org <http://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.
> 
This is great to hear that you are thinking of it in these terms. This is basically our working assumption and conforms with industry best practice. Some good examples are the Zigbee Cluster model ("clusters" of attributes and commands for on/off, levelcontrol, colorcontrol features) and the SmartThings capability model http://docs.smartthings.com/en/latest/capabilities-reference.html <http://docs.smartthings.com/en/latest/capabilities-reference.html>.

We are working with a generalized and extensible abstraction that is similar to these examples. More details below.

> I've been trying to follow along with the discussion regarding semantic annotations and iotschema.org <http://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 <http://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 <http://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").
> 
I think the term "schema" is a little unfortunate. We like to call them "definitions", in part to emphasize that they are meant to be definitional, like a dictionary,rather than encyclopedic, like SSN or SOSA. We intend to reuse concepts from the popular ontologies rather than redefine them.

Also, schema,org in its classic use is an annotation onto an HTML payload, using microformats or some embeddable format. So in that sense it doesn't define a data structure in the way that something lke json schema does. Does this make sense?

What we provide in iot.schema.org is a way to describe data structures but any particular definition should not constrain the data to a single type.

> For example, could an iotschema.org <http://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 <http://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?
> 
This is a good example. We don't want to require any particular number types or units or payload structures in an iot.schema.org definition, but we provide vocabulary to describe and enable clients to adapt. This is some work in progress in iot.schema.org ATM, see the shapes presentation. 

This data constraint description in WoT is left to the dataschema element in TD, which iotschema should allow as a data constraint. We are, as you know, currently refactoring some of this in TD.

> 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:
> Capability
> InteractionPattern
> Property
> Action
> Event
> DataItem
> There was also some discussion around the concept of "Feature of Interest", which I didn't fully understand.
> 
We call these categories, they are also the main classes in our simple iotschema ontology.

> I'm wondering what makes this number of levels necessary? Could it possible just to have two levels of @type?
> Thing
> 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).
> 
Your example is mostly consistent with our practicein that Capability names are used in annotation at the "thing" level. We don't expect there to be instances of capabilities, just the interactions that the capabilities expose (providesInteractionPattern). The thing can inherit/expose just the interactions of the Capabilities that it is composed of. Capabiities are simply sets of interactions that are likely to be exposed by a particular Capability type. 

I will explain the data item annotation based on your example below.

> 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 <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",
should be "@type": ["LevelProperty", "LevelData"]
>       "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",
should be "@type": ["LevelData"]
>             "type": "number",
>             "minimum": 0,
>             "maximum": 100
>           },
>           "duration": {
>             "name": "Duration",
>             "description": "Duration of fade",
>             "@type": "DurationProperty",
should be "@type": ["DurationData"]
>             "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?
> 
Let's look at the fadeaction above. The two parameters this action takes are level and duration. This is where the dataitem annotation comes in. As noted, they should be "LevelData" and "DurationData", and not re-use the "LevelProperty", "DurationProperty" annotation.

We need to remember that the TD PropertyInteraction is not the same class as DataSchema Property. This is what we tend to lose track of in the siplified TD where we now have "Property" appearing in both places. Thus, we label the DataSchema Property in TD with the DataItem class label in iotschema. The confusion arises because they are both called "Property". This is why we had "Field" in the previous TD vocabulary instead, for what is now called the DataSchema "Property" element.

So I would not characterize these as sub-properties of a property in iotschema terms, but rather DataItems exchanged with an Interaction (Property, Action, Event). See, FadeAction and LevelProperty both exchange LevelData.

Another interesting point about your example. The property and event just return number, no structure. While this is valid JSON, it is common to refer to this a text/plain mediatype, as is done in LWM2M. In this case, the iotschema property and dataitem annotation both refer to the resource itself, thus the annotation includes both categories. This way the client knows that it gets the representation from the interaction (PropertyInteraction) is also a representation of the DataItem. This is not the case for structured payloads, where the client needs to know how to extract the DataItems from the payload elements.

> 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 <http://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 <http://iotschema.org/>? It seems like these kinds of data structure constraints would be necessary in order to allow ad-hoc interoperability between web things.
> 
Yes and no. We don't intend for iotschema definitions to contain fixed DataItem constraints. We want to provide a format to define these e.g. RDF Shapes, QUDT and other mechanisms like the JSON Schema terms in WoT TD. It is out of scope for iot.schema.org, for example, to mandate celsius for all temperature data. Trying to fix a minimum and maximum is even more problematic. One could define TemperatureCelsius, TemperatureFahrenheit, etc. but this seems suboptimal vs. having the client adapt. I hope I understood your comment above correctly...

> Regards
> 
> Ben