Define Plugfest Scenarios for OneDM

[mmccool]

• What are some use cases for OneDM/WoT?
• What are the requirements to support these use cases, eg. semantic query support in directories, etc?
• How and when do we annotate the TDs?
• How do we get the annotated TDs into the directory?
• Can we enhance tools to take advantage of annotations, eg. Node-RED integration?

[mmccool]

Aug 19 notes:

• MK has an example (will post link) of how the OneDM annotation would work in a TD, eg for capabilities
• @type annotations on properties, events, and actions
• annotations have a path
• also data schema annotations, eg geolocation (maybe) - but data models not a focus of OneDM, instead see these in Protocol Bindings. But it might make sense to do these in OneDM, so can annotate a TD's data schema to identify data we can extract
• Who does the annotations? What can we use it for? Can we create a set of example queries? When do we need SPARQL vs. JSONPath/XPath? Do we need a directory supporting Things Models? Do we need links from TDs to TMs?

[mjkoster]

Example annotated TD:
https://github.com/mjkoster/ODM-Examples/blob/master/examples/switch-td.json

@type statements in the TD point to nodes in this SDF file:
https://github.com/mjkoster/ODM-Examples/blob/master/examples/sdf-switch.sdf.json

For plugfests, we can use @type statements in TDs to point to definitions in the OneDM repositories
We could also create our own repository for definitions specifically for agreed-upon shared definitions in SDF format - this could potentially be hosted by OneDM - for example by adding a WoT repository where we can control the definitions we use in a plugfest

One quality of the SDF URI based on JSON pointer, is that the semantic category names (classes in the meta model) are explicit in the path segments:

http://onedm.org/wot-plugfest/sdfObject/Switch/sdfProperty/State

Note: in the example TD, the sdfObject name "Switch" is used for @type of the TD itself. This enables discovery by selecting on Thing type and in practice would enable discovery to return whole TDs that contain the affordances (Properties, Actions, Events) of the desired "Object" (in this case, Switch). These TDs returned may also contain other affordances for other Object types, which the client may freely ignore. This is how we are using Object/Capability tags now in TDs, by including all og the Object types in a list along with device type, as the value of @type at the TD level.

To further clarify, data schemas are not the main focus of OneDM, because we wanted to prioritize everyone submitting protocol-independent models, and consider data schemas part of protocol binding. We wanted to stick to defining only the constraints on simple types.

At the same time, there is a clear need to define interoperable complex data types in OneDM. The geolocation data type could be defined as a standalone complex data type in OneDM with semantic annotation on the data fields, also with default data schema for some media types. I would like to take this as an example to create a strawman design pattern for OneDM complex data types. We have a few other cases like RGB color and multi-axis sensors to think about. We already have a proposal for enums, and this could be a complementary pattern for complex data.

Current thinking is that named sets/groups/tuples of properties are required, with optionality specified, and this pattern can be nested, e.g. a named set consisting of named sets. This seems to cover the use cases for complex data. Then we can provide a default schema that can be used to construct the DataSchema element in the target TD. If there is a favorite geolocation data reference, I will use it to create a strawman example.

[mmccool]

We should aim to get as many TDs in the system one week before the plugfest (eg by Sept 21) so we have a week to do manual annotation so we can play with semantic queries use cases.

[mmccool]

test case PR: #68
This is just a simple "input-only" switch, i.e. the state is read-only, and there are no actions to change it. It can only be changed by the user, e.g. by manually pushing it. I don't see any easy way to express these ideas (eg to distinguish inputs from outputs), or the fact that it's a momentary button, in ODM, but I need to dig around a bit more in the definitions. "Real" switch products do tend to be designed so that the state can be changed remotely, however (although this is not universal, and there are reasons why you might not want it, eg for security).

[mmccool]

BTW the above example directory really only has "switch" and "motion sensor", and the switch includes assumptions about remote control of state. So to do this right we need to set up our own SDF definitions (as Michael suggests above...).