Re: Proposal for a WoT servient based on IoTivity

Hi Victor,

Thanks for the review; I'm making a second pass and cleaning up the TD files. Your suggestions will help a lot.

I do have a namespace to use and will be updating and adding a real context file to resolve the references correctly.

> -       your approach of having capabilities in the one hand and things in the other hand seems very promising. Do you already have a piece of code in your servient implementation that constructs all st-th-*.json files by loading and parameterizing the proper st-cp-*.json files?


I haven't implemented any automated conversion from capability TDs to thing TDs. I wanted to show the underlying structure based on capabilities and still thinking of ways to accommodate sub-structures like capabilities in Thing Description. I think applications may benefit from both constructing and discovering capabilities as a semantic layer that encapsulates subsets of the events, actions, and properties of a thing.

Capabilities solve a use case need for reusable semantic definitions of properties, actions, and events. For example, if I have a thing with more than one function that offers on/off control, I need some way to associate a particular on/off instance to the instance of the thing that it controls. 

I'm still not sure how TD can be extended to do this. I'm evaluating an index construct that might also be used for groups and arrays of resources. The problem is that there isn't a well defined way to do indirection. WIth typical hypermedia controls, one can link to a collection of links. So a thing can have links to capabilities, which can have links to events, actions, and properties. The capabilities, actions, events, and properies can all have reusable definitions and in some cases reusable IDs.

With TD there is no collection structure other than the items in the properties, actions, and events arrays. If there was a collection added for capabilities, what would the links point to? I don't know if links to other elements within the TD document itself would be useful. 

What are your thoughts on how to do this?

Here is an example using hypermedia controls:
https://github.com/mjkoster/iotivity-servient/tree/master/model <https://github.com/mjkoster/iotivity-servient/tree/master/model>

oic-res-links is the entry point. It is an index that contains links to the "light" thing and direct links to the light's capabilities. The light thing is modeled by a collection of links to its capabilities. Each capability is modeled by a collection of event, actions, and properties, therefore is directly mappable to a TD instance.

"commands" use the same transfer layer semantics as TD Actions, and attributes use the same transfer semantics as TD Properties, so TD can point to these but can't express the basic structure of multiple capabilities of a thing.

The embedded semantics in these controls can be referenced to namespaces using a JSON-LD file as an RDF template with associated property and type definitions:
http://thingschema.org/smartthings/examples/light-example.jsonld <http://thingschema.org/smartthings/examples/light-example.jsonld>

http://thingschema.org/smartthings/ <http://thingschema.org/smartthings/> is the namespace I will refer to in the updated TD files, but I still need to make a default context, etc. to get it all to work without the temporary hack of duplicating the explicit context in each file.

Best regards,

Michael


> On Jun 3, 2016, at 6:47 AM, Charpenay, Victor <victor.charpenay@siemens.com> wrote:
> 
> Hi Michael,
>  
> thanks for pointing this out. I browsed your work with interest. Here are a my comments:
>  
> -       your approach of having capabilities in the one hand and things in the other hand seems very promising. Do you already have a piece of code in your servient implementation that constructs all st-th-*.json files by loading and parameterizing the proper st-cp-*.json files?
> -       If it is the case, I understand redundancy does not really matter. But here is a piece of advice to avoid repeating x times the same JSON schema in a single TD (also mentioned here <https://github.com/w3c/wot/tree/master/proposals/type-system#comparison>). It simply consists in using the @id JSON-LD keyword to reference an object defined several times. e.g.:
> {
>   …
>   “properties”: [
>     {
>       “name”: “hue”,
>       “valueType”: {
>         “@id”: “#percent_type”,
>         “type”: “object”,
>         “minimum”: 0,
>         “maximum”: 100
>       },
>       …
>     },
>     {
>       “name”: “saturation”,
>       “valueType”: “#percent_type”,
>       … 
>     }
>   ],
>   …
> }
> -       I believe st-td.json is just a draft example made of pieces you copied from the Current Practices document, is that right? Because it contains syntax errors and some inconsistencies as per JSON-LD.
> -       It is great to see that you annotated your TDs with actual semantics. Do you plan on further defining concepts like capability, hue, colortemperature, etc? I assume the ontology http://example.org/smartthings <http://example.org/smartthings> does not exist. It would be beneficial if you annotated your Things with well-defined concepts, e.g. from the DogOnt ontology. DogOnt has concepts like HueStateValue, SaturationStateValue, OnCommand, OffCommand and many others, i.e. probably everything you will need. It is actually what we tried to introduce in the last PlugFest with a “common” extra context for semantic annotation <https://github.com/w3c/wot/tree/master/TF-TD/TD%20Extensions>. It is maybe better to reference DogOnt directly, though. You can download the ontology file here <http://elite.polito.it/ontologies/dogont.owl>.
> -       When you declare “@type”: “thing” or “@type”: “capability” at the beginning of a TD, those terms should appear either in a namespace or in a context. Otherwise, the RDF triple you generate from that isn’t quite correct. If your code makes use of it, you might want to use an internal property instead of @type (for instance _type, in which case it is simply ignored by the JSON-LD processor).
> -       I spotted minor syntax errors:
> o    st-cp-switch.json:48, the trailing comma should be removed
> o    st-cp-colorcontrol.json:119, the escaped string seems wrong
>  
> By the way, I used a validation tool to check your TDs, which I am currently developing. It performs JSON Schema validation as well as semantic validation if there is any annotation (still experimental). This tool is web-based and I hope to put it online before the PlugFest in Beijing, to help participants.
>  
> Regards,
> Victor
>  
> From: Michael Koster [mailto:michael.koster@smartthings.com] 
> Sent: Dienstag, 31. Mai 2016 20:06
> To: Public Web of Things IG
> Subject: Proposal for a WoT servient based on IoTivity
>  
> Hi,
>  
> FYI; I have collected some working documents and started a project repository to create an implementation of a WoT servient based on IoTivity as the resource layer.
>  
> The basic idea is described at:
> https://github.com/connectIOT/iotivity-servient/blob/master/docs/st-servient.pdf <https://github.com/connectIOT/iotivity-servient/blob/master/docs/st-servient.pdf>
>  
> Iotivity would expose resource models using the abstract transfer layer protocol bindings proposed in:
> https://github.com/connectIOT/iotivity-servient/blob/master/docs/abstract-transfer.pdf <https://github.com/connectIOT/iotivity-servient/blob/master/docs/abstract-transfer.pdf>
>  
> Initially I have mapped some SmartThings Capabilities (different things a device can do or expose, like on/off and level control) and some reference device types to Thing Descriptions.
> These are the devices that would be exposed for the PlugFest:
> https://github.com/connectIOT/iotivity-servient/blob/master/docs/BasicDeviceTypes.pdf <https://github.com/connectIOT/iotivity-servient/blob/master/docs/BasicDeviceTypes.pdf>
>  
> I've created a set of Thing Descriptions for the Capabilities, and another set for devices, that aggregate the Capability TDs. These are all maintained at:
> https://github.com/connectIOT/iotivity-servient/tree/master/td <https://github.com/connectIOT/iotivity-servient/tree/master/td>
>  
> It would be great if someone would review these TD files to confirm that I understand how to use TD, before I create a larger set of TDs to represent the reference device types and capabilities.
>  
> Best regards,
>  
> Michael