- From: Anicic, Darko <darko.anicic@siemens.com>
- Date: Fri, 18 May 2018 07:32:55 +0000
- To: Benjamin Francis <bfrancis@mozilla.com>, public-wot-ig <public-wot-ig@w3.org>
- Message-ID: <506E83C73FFE64489FEDD50EC57ACFC820BE7C5F@DENBGAT9EK3MSX.ww902.siemens.net>
Hi Ben,
please see my answers below.
Von: Benjamin Francis [mailto:bfrancis@mozilla.com]
Gesendet: Freitag, 4. Mai 2018 20:05
An: public-wot-ig
Betreff: Capabilities & Schemas
Hi there,
I work on Mozilla's Web of Things implementation over at iot.mozilla.org<http://iot.mozilla.org>. Apart from our open source gateway<https://github.com/mozilla-iot/gateway> implementation which bridges existing smart home devices to the web, we now also have a framework<https://iot.mozilla.org/things/> of re-usable software libraries to create web things themselves using Python<https://github.com/mozilla-iot/webthing-python>, NodeJS<https://github.com/mozilla-iot/webthing-node>, Java<https://github.com/mozilla-iot/webthing-java>, C++<https://github.com/mozilla-iot/webthing-esp8266>, with a Rust library coming soon.
These WoT implementations all expose the Web Thing API<https://iot.mozilla.org/wot/> which, although isn't exactly the same as the current W3C WoT Working Group's specifications, the JSON Thing Description format is very similar to the latest Simplified WoT Thing Description<https://w3c.github.io/wot-thing-description/proposals/simplified-td> proposal so we hope to gradually converge on a standard along those lines as it emerges.
We've recently been discussing a capabilities system<https://github.com/mozilla-iot/wot/issues/57>, such that a thing doesn't just have a single top level "type", but can have multiple standard "capabilities" which can be mixed and matched between different things.
I've been trying to follow along with the discussion regarding semantic annotations and iotschema.org<http://iotschema.org>, but I have some questions.
Semantic Annotation vs. Data Structure Constraints
Firstly, I can see that there are a lot of proposed schemas<http://iotschema.org/docs/full.html> for capabilities, properties, actions, events and property values. Currently these just appear to have a name and a description, but do not specify any kind of data structure in the way that schema.org<http://schema.org> does for all of its schemas for example. To what extent is a schema just meant to provide a semantic annotation, vs. define a fixed data structure a client can expect from a thing to help with interoperability? Is it just that these data constraints haven't been defined yet, or is that not the purpose of the schemas? What is the relationship between a JSON-LD style "@type" which is defined by an external schema at iotschema.org<http://iotschema.org> and a JSON Schema style "type" which is defined in a Thing Description? (Note the awkward name duplication in the terms "type" and "schema").
Actually we have already specifications for Capabilities, Interaction Patterns and Data schema (what you are referring to), but currently this content is not displayed on the iotschema<http://iotschema.org/>.org web pages. Until we fix the appearance on web pages, you can just access the content of iot.schema.org directly from github. For example, let us consider:
Capability: AirConditioner - https://github.com/iot-schema-collab/iotschema/blob/master/capability.jsonld
{
"@id": "iot:AirConditioner",
"@type": "rdfs:Class",
"rdfs:subClassOf": { "@id": "iot:Capability" },
"rdfs:comment": "A capability for air conditioner",
"rdfs:label": "AirConditioner",
"iot:domain": {"@id": "iot:Home"},
"iot:providesInteractionPattern": [
{
"@id": "iot:Temperature",
"@id": "iot:TargetTemperature",
"@id": "iot:BinarySwitch",
"@id": "iot:RunMode",
"@id": "iot:CountDown",
"@id": "iot:WindStrength"
}]
}
Interaction Pattern: Temperature - https://github.com/iot-schema-collab/iotschema/blob/master/interaction-patterns.jsonld
{
"@id": "iot:Temperature",
"@type": "rdfs:Class",
"rdfs:comment": "Temperature interaction property",
"rdfs:label": "Temperature",
"rdfs:subClassOf": { "@id": "iot:Property" },
"iot:providesOutputData": {
"@id": "iot:TemperatureData"
},
"iot:writable" : "schema:False",
"iot:observable" : "schema:Boolean"
}
Data Schema: TemperatureData - https://github.com/iot-schema-collab/iotschema/blob/master/interaction-patterns.jsonld
{
"@id": "iot:TemperatureData",
"@type": "rdfs:Class",
"rdfs:comment": " Temperature data",
"rdfs:label": "TemperatureData",
"rdfs:subClassOf": { "@id": "schema:PropertyValue" },
"schema:propertyType": { "@id": "schema:Float" },
"schema:unitCode": { "@id": "iot:TemperatureUnit" },
"schema:minValue": "schema:Float",
"schema:maxValue": "schema:Float"
}
For example, could an iotschema.org<http://iotschema.org> schema define that a property of @type LevelProperty always has a type of "number" with a minimum of 0 and a maximum of 100?
Yes, as you can see above, Data Schema allows one to define minValue and maxValue.
Or does it just give the client a semantic hint that this property is for setting a level? Could an iotschema.org<http://iotschema.org> schema define that an action of @type FadeAction always has a LevelProperty and a DurationProperty? That a property of @type TemperatureProperty always has a unit of "centigrade"?
Yes, you see above from the TemperatureData specification above that its unitCode is TemperatureUnit, which is an enumeration of Celsius, Kelvin, Fahrenheit, see: https://github.com/iot-schema-collab/iotschema/blob/master/unit.jsonld
{
"@id": "iot:TemperatureUnit",
"@type": "rdfs:Class",
"rdfs:comment": "An enumeration of temperature units.",
"rdfs:label": "TemperatureUnit",
"rdfs:subClassOf": {
"@id": "schema:Enumeration"
}
},
{
"@id": "iot:Celsius",
"@type": "iot:TemperatureUnit",
"rdfs:comment": "unit of the temperature of which the scale is defined by two fixe-points, the temperatures of freezing and boiling point of water at normal pressure (air pressure of 1 013,25 hPa)",
"rdfs:label": "Celsius",
"iot:reference": "0112/2///62720#UAA033#001",
"dct:source": "http://data.nasa.gov/qudt/owl/unit#DegreeCelsius"
},
{
"@id": "iot:Kelvin",
"@type": "iot:TemperatureUnit",
"rdfs:comment": "unit of thermodynamic temperature is the fraction 1/273,16 of the thermodynamic temperature of the triple point of water",
"rdfs:label": "Kelvin",
"iot:reference" : "0112/2///62720#UAA185#001",
"dct:source": "http://data.nasa.gov/qudt/owl/unit#Kelvin"
},
{
"@id": "iot:Fahrenheit",
"@type": "iot:TemperatureUnit",
"rdfs:comment": "unit of temperature according to the temperature of the freezing and boiling point of water (32 °F and 212 °F)",
"rdfs:label": "Fahrenheit",
"iot:reference" : "0112/2///62720#UAA039#001",
"dct:source": "http://data.nasa.gov/qudt/owl/unit#DegreeFahrenheit"
}
That a thing of @type OnOffSwitch always has a property of @type OnOffProperty and an action of @type ToggleAction?
Levels of Type
Another question I have is regarding the number of levels of @type definitions in the data model. I joined the April 19th Community Teleconference and understood from the presentations given in that call that there are at least three levels of schemas being considered:
1. Capability
2. InteractionPattern
* Property
* Action
* Event
1. DataItem
There was also some discussion around the concept of "Feature of Interest", which I didn't fully understand.
I'm wondering what makes this number of levels necessary? Could it possible just to have two levels of @type?
1. Thing
2. Property/Action/Event
Well it seems there is consensus about a model according to which a Thing has Capabilities, and Capabilities are distinguished in a form of Properties, Actions and Events. This is not only in the model of iot.schema and W3C WoT Thing Description, but also in few other IoT models.
Capability with its Properties, Actions and Events is one pattern in iot.schema.org<http://iotschema.org/docs/full.html>. You asked about “Feature of Interest” (FoI). FoI is another pattern that we are currently discussing and introducing in iot.schema.org<http://iotschema.org/docs/full.html>. FoI is a concept which binds Capability and Interaction Patterns to real-world objects (e.g., Room, Door etc.). It provides information about the environment/object in/on which sensing/actuating is applied.
Important to note is that iot.schema.org<http://iotschema.org/docs/full.html> is organized around patterns. If you don’t need the FoI pattern for your use case, then just use the Capability pattern alone.
I've included an example below which describes a lamp. The lamp has the top level @types or "capabilities" of Lamp, OnOffSwitch and DimmerSwitch which suggest that the thing will have an OnOffProperty and a LevelProperty and that the thing is a lamp (i.e. an object which emits light).
The lamp has properties of @type OnOffProperty and LevelProperty, an action of @type FadeAction and an event of @type OverheatedEvent. The action accepts an input of type object, with two sub-properties of @type LevelProperty and DurationProperty. You'll noticed that the LevelProperty @type is re-used from the top-level LevelProperty as it has the same data structure and constraints.
{
"name":"My Lamp",
"description": "A web connected lamp",
"@context": "https://iot.mozilla.org/schemas",
"@type": ["Lamp", "OnOffSwitch", "DimmerSwitch"],
"properties": {
"on": {
"name": "On/Off",
"description": "Whether the lamp is turned on",
"@type": "OnOffProperty",
"type": "boolean",
"href": "/things/lamp/properties/on"
},
"level" : {
"name": "Level",
"description": "The level of light from 0-100",
"@type": "LevelProperty",
"type": "number",
"minimum" : 0,
"maximum" : 100,
"href": "/things/lamp/properties/level"
}
},
"actions": {
"fade": {
"name": "Fade",
"description": "Fade the lamp to a given level",
"@type": "FadeAction",
"input": {
"type": "object",
"properties": {
"level": {
"name": "Level",
"description": "The level to fade to",
"@type": "LevelProperty",
"type": "number",
"minimum": 0,
"maximum": 100
},
"duration": {
"name": "Duration",
"description": "Duration of fade",
"@type": "DurationProperty",
"type": "number",
"unit": "milliseconds"
}
}
},
"href": "/things/lamp/actions/fade"
}
},
"events": {
"overheated": {
"@type": "OverHeatedEvent",
"type": "number",
"unit": "celsius",
"description": "The lamp has exceeded its safe operating temperature",
"href": "/things/lamp/events/It seems likeoverheated"
}
}
}
If a property @type can also be used for sub-properties, what is the need for @types for DataItems?
Please see from the example above.
Intended Use Cases
At Mozilla we'd like to be able to add lightweight semantic annotations to an otherwise plain JSON Thing Description to mark up certain standard capabilities, defined by shared external schemas in a schema repository like iotschema.org<http://iotschema.org>, in order to create interoperability between different Web of Things implementations. Ideally these semantic annotations
would indicate that a thing meets certain data constraints, such that a web client communicating with that thing can expect properties, actions and events of a thing to return data in a certain format. That would include defining constraints such as primitive data types, minimum and maximum values and enums for a range of possible values for example.
Hope the example above shows what you said.
Is this the intended use case of @context and @type annotations which reference schemas from iotschema.org<http://iotschema.org>? It seems like these kinds of data structure constraints would be necessary in order to allow ad-hoc interoperability between web things.
Yes, that is the intended use case of @context and @type annotations which reference schemas from iot.schema.org<http://iotschema.org>.
Regards,
Darko
Regards
Ben
Received on Friday, 18 May 2018 07:33:35 UTC