Thing types for common devices

[T-vK]

I am currently working on some IoT devices. For instance: A thermostat, lamps and LED strips
But there don't seem to be standardized ways to define these devices and their typical actions like set the brightness, set the temperature, etc. https://iot.mozilla.org/wot/#web-thing-types
I only found binarySensor and onOffSwitch, which are both rather abstract.

Are there any plans on adding more types to the spec? Especially non-abstract ones like thermostat and lamp?

This would make it much easier to create IoT devices that are plug&play.

[benfrancis]

Yes, at Mozilla we're currently working on adding more Web Thing Types to our implementation and then eventually the spec. We hope to agree on some basic thing types as part of the specification through work with the W3C WoT Interest Group. These types can then be extended with additional schemas, e.g. from iot.schema.org using JSON-LD.

We'd be interested to hear more about what you're working on, if you want to share more details on our public mailing list then we might be able to help.

With regards to proposed thing types, let's file an issue per proposed type and discuss what the properties, actions and events would be and whether they are common enough to be part of the spec itself vs. being defined externally as a schema.

[poussa]

Hi @benfrancis

When adding more types to your specification, have you though about reusing the work that OCF has done? They have done a lot of data models, you can find them here: https://oneiota.org/

The models contains REST API specification for various things. Would that be the same you are looking for?

[benfrancis]

@poussa Certainly, yes.

We've also been looking at the device types defined for ZigBee and Z-Wave which are quite mature and often have equivalent types in both protocols.

BTW I should be clear that the JSON-LD Thing Description being created by the Working Group has no built in types and I believe relies on JSON-LD contexts entirely.

Our approach for the JSON Thing Description in the Interest Group so far (just got going, based partly on the Mozilla submission referenced above) has been to experiment with defining a small set of built-in types (to make it easy to get started), with extensibility through optional JSON-LD extensions. The cut-off point for what is part of the default context in the spec vs. defined via external schemas is quite arbitrary though, so if a healthy ecosystem of popular schema repositories emerges in future it may make sense to just defer to them entirely.

[sebastiankb]

Please note, this topic is already addressed by the iot.schema.org team ( @danicic, @mjkoster, and @danbri). So far, for the next WoT PlugFest it is planned to use it more active for some use case applications.

[benfrancis]

Hi @sebastiankb, I'm currently trying to implement some more complex web thing types in Mozilla's gateway implementation and I looked at what's currently on iotschema.org (I understand this temporary domain will eventually be migrated to iot.schema.org) in the hope that there might already be some well defined types I could re-use.

There are currently lots of broken links on that website (I think I may have seen this mentioned in some W3C meeting minutes lately), but I did find:

• Property
• Action
• Event

There's really just a high level list of a few property types which aren't yet fully defined. Is this the latest version of this work so far? I would argue some of them aren't great examples, like "Turn On" and "Turn Off" and "Set Dimmer" as properties.

I did also find https://github.com/iot-schema-collab/iotschema which has some examples in JSON-LD.

oneiota.org already has quite a mature collection of "resource" types defined by the OCF in RAML, Swagger and JSON Schema formats although there does seem to be some duplication and inconsistencies.

Another question I have is how are these types intended to be used? Our simplistic model of Web Thing Types currently just has a single high level thing type for a Thing like "onOffSwitch" or "binarySensor". This works for simple examples, but the diversity of device types (e.g. the SmartThings ZigBee door sensor which also happens to be a temperature sensor) means this model breaks down pretty quickly. The user would basically have to choose between multiple different types which could be applied to the same device.

In our gateway implementation we are mapping Web Thing types onto off the shelf ZigBee and Z-Wave devices. ZigBee and Z-Wave have the concepts of "clusters" and "command classes" respectively which are collections of properties or commands which can be composed together into a single device.

From @danicic's examples on GitHub it appears that this might be the intention for iot.schema.org too, with the concept of "capabilities" borrowed from SmartThings as documented by @mjkoster. This is also the case for oneiota.org which defines interoperability at the "resource" level where a device consists of many resources.

What's the latest thinking on how iot.schema.org types are used in a Thing Description?

[mjkoster]

Great question!

tl;dr
iot.schema.org and WoT Thing Description are used together to provide a practical approach to semantic interoperability, where we can describe, for a broad class of application domains, "what to do" and "how to do it" for typical interactions with connected things in those application domains.

The approach builds on the current industry convergence onto a relatively small set of basic transfer protocols (HTTP, CoAP, MQTT), and addresses the issue of the diverse ways there protocols are used across device SDOs (Zigbee, OCF, OMA LWM2M, IPSO)

The intention is to base the semantic interoperability on the concept of "capabilities", generalized across multiple models, e.g., Zigbee Clusters are a similar concept. As you have noticed, OCF/Oneiota resource types are also at a similar level of granularity and compose-ability.

The capability model solves the problem of devices that combine reusable elements of functionality, which is very common and IMO necessary to fully support to end users.

iotschema capability definitions are abstract, protocol-neutral, definitions for these capabilities, and consist of a set of (also abstract) events, actions, and properties that implement the capability. The definitions in iotschema will incorporate other ontologies and vocabularies when appropriate, for example QUDT.

The intention is for a particular iotschema definition to be reusable for an OCF resource type, an IPSO Smart Object, a Zigbee Cluster, or a SmartThings capability and to provide a basis for semantic interoperability across these "ecosystems".

An iotschema capability is meant to provide a standard expression of "what you want to do" with some connected thing, like obtain temperature, or close a door, or turn off a light.

The definitions in iotschema contain terminology for 3 levels of interaction; the capability level, e.g. light dimming capability, the interaction level (like TD) events, actions, and properties, like a moveToBrightness action, and third, data items like brightnessData and rampTimeData that you include in a moveToBrightness action and is used to annotate the inputData and outputData constructs in a TD.

iotschema definitions are expected to be made by domain experts in a protocol-neutral forum like a W3C Community Group. There may be many such groups specialized by application domain, e.g. automotive, healthcare, smarthome...

WoT Thing Description describes instances of actions, events, and properties that may be annotated with terminology from iotschema definitions at any or all 3 levels (capabiity, interaction, and data item). There are examples of this in the Thing Descriptions I submitted at the Burlingame plugfest.

ThIng Description also contains Protocol BIndings, which describe the "how to do it" associated with a particular "what to do" which is described in the iotschema-based annotation.

So the Thing Description is annotated with iotschema semantic identifiers for capabilities, interactions, and data items to describe "what to do", and annotated with protocol bindings to describe "how to do it", both of which are IMO necessary to achieve practical semantic interoperability in today's world of diverse device protocols and device SDOs.

[draggett]

I think there are some interesting challenges in how to describe capabilities. For instance, there could be a one to many relationship between a capability and the interaction model, e.g. where a given capability involves several properties, actions and events. One approach I've explored associates each capability with a set of named roles. The interaction model includes declarations that a thing implements a given set of capabilities, and includes associated declarations that signal the semantic roles played by particular properties etc. The semantic model for capabilities identify the roles.

A taxonomy of capabilities then allows for variants with different sets of roles. This can be used to model different kinds of lights, e.g. simple on/off lights, lights with a dimmer control, lights with a hue control, and the direction and the direction for lights that are not omnidirectional. The taxonomy allows roles to be applied to metadata, e.g. the location of a light within a room.

A way to study the requirements for such taxonomies would be to look at existing consumer products as if they were IoT enabled, e.g. washing machines. The user manuals describe the capabilities from the user's perspective, and this provides the basis for envisioning how these capabilities could in principle be exposed as a thing in the web of things. We could then look at the ranges of products from a variety of manufacturers to get a handle on the challenges for expressing descriptive models of their capabilities. To be useful, the descriptions would share common vocabularies.

We need to find a way for the WoT IG to work on broad set of scenarios and to make demos that are available online rather than just at each plugfest.

[danicic]

I would like to go back to the original issue post from @T-vK and to point to existing iot.schema.org Capabilities for thermostats, lamps and LED strips:
on-line: http://iotschema.org/Capability
Git: https://github.com/iot-schema-collab/iotschema
or
Interaction Patterns like set the brightness, set the temperature, binarySensor and onOffSwitch available:
on-line: http://iotschema.org/Property
Git: https://github.com/iot-schema-collab/iotschema/blob/master/interaction-patterns.jsonld

Please raise an issue or create a pull request to propose another Capability or Interaction Pattern you need.

[benfrancis]

@danicic Are these schemas intended to map onto a Thing Description in some way?

The properties with verbs in their names don't seem like great examples. Shouldn't properties be described by nouns?

Here are some example properties from the Web Thing Types we have implemented in Mozilla's Things Gateway.

• on (type: boolean)
• level (type: number, unit: percent)
• voltage (type: number, unit: volt)
• current (type: number, unit: ampere)
• frequency (type: number, unit: hertz)
• instantaneousPower (type: number, unit: watt)
• color (type: string, hexidecimal RGB color code)

How are capabilities meant to be mapped onto a Thing Description? Are they properties, actions, events or something else?

In Mozilla's Web of Things gateway implementation we have found that just defining types at the top level of a Thing (e.g. onOffSwitch, multiLevelSwitch, binarySensor, multiLevelSensor, smartPlug, onOffLight, dimmableLight, onOffColorLight, dimmableColorLight) is quite inflexible on its own.

We are interested in standardising "capabilities" where capabilities are standard properties, actions and events that can be mixed and matched between web thing types.

For example:

• an "on" capability could be a boolean on/off property which could be shared between smart plugs and bulbs
• A "color" capability could be shared between colour lights and dimmable colour lights
• A "fade" action could be shared between dimmable lights and dimmable colour lights
• A "close" action could be shared between a garage door opener and electric blinds
• An "overheated" event could be shared between a boiler and a lamp

How does this align with your current understanding of capabilities?

Also, how do people find the pages you linked to? The front page of iotschema.org is not very helpful.

[draggett]

In my view, capabilities can be regarded as constraints on the interaction models exposed by things. Such constraints should be composable and flexible. An example is a thing that has the role of a lighting controller that can be used for a wide variety of different kinds of lights, and for control of multiple lights, e.g. all of the lights in a given room. We want to make it easy to create apabplications that can alter the lighting without getting bogged down in the complexity of the variation of interfaces exposed by different lighting vendors and across different models of lights.

For this the applications should be able to choose between a simple interface and a complex interface, where they would be able inspect the available lights in the room along with their properties and capabilities. This is all possible using relatively simple semantic models and a lightweight means to query them. The JSON thing description could declare the capabilities as named terms that the @context links to the semantic models. It is helpful to have a level of indirection for thing property names and the semantic roles they play in the constraints. My proposal has been to use @context to bind the property names to the semantic roles, so that the capability constraints are expressed in terms of the roles and not the property names.

[danicic]

@benfrancis yes, iot schema is intended to map onto a Thing Description. We provide semantic specifications at 3 levels:

• Capability
• Interaction Pattern
• Data Types

The Interaction Pattern level defines properties, actions, events that are mapped to TD Properties, Actions, and Events. The current specification explicitly provides such a mapping. But right now we are working on a proposal where we only state in the schema that something is an Interaction Pattern, and further use shape constraints to constrain an Interaction Pattern to be either a property, action or event (along other constraints). What is a property for one device, can be an action in another one. Therefor to offer a greater flexibility we will provide more general Interaction Patterns with device-specific shape constraints.

The Capability level builds on top of the Interaction Pattern level by stating, for example, that the Interaction Pattern "BinarySwitch" is shared in both, "Light" Capability and "Aircondition" Capability (similarly as in your examples above).

iot schema follows a pattern-based approach to provide semantic specifications. All 3 levels (above) are defined as a part of the Capability pattern. We are now working on a new pattern where a Thing (Feature of Interest) should be specified, and parts of W3C SSN/SOSA ontology should be integrated. This will help to describe, e.g., a door as a Thing which can be (un) locked.

Yes, I agree we should use nouns instead of verbs. In some specifications this is already the case.

[danicic]

@draggett yes, Capabilities are composable in sense that a Thing may implement more than one Capability. Composability exists also at the level of Interaction Patterns as Things may implement certain Interaction Patterns without implementing a whole Capability.

[benfrancis]

@danicic Interesting, this sounds very close to what we've been discussing at Mozilla too.

The Interaction Pattern level defines properties, actions, events that are mapped to TD Properties, Actions, and Events. The current specification explicitly provides such a mapping. But right now we are working on a proposal where we only state in the schema that something is an Interaction Pattern, and further use shape constraints to constrain an Interaction Pattern to be either a property, action or event (along other constraints)

Can you provide an example of how this works?

If properties, actions and events become top level members of the Thing Description and the "interaction" level is removed, are schemas for interaction types no longer required? Could a capability just either be a property, action or event?

What is a property for one device, can be an action in another one.

Can you provide some examples? In our implementation so far, properties are generally nouns and actions are generally verbs. It can sometimes be difficult to decide whether a capability should be a property or an action, but the general rule of thumb we've been going by is that an action is used where simply setting a property is not sufficient. This might be because:

• An action sets multiple properties
• An action happens over a period of time (e.g. rebooting a device, closing a garage door, closing a blind or fading a light from one brightness to another), where you might first request an action and then query or be notified of its current status.
• An action has a different result depending on the current state of the device (e.g. a toggle action).

We wouldn't for instance have a SwitchOn and SwitchOff action in addition to a SwitchStatus property as in EXAMPLE 15 in the Protocol Binding Templates specification, if just setting the SwitchStatus property would have the same result.

We have recently been thinking of types at two levels:

• Thing Type
• Capability

Here is an example where DimmableLight is a thing type and OnOffProperty, LevelProperty, ToggleAction, FadeAction and OverheatedEvent are capabilities defined by an external context at iot.schema.org. Whether a capability is a property, action or event is included in its name.

You will notice that properties, actions and events have a "schema" property, as per the latest W3C proposal for defining data types, re-using types from JSON Schema. I hope this isn't confusing with the concept of "schemas" at iot.schema.org ?

{
  "@context": "https://iot.schema.org",
  "@type": "DimmableLight",
  "name":"My Lamp",
  "description": "A web connected lamp",
  "properties": {
    "on": {
      "name": "On/Off",
      "@type": "OnOffProperty",
      "schema": {
        "type": "boolean"
      }
      "writable": true,
      "description": "Whether the lamp is turned on",
      "href": "/things/lamp/properties/on"
    },
    "level" : {
      "name": "Level",
      "@type": "LevelProperty",
      "schema": {
        "type": "number",
        "minimum": 0,
        "maximum": 100,
        "unit": "percent"
      },
      "writable": true,
      "description": "The level of light from 0-100",
      "href": "/things/lamp/properties/level",
    }
  },
  "actions": {
    "toggle": {
      "name": "Toggle",
      "@type": "ToggleAction",
      "description": "Toggle the lamp on and off",
      "href": "/things/lamp/actions/toggle"
    },
    "fade": {
      "name": "Fade",
      "@type": "FadeAction",
      "description": "Fade the lamp from one level to another",
      "schema": {
        "type": "object",
        "members": {
          "level": {
            "type": "number,
            "minimum": 0,
            "maximum": 100,
            "unit": "percent"
          },
          "duration": {
            "type": "number",
            "unit": "milliseconds"
          }
        }
      "href": "/things/lamp/actions/fade"
    }
  },
  "events": {
    "overheated": {
      "name": "Overheated",
      "@type": "OverheatedEvent",
      "schema": {
        "type": "number",
        "unit": "celcius"
      }
      "description": "The lamp has exceeded its safe operating temperature",
      "href": "/things/lamp/events/overheated"
    }
  }
}

[mjkoster]

In the current thinking, a capability may have more than one property as well as actions. In general, the actions are orchestrated updates of properties but can be more. Your example of fade action captures the idea (in Zigbee it's called MoveToLevel, for example). Even for on/off it may be useful to define an action that simply sets the property value (more discussion we could have on this point...)

Capability is like "brightness control" or "on/off", Interactions can be properties like "current brightness", and actions like "set brightness", "step brightness", "flash", also events like "overheated". Whether we have a meta class label "interaction" in the file format is practically inconsequential to the concepts involved. It doesn't matter whether we label them "interaction" or as property, action, etc. or indeed as "setBrightnessAction", "currentBrightnessPropety".

One question about your example, what does the "from" level do? How do you send a command to move "from" one level to another. Isn't the level already at the "from" state?

Also, we have "Data Shape" which is a generalized way of expressing the dataSchema, so we do have equivalent concepts for all 3 levels. We can also label a thing type as a capability (like "luminary".

While there is some confusion in terminology where we call schema.org definitions "schemas" we plan to call the iotschema entities "definitions" to help but we feel that aligning the "branding" with schema.org is overall a desireable aspect, especially since we expect to reuse a lot of the conceptual design of schema.org and ultimately be part of schema.org.

[benfrancis]

In the current thinking, a capability may have more than one property as well as actions. In general, the actions are orchestrated updates of properties but can be more.

Interesting. Can you point to some examples? It seems like it would be simpler to just have capability @types (which are either a property, action or event) and then thing @types which are a group of capabilities. Have you found that too limiting in practice?

Your example of fade action captures the idea (in Zigbee it's called MoveToLevel, for example).

Actually the fade action example here is intended to be a single action capability which has multiple data items (arguments) wrapped in an object.

Even for on/off it may be useful to define an action that simply sets the property value (more discussion we could have on this point...)

Please do explain.

Capability is like "brightness control" or "on/off", Interactions can be properties like "current brightness", and actions like "set brightness", "step brightness", "flash", also events like "overheated". Whether we have a meta class label "interaction" in the file format is practically inconsequential to the concepts involved. It doesn't matter whether we label them "interaction" or as property, action, etc. or indeed as "setBrightnessAction", "currentBrightnessPropety".

It does seem like these two levels (capability, interaction) could be reduced down to one (capability). Are there known problems with that approach?

One question about your example, what does the "from" level do? How do you send a command to move "from" one level to another. Isn't the level already at the "from" state?

Hah, I noticed that too. You must be looking at the example in WebThingsIO/api#57 because I removed the "from" part when copying the example here.

Also, we have "Data Shape" which is a generalized way of expressing the dataSchema, so we do have equivalent concepts for all 3 levels. We can also label a thing type as a capability (like "luminary".

If a capability is always a single property, action or event with a single data "schema" then these four (?!) levels of @type (thing, capability, interaction, data) could potentially be reduced down to two (thing, capability). Multiple data items for a property capability, action capability argument or event capability payload could be encapsulated in an object.

While there is some confusion in terminology where we call schema.org definitions "schemas" we plan to call the iotschema entities "definitions" to help but we feel that aligning the "branding" with schema.org is overall a desireable aspect, especially since we expect to reuse a lot of the conceptual design of schema.org and ultimately be part of schema.org.

I agree with aligning on the "branding" of schema.org. If a capability "schema" at iot.schema.org mapped onto a single property, action or event which has a single "schema" property then this might actually be less confusing. If the semantic @type markup is treated as optional then you could manually define the "schema" using plain JSON...

   "properties": {
     "on": {
       "name": "On/Off",
       "schema": {
         "type": "boolean"
       }
       "writable": true,
       "description": "Whether the lamp is turned on",
       "href": "/things/lamp/properties/on"
     }

Or if you want to denote that your schema conforms to a standard schema at iot.schema.org, you could explicitly mark that up with a semantic @type annotation.

   "properties": {
     "on": {
       "name": "On/Off",
       "@type": "OnOffProperty",
       "schema": {
         "type": "boolean"
       }
       "writable": true,
       "description": "Whether the lamp is turned on",
       "href": "/things/lamp/properties/on"
     }

In fact, if you weren't limited to JSON-LD syntax you could potentially even rename @type to @schema.

Without semantic annotations you manually define the schema:

   "properties": {
     "on": {
       "name": "On/Off",
       "schema": {
         "type": "boolean"
       }
       "writable": true,
       "description": "Whether the lamp is turned on",
       "href": "/things/lamp/properties/on"
     }

With semantic annotations you could just refer to an external schema:

"@context": "https://iot.schema.org",
...
   "properties": {
     "on": {
       "name": "On/Off",
       "@schema": "OnOffProperty",
       "writable": true,
       "description": "Whether the lamp is turned on",
       "href": "/things/lamp/properties/on"
     }

..which kind of makes sense given the "schema" property is basically a JSON Schema! Or is that just more confusing?

This might be easier to discuss if we had some actual examples of capabilities at iotschema.org which are more than just names of capabilities.

[draggett]

From a formal perspective, you can define capabilities in terms of semantic models that constrain the interaction models for things. Things of a particular kind may have a given set of capabilities. Some of these may exclude certain others, but for the most part capabilities are freely composable. Capabilities may be related to part-whole relationships. The thing descriptions developed by independent vendors may vary in the names they use for the properties, actions and events of their things. This can be addressed through a mapping from the names used in a particular thing to the names used in semantic constraints for capabilities. Semantic constraints can apply to one or more properties, and take into account sub-properties and relationships between dependent things.

This probably sounds rather abstract, but nevertheless it is important that we have a sound formal basis for capabilities if we are to avoid shooting ourselves in the foot once we move beyond trivial examples. This is one more reason for the Web of Things IG to put serious effort into gathering and analysing a broad range of use cases. If this is too tough a challenge for the IG then we should reach out to the broader research community.

[benfrancis]

@mjkoster @danicic What is the latest thinking on how to reference an iotschema.org schema from a Thing Description?

I note that the Simplified Thing Description proposal has now landed, and the latest Thing Description specification in many ways is looking quite promising.

The specification currently uses a @thing annotation in the JSON-LD 1.1 serialisation example which appears to be used like a JSON-LD @type annotation. What's the rationale behind this? Is it perhaps intended to disambiguate between JSON-LD style @types and JSON Schema style types? It seems like a bit of a strange name.

The specification also says that the plain JSON "JSON TD" serialisation "allows semantic annotations", but doesn't explain how.

I can see that there are now a lot of proposed schemas for capabilities, properties, actions, events and property values at iotschema.org. 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 does for example. Is it intended that these types will eventually provide some data constraints for capabilities? If so, what is the relationship between an iotschema.org capability definition and a JSON Schema style "type" definition in the Thing Description?

We're keen to implement a capabilities system in Mozilla's Web of Things implementation and I don't want to diverge from the latest W3C direction unnecessarily, but I don't currently understand how it's intended to work.

[vcharpenay]

The specification currently uses a @thing annotation in the JSON-LD 1.1 serialisation example which appears to be used like a JSON-LD @type annotation. What's the rationale behind this?

It is a typo, @type should be used instead. Thank you!

[sebastiankb]

@thing was a mistake. I just fixed that in the specification.

[mjkoster]

@benfrancis
As you note, we can include semantic annotation in a TD by using @type property definitions from JSON LD.

Semantic annotation may be added for the thing category, the interaction categories (event, action, property), and for the data item (schema property) category. Annotation at the thing level could use an array of iot.schema capability names for discovery, for example:

"@type": ["iot:light", "iot:binaryswitchcapability". "iot:levelcapability"]

The semantic annotation in iot.schema for data items is meant to enable association of data items with their respective capabilities and interactions, also to understand data items outside the context of the capability, e.g. log or historical data.

With iot.schema.org, we generally intend to provide ways to describe data constraints (data shape) but not specify the actual constraints. There are different ways to describe data constraints, and with W3C TD we allow the use of the JSON Schema data type and constraints (type, minimum, maximum, multipleOf...) along with engineering units. JSON Schema type as used in TD is number, integer, string, boolean, object, array, also enum, value, and const may be included.

[benfrancis]

@mjkoster Thanks for that clarification.

The Mozilla IoT team discussed this in person last week and we're a little confused about how the schemas at iot.schema.org are useful if they don't specify data format constraints for @types. If every implementation of a @type uses different data constraints specified using JSON Schema in a Thing Description instance, then they don't seem very useful for enabling ad-hoc interoperability between implementations. Perhaps you can explain how that's intended to work?

For example, if a Web of Things client knows that a thing with the capability Light may have properties of @type OnOffProperty, LevelProperty and ColorProperty and that those properties have a data type of boolean (true = on), number (percentage) and string (hexadecimal RGB value) respectively, then the client knows how to modify the properties of any light it encounters. If however the schemas to do not define data constraints then a light would be free to represent its OnOffProperty as an enum or string, ColorProperty as a string/RGB map/HSL map etc. and LevelProperty as an integer from 0 to 255 for example. When a Web of Things client comes across a new Light, how does it know how to interpret that thing's properties and modify them to have the desired effect?

For the time being, the Mozilla team has decided to annotate @types at just the thing level and the property/action/event level. It's possible we may add @types at the data level and "feature of interest" level in future if that turns out to be necessary, but we want to start simple. We may also create our own (hopefully temporary) schema repository where we can experiment with schemas which enable ad-hoc interoperability by specifying data constraints for @types.

[mjkoster]

@benfrancis
Yes, there will need to be some constraints set by the iot.schema.org definitions. For example, in the case of scalar numeric values, clients can adapt fairly easily to different units and scales.

For the cases of different data types, there are different definitions. In your color example we can have different capability definitions for HScolor, XYcolor, RGBcolor, colortemperature, and can add more if needed. They are also differentiated by interaction (setXYcolor, setColorTemperature actions) and data type (XYcolordata, huedata, saturationdata).

I suppose if there was an alternate enumeration for temperature (cold, cool, warm, hot) then it would have its own definition at some level and the client would need to understand the difference.

For a particular semantic type (e.g. color saturation data), we allow the protocol binding to specify the number type (integer, float) and range, but we constrain it to be a number and may apply additional constraints on the definition.

I suppose there is a balance to be struck. We probably can agree that we don't force all temperature to be units of Fahrenheit?

[egekorkan]

@mjkoster @danicic is there any progress on this issue? I think it is mostly done but I would like to hear your opinion first

[jtc42]

I’m also curious about this. I’d like to use iot-schema for some work, but there doesn’t seem to be any way to do things I’d consider basic like annotate hexadecimal colour properties with any useful information in the annotation. type: string isn’t particularly useful to describe a colour property on its own without an indication of the format.

[RoboPhred]

I would like to see examples on using iotschema annotation. It's great that we have a standard, but browsing through the site, it's unclear how any of these iris are to be used.

I am trying to understand color data in particular. the CurrentColour table itself defines the value of a providesRColourData to be a RColourData that contains 3 properties: numberDataType (presumably the current value), minValue, and maxValue. Does that mean my property has to return these 3 values? Or are these still annotations and I can just annotate the property itself as the current property? The latter seems unlikely as the current value property is bizarrely titled numberDataType and makes no mention of its connection to RColourData or disambiguation between the identical properties in BColourData and GColourData...

All together, the iotschema is very unclear and seemingly unwieldy / impractical, so the question of how to find and apply community supported annotations to thing descriptions is still largely unanswered. This is pushing me to build my own IRIs for the time being, just to get my project up and working. However, this is something I would really prefer having a standard for.