Re: Capabilities & Schemas

On 24 May 2018 at 21:29, Michael Koster <michaeljohnkoster@gmail.com> wrote:

> OK, I see now that you weren't seeing the connections between capabilities
> and interactions, and between interactions and data, due to the broken
> links on the HTML site. I thought we were only discussing to what extent we
> need to constrain data types and ranges in iot.schema.org definitions...
>

To clarify, my query was indeed about to what extent iot.schema.org
definitions should define constraints for capabilities and interactions.
The current examples in the HTML site do not define what properties,
actions and events a thing which implements a given capability may have, or
what data format properties, actions and events may use as input and
output. I now see that the JSON-LD representation of those definitions on
GitHub does appear to include some of these kinds of constraints. For
example:

   - A Thing with the AirConditioner capability provides a Temperature
   property
   - A Temperature property provides TemperatureData as output data
   - TemperatureData is of type Float, may have a minimum of type Float, a
   maximum of type Float and has a TemperatureUnit
   - A TemperatureUnit may be Celcius, Kelvin or Fahrenheit

This isn't quite as prescriptive as I had imagined because it doesn't
prescribe fixed minimums, maximums and units for example, but does define
that TemperatureData may have a minimum and maximum and one of a defined
list of units. This is probably constrained enough to allow for ad-hoc
interoperability between different implementations of a given definition,
albeit requiring some level of adaptation by the client.

> We still have questions about whether every instance of some interaction,
> e.g. light brightness, can be mandated to use the same scale and type. I
> would like to discuss exactly what client software adaptations we are
> expecting/not expecting and whether we are mandating that everyone either
> redesign their devices or use a gateway box or bridge.
>

The primary requirement for our gateway implementation is currently to be
able to generate a meaningful user interface from a Thing Description. That
should be possible with the example described above, it just requires the
gateway to implement support for a fixed list of units and arbitrary
minimums and maximums.

We also have a requirement for a user command (e.g. "Dim the lights") to
have a consistent result, regardless of a Thing's implementation. With the
approach described above this may require some level of adaptation by the
client to increase brightness by a consistent amount, regardless of what
units and ranges are used by a specific implementation.


> I don't think we are expecting to mandate e.g. every data representation
> from every temperature sensor, but I guess we should discuss that
> also.Surely temperature units can be adapted to by a reasonable client.
>

> For example, if I want to set a light at 50% brightness and the light has
> a 0-255 scale, I know what to do. Likewise, if another light has a
> 0.00-1.00 scale in floating point I also know what to do. We don't want to
> mandate a 0-255 brightness scale for all lights for ever.
>

Yes this will be tricky to get right. I suppose if there's the flexibility
for a definition to provide either a range of different possibilities or
more specific constraints then schema repositories can compete on levels of
specificity. A smart home application might require less complexity than an
industrial application for example. It would certainly make client
implementations simpler if implementations converged on stricter
definitions for simpler applications (e.g. if everyone agreed to implement
the brightness of a domestic light bulb as a percentage).


>
> The question of reusing the property interaction for a data element is
> related to a discussion we are currently having in regards to the
> underlying TD model and our new simplified TD serialization.
>

In the example above I'm not sure why Temperature and TemperatureData need
defining separately. The constraints could be attached directly to a
TemperatureProperty definition. Perhaps there are more complex examples
where these two layers of definition are required?


>
> I guess it turns somewhat on the question of whether all representations
> for interactions are simple numbers, strings, etc. and can be re-used in
> composed payloads. Again partly a question of to what extent we are
> adapting to what's being built vs. mandating how things should be built.
>

One way to look at this is to see the Web of Things as a higher level
abstraction on top of multiple existing implementations. For example, a
Color schema at the web layer could use a simple web-style hex string to
define a colour value which abstracts away differences in underlying
implementations in Zigbee, Z-Wave and Bluetooth which represent colours
using a whole range of different formats which may be closer to the
hardware implementation. A gateway can bridge those underlying
implementations to a consistent Web of Things layer.

Future "native web things" could directly expose a Web of Things schema's
abstraction if they want to.


>
> Anyway, I agree with your conclusion. You only need to use the annotations
> that make sense for your use case, and both the semantic meaning and
> relational definitions (which interactions go with a capability)  are
> provided by the definitions in iot.schema.org.
>
> What are your thoughts on the granularity of capabilities? Does it make
> sense to define "light bulb" as a capability itself, or to define "on/off",
> "brightness", color control", "energy measurement" as capabilities that can
> be composed int a light bulb? WHat is the tradeoff around reusability and
> compose-ability?
>

I'm not sure. Maybe both.

It's useful to have an OnOffSwitch capability so you can issue a command
like "turn everything off" and every thing which has an OnOffSwitch
capability can be turned off with their OnOffProperty. Equally it's helpful
to a have a Light capability which can have an OnOffProperty,
LevelProperty, ColorProperty and ColorTemperatureProperty - so that an
implementation can provide a meaningful user interface for a "light".

The question is then whether to define those as multiple overlapping
schemas where a thing can implement multiple schemas (like interfaces), or
to introduce the concept of inheritance (like classes). I think my personal
preference would be the former, for simplicity.

Ben