Re: Capabilities & Schemas

On 16 May 2018 at 03:08, Michael Koster <michael.koster@smartthings.com>
wrote:

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

Yes, we are already have adapter implementations which classify devices
using various smart home protocols like Zigbee (including directly paired
SmartThings devices), Z-Wave, HomeKit etc. into web thing types. The
capabilities system should make this mapping more flexible.

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

Schema.org schemas do specify an "expected type" and "description" for each
property (e.g. Text, Integer, Date, DateTime, URL). They can also be
represented in JSON-LD rather than just annotations to HTML content. I have
experience of using schema.org schemas to generate a card representation of
bookmarked web pages and this wouldn't be possible without the level of
data structure the schemas define.

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

Do you have an example client implementation which can automatically adapt
to different representations of the same type, based on the JSON Schema
definition in a Thing Description? My team are sceptical that ad-hoc
interoperability is possible with this approach.


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.

OK, so a thing capability schema will eventually define a set of
interactions a client can expect that a thing which implements that
capability to have? That isn't currently the case.

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

Why not just re-use LevelProperty and DurationProperty? The representation
is exactly the same. With JSON Schema notation of object "properties",
they're even called the same thing.


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

If you do just think of them as sub-properties, it could simplify the data
model by removing the data type layer.


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

Right, I guess this depends on the concrete protocol binding. In our HTTP
binding a Property resource <https://iot.mozilla.org/wot/#property-resource>
wraps the data in an object, using the property ID as a key. Our WebSocket
binding does something similar to construct a setProperty message
<https://iot.mozilla.org/wot/#setproperty-message>. This is pretty hard to
define declaratively using the Protocol Binding Templates approach, but can
be defined using a concrete protocol binding specification.


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

Yes, I think you understood correctly. What we're a bit confused about is
what the schema is actually useful for if it's purely a semantic annotation
and doesn't provide a standard data schema for a client to expect. That
also doesn't seem consistent with the classic schemas on schema.org which
do define data types for properties. I'm curious whether you've actually
managed to implement an adaptable client which can cope with this much
variability in data representation? We certainly haven't.

Ben