¶ Web of Things (WoT) Thing Description
¶ Keywords
Technical access modality to the objects of the IoT
¶ Download address in OLS
Info
https://olsapi.qlf.thinginthefuture.com/api/v2/ontologies/?iri=http%3A%2F%2Fwww.w3.org%2Fns%2Ftdo%23
¶ Known equivalences :
Unknown
¶ Description
The W3C Thing Description (TD) is a central building block in a Web of Things
(WoT) enabled system and can be considered as the entry point of a Thing (aka
the index.html of the Thing). The TD consists of semantic metadata for the Thing
itself, a narrow-waist interaction model with WoT's Properties, Actions, Events,
a semantic schema to make data models machine-understandable, and features for
Web Linking to express relations among Things.
¶ Orange evolutions
In the short term, we needed to have a version that met our needs.
For our use we realized a number of problems and limitations. We decided to
modify TD and call it TDO (O for Orange) before our proposals could be taken
into account.
Our changes and contributions are as follows :
¶ Orange evolutions
¶ BasicSeccuritySchema
The basic authentication scheme does not allow to specify the encoding type (eg
base 64) as well as the contents of the authentication chain. We recommend the
addition of 2 fields: "encoding" with possible value "none" or "base64"
"format". Example #login: #password (open to any existing standard for content description)
The possible values for "encoding" would be: none, base64
¶ OAuth2SecutitySchema
The schema for OAuth authentication does not make it possible to specify in its
current form the authentication provisions of the initial request. We recommend
adding the "authenticationMode" field that can take the following values: none,
header, body
¶ Form
We suggest adding input (0..1) and output (0..1) to Dataschema because depending
on the target platform, the protocol; the inputs and outputs might not be the
same or passed in the same way and consistently (eg header, body or header and
body).
!!!! La description des inputs/outputs au travers de DataSchema
The problem with the DataSchema and the current ontology of W3C and that we do
not know in payloads the source of the valuation for non constant elements.
At this point we see two tracks:
- Add a "valorization" field that would refer to the DataProperty of the so-called reference x ontology and used during the injection.
- Create a DataSchema relationship to ontology x. This relationship between TD and x can not be known in advance.
It could only be created on individuals in the current state of the ontology.
The question is whether one can ontologically create direct relationships on dataproperties.
Added a dataproperties "name".
A still fuzzy and perhaps not good track would be that TD would serve as an ontological basis for extensions that would allow other entities to be described to describe the technical access modalities according to the platforms. We can draw a parallel between ZLC and profiles or ZDT and the definition of devices.
The specification of the binding templates probably deserves to be clarified. In the case where a device supports both OCF, oneM2M and others, the principle that the group has followed so far is that the device must exhibit a TD for each formalism. This is why semantic annotations with @type are important.
This simplifies things but does not solve the following problem:
In Datashare, as shown by this example of the state of a lamp, we have payloads in input and output that are different.
Input
{
"target": {
"byUdi" : ["hue:LCT001@001788fffe16af9e#L3"]
},
"params": {
"on":false
}
}
Output
[
{
"device": {
"id": 11283,
"udi": "hue:LCT001@001788fffe16af9e#L3",
"links": {
"parent": "/users/me/connections/3915/devices/11286",
"self": "/users/me/connections/3915/devices/11283",
"connection": "/users/me/connections/3915"
}
},
"result": {
"message": "Accepted",
"code": 0
}
}
]
If input and output are different then we need to define the interaction as an action and not as a property.
The problem and that from a conceptual point of view is not the best and if there are the same objects visible spar another platform we will have trouble to match a properties of one side with on the other side an action.
For semantic annotations, Property and Action are not equivalents. If we want to represent an object of type saref: LightSwitch, we can do it in two ways:
As a property
{
"@type": ["Thing", "saref:LightSwitch"],
"properties": [{
"@type": "saref:OnOffState",
"type": "boolean",
"writable": true,
"forms": [...]
}]
}
or
as an action
{
"@type": ["Thing", "saref:LightSwitch"],
"actions": [{
"@type": "saref:ToggleCommand",
"saref:actsOn": [ "@type": "saref:OnOffState" ],
"input": { "type": "boolean" },
"forms": [...]
}]
}
In both cases, the state of the switch (on / off) is represented semantically. The td: Property class represents only the state of an object that is exposed by a servient (which does not prevent the object from having other properties or a more complex state).
Among the current reflections, there is the idea that what we propose, namely to define the format of the form regardless of the schema of a property or the input / output of an action
The prefix iot corresponds to à http://iotschema.org/.
This topic is under discussion
https://github.com/w3c/wot/issues/247 or more specifically here, for the differentiation between schema at the level of an Interaction and concrete serialization in a Form:
https://github.com/w3c/wot-thing-description/issues/112
Ontologies modified:
http://owlgred.lumii.lv/online_visualization/gndj
Properties can be used for controlling (or retrieving) parameters, such as a setting an operation state (or getting the current value). Actions model invocation of physical processes, but can also be used to abstract RPC-like calls of existing platforms. Events cover the push model where state change notifications, discrete events, and streams of values are sent asynchronously to the receiver. In general, the TD provides metadata for the different communication bindings (e.g., HTTP, CoAP, MQTT, etc.), mediaTypes (e.g., "application/json", "application/xml", "application/cbor", "application/exi" etc.), and security policies (authentication, authorization, etc.). The serialization of the TD instances is based on JSON and includes at least the TD core vocabularies as JSON keys as defined in this specification document.
Based on this content, we know there exists one Property interaction resource with the name status. In addition, information is provided such as that this Property is accessible via the CoAP protocol with a GET method (default assumption as descripted in the W3C WoT protocol template deliverable WOT-PROTOCOL-BINDING) at coaps://mylamp.example.com:5683/status (announced within the form structure by the href key), which will return a string status value within a JSON structure (as default assumption).
In a similar manner an Action is specified to toggle the switch status using the POST method that is applied to the coaps://mylamp.example.com:5683/toggle resource (see CoAP protocol binding description in the W3C WoT protocol template deliverable WOT-PROTOCOL-BINDING).
The WoT's Event model enables a mechanism for events to be notified by a Thing. Here, a subscription of a possible overheating event of the lamp can be applied by using CoAP OBSERVE at coaps://mylamp.example.com:5683/oh. (see CoAP protocol binding description in the W3C WoT protocol template deliverable WOT-PROTOCOL-BINDING).
The TD in Example 1 reflects some default assumptions that are not explicitly described. E.g., this includes that the media type of the exchange format of the interactions is based on JSON (=mediaType), the property status is not writable and observable. Thus, the TD specification defines vocabularies (writable, observable, mediaType) that have default values. If these vocabularies are not implicit in a Thing Description instance, the Thing Description processor follows the default assumption for interpretation as defined here in this specification.
The TD can be also processed as a RDF-based model. In that case, the Thing Description instance can be simple transformed into a valid JSON-LD style. In terms of JSON-LD 1.1 serialization and semantic's open-world assumption the mentioned vocabularies with default values will be always implicit present in the instances.
Example 1 shows a simple TD instance in such JSON serializiation that reflects WoT's Properties, Actions, Events paradigm by describing a lamp Thing with the name MyLampThing.
EXAMPLE 1: Simple Thing Description Sample
{
"id": "urn:dev:wot:com:example:servient:lamp",
"name": "MyLampThing",
"properties": {
"status" : {
"type": "string",
"forms": [{"href": "coaps://mylamp.example.com:5683/status"}]
}
},
"actions": {
"toggle" : {
"forms": [{"href": "coaps://mylamp.example.com:5683/toggle"}]
}
},
"events":{
"overheating":{
"type": "string",
"forms": [{"href": "coaps://mylamp.example.com:5683/oh"}]
}
}
}
For more information on TD refer to the online documentation :
https://w3c.github.io/wot-thing-description/
!!! Description of interaction with other ontologies (inheritances and relationships) :
Thind Descriptor can be related to any ontology that describes things with technical modalities (API).
Example :
Recommendations for use cases of IoT:
The Thing could be a SDT or a physical or logical SDT device in oneM2M / SDT or a Device in the ZiGBee / ZCL sense.
Since Physical Devices do not normally have an interaction, there is no reason to represent it.
The device and the non-access data set relating to the device will be
represented elsewhere in another ontology such as DogOnt or IoT-O for example, which will be referred to as reference ontology.
In a general way one thing (Thing in the most general sense of the Ontologies) can be seen (instantiated) in several different ontologies present in Thing'In or distributed elsewhere.
This thing can be a communicating object, hence the need to describe in the ontological world the terms of technical access.
Non-communicating things in the real world could have technical access
modalities. Example: Set the temperature of a room.
The terms of access may not be technical, but the Thing Descriptor ontology is only interested in technical access modalities.
Other modalities may be:
-
the security arrangements,
-
the financial terms,
-
the temporal modalities,
-
spatial modalities.
Examples of use :
Simple examples of Use case with module SDT
