RE: Proposal for a WoT servient based on IoTivity

Hi Michael,



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



Capabilities and properties/actions/events are of different nature. The former are concepts while the latter are individuals/instances, to reuse OWL terminology. This is just a quick thought, but from my point of view, everything that is reusable (i.e. capabilities but also data schemas) should not be serialized in a TD. It should be prior knowledge that a client integrates either statically (e.g. a constrained device generates code for particular schemas and/or capabilities) or dynamically (e.g. a client downloads your ontology from thingschema.org and performs reasoning over it when encountering a TD using your vocabulary).



It means that capabilities (and schemas) should be available elsewhere, either locally on your servient or somewhere in the cloud. Their ID would then be their URI. In that case, something like this might be enough in the TD (an array of links):



{

  “@type”: “wot:Thing”,

  “capabilities”: [ “stc:light” ],

  “properties”: […],

  “actions”: […],

  “events”: […]

}



In your example (oic-res-links.json), there is no direct link from the thing to the properties/actions/events. You assume here that every WoT client is aware of the concept of capability, the same way it is aware of the concepts of properties/actions/events. Wouldn’t it be worth declaring both links to the capabilities and links to the actual interactions? We can go even further: is the indirection “thing > capabilities > interactions” needed here? A capability resource has no content in itself, I believe (links are in the protocol headers). Does it deserve to be a resource at all?



>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




instead of sch:Type, I believe you meant sch:Class. Schema.org doesn’t define any “Type” concept.



Best regards,

Victor



From: Michael Koster [mailto:michael.koster@smartthings.com]
Sent: Samstag, 25. Juni 2016 20:45
To: Charpenay, Victor (CT RDA NEC WOS-DE)
Cc: Public Web of Things IG
Subject: 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




   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/ 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<mailto: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 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




   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




   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



   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




   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