Thing Models vs. Capability Schemas

[benfrancis]

The WoT Thing Description 1.1 specification mentions that one of the use cases that Thing Models enable is:

develop common applications across devices from different manufacturers that share a common Thing model.

There is an example provided of a Thing Description which uses a type link relation to refer to a Thing Model of which it is an instance. [1]

{
    ...
    "@type": "Thing",
    "name": "Smart Pump",
    "description": "Smart Pump live plant and simulator",
    "id": "urn:smart:device:wot:pump:instance:1",
    "version" : {"instance": "1.0.0",
                 "model" : "1.0.0" },
    "links" : [{
        "rel" : "type",
        "href" : "http://example.com/ThingModelPool/Pump",
        "type": "application/td+json"
    }],
    ...
}

For a number of years now WebThings has solved this problem using semantic annotations which refer to capability schemas in the style of schema.org and iotschema.org. Below is an example of a Thing Description which conforms to the "Light" and "OnOffSwitch" schemas.

{
  "@context": "https://webthings.io/schemas/",
  "@type": ["Light", "OnOffSwitch"],
  "id": "https://mywebthingserver.com/things/lamp",
  "title":"My Lamp",
  "description": "A web connected lamp",
  "properties": {
    "on": {
      "@type": "OnOffProperty",
      "type": "boolean",
      "title": "On/Off",
      "description": "Whether the lamp is turned on",
      "links": [{"href": "/things/lamp/properties/on"}]
    },
    "brightness" : {
      "@type": "BrightnessProperty",
      "type": "integer",
      "title": "Brightness",
      "description": "The level of light from 0-100",
      "minimum" : 0,
      "maximum" : 100,
      "links": [{"href": "/things/lamp/properties/brightness"}]
    }
  },
  "actions": {
    "fade": {
      "@type": "FadeAction",
      "title": "Fade",
      "description": "Fade the lamp to a given level",
      "input": {
        "type": "object",
        "properties": {
          "level": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "duration": {
            "type": "integer",
            "minimum": 0,
            "unit": "milliseconds"
          }
        }
      },
      "links": [{"href": "/things/lamp/actions/fade"}]
    }
  },
  "events": {
    "overheated": {
      "title": "Overheated",
      "@type": "OverheatedEvent",
      "type": "number",
      "unit": "degree celsius",
      "description": "The lamp has exceeded its safe operating temperature",
      "links": [{"href": "/things/lamp/events/overheated"}]
    }
  },
...
}

The schemas in our repository define not only a top level capability type, but detailed definitions of properties, actions and events those capabilities provide, including which interaction affordances are required for a given capability, which properties are read-only, data schemas for properties, action inputs and event payloads including minimums, maximums, enums and units. [2].

This means that when a WoT consumer sees that a WoT producer conforms to a particular schema, it knows what interaction affordances to expect and what data schemas they will follow [3]. It is also possible for a single device to implement multiple schemas, so they can be mixed and matched to form a complete device. Devices can also go beyond what is defined in the schema and add their own interaction affordances.

It seems therefore that the proposed Thing Model feature may overlap with this existing use case of semantic annotations and there are now two ways of referring to a common model/schema used by multiple devices:

1. Using semantic annotations which refer to a capability schema @type from a repository in @context
2. Using type link relations which refer to a Thing Model

We discussed this topic today in the vF2F in the context of both Thing Model and iotschema.org (which also uses the semantic annotation approach) and it would be great to reach a consensus on a single approach, which may be one or the other or a combination of both. For example, maybe Thing Models could be a formal way of describing a capability schema, or alternatively maybe Thing Models could be replaced with an existing semantic web standard.

Notes:

1. The example doesn't provide a complete Thing Description so it's not clear whether the consumer is expected to fetch the Thing Model resource in order to combine it with a partial Thing Description in order to compose the full Thing Description, or whether the Thing Description would be complete and the link relation is only informational.
2. WebThings capability schemas are only defined as human-readable specifications, they are not formally defined in RDF. I'm sure it would be possible to formally define them in RDF, we just never had the need to do that.
3. The main use case for these semantic annotations in WebThings is to generate a much richer user interface for known capability types than could be provided based only on simple types in data schemas. For example, knowing that a string represents a colour can provide a colour picker rather than a hexidecimal number, or knowing that a boolean property represents an alarm could provide something more attention grabbing than a simple checkbox. When a device is added to WebThings Gateway the user is also given a choice as to which capability to use as the primary capability of the device, which determines how it is represented on the main dashboard, including enabling one-touch features like toggling its on/off state.

[sebastiankb]

You are right, the mechanism seems to be kind of similar. However, there are differences: The @context / @type from JSON-LD approach is mainly used to provide a semantic context or to reuse existing terms from a known ontology. So it is possible to rely on multiple ontologies such as from schema.org, SAREF and SSN in a single TD, however, there it is not defined what is the minimum definition or what is required. If I see it correctly, the repository is mainly a website that gives (human-readable) instructions for developers, however, there is no JSON-LD context file or general RDF representation behind, right? I had quick test with the JSON-LD playground.

The TM approach mainly specifies what a TD must look like when it is instantiated. So it is a kind of a template (~class definition) that tells what kind of interaction are required, how, e.g., the title value structure have to look like (e.g., 'title':"Device No. {{DEVICE_NO})", which security / communication templates are possible to implement etc.. So the TM is more less a tooling which offers the opportunity to make such kind of definitions to create specific TDs.

[benfrancis]

it is not defined what is the minimum definition or what is required.

That is true, it is very open ended. Both webthings.io/schemas and iotschema.org specify everything from capabilities down to data schemas, which covers most (but not all) of what can be specified in a Thing Model:

• capabilities
  • properties
  • actions
  • events
  • data schemas

If I see it correctly, the repository is mainly a website that gives (human-readable) instructions for developers, however, there is no JSON-LD context file or general RDF representation behind, right? I had quick test with the JSON-LD playground.

That's correct, as I said:

WebThings capability schemas are only defined as human-readable specifications, they are not formally defined in RDF. I'm sure it would be possible to formally define them in RDF, we just never had the need to do that.

The TM approach mainly specifies what a TD must look like when it is instantiated. So it is a kind of a template (~class definition) that tells what kind of interaction are required, how, e.g., the title value structure have to look like (e.g., 'title':"Device No. {{DEVICE_NO})", which security / communication templates are possible to implement etc.. So the TM is more less a tooling which offers the opportunity to make such kind of definitions to create specific TDs.

That all makes sense, but given the overlap in features what is still not clear to me is when a developer should use Thing Models vs. Capability Schemas.

If Capability Schemas can already provide most of the features of Thing Models then for me it raises the question of whether they need to be standardised at all. The only other use cases proposed for Thing Models appear to be as a tool during development or an internal templating language used in the implementation of a WoT producer, rather than something that is communicated between a WoT producer and a WoT consumer. If that's the case then do they even need to be standardised? It's very common on the web for web servers to use all kinds of templating languages on the server side, which makes no difference to a web browser parsing the generated HTML output.

I agree that the use of capability schemas in the way that WebThings and iotschema.org use them is not fully defined in any WoT specification, so perhaps there is a role for Thing Models as a formal definition of such a schema. It just isn't clear to me how they fit together.

[egekorkan]

So I think one advantage is that there can be many TMs with different granularity levels and letting anyone to make their own TMs without relying on a vocabulary or repository of existing capability descriptions. Semantic annotations are however necessary to guarantee use cases that require specific annotations, like the use case of UI generation.

Regarding what we gain by standardizing TMs, I also couldn't think of a good case where I write a TM, send it to some other entity and that entity can do something just by using that TM. I am guessing that people want a formal definition for the internal tools to use and not invent something from scratch each time.

[benfrancis]

@egekorkan wrote:

So I think one advantage is that there can be many TMs with different granularity levels and letting anyone to make their own TMs

There can also be many schemas with different granularity levels and anyone can make their own schemas.

They key question I'd like to answer is when should the author of a Thing Description use a Thing Model vs. semantic annotations?

Should webthings.io/schemas and iotschema.org start using Thing Models for all their schemas for example?

The main difference I can see is that with Thing Models the names of interaction affordances are fixed in the Thing Model, whereas with schemas @type annotations are used to identify which affordance is which and the name is instance specific. This is really just a difference in syntax, I'm struggling to see a functional difference in how they are used in Thing Descriptions.

Capability Schema

{
  "@context": ["http://www.w3.org/ns/td", "https://webthings.io/schemas/"], 
  "@type": "Light",
  "properties": {
    "brightness" : {
      "@type": "BrightnessProperty",
      "type": "integer",
      "minimum" : 0,
      "maximum" : 100,
      "forms": [{"href": "/things/lamp/properties/brightness"}]
    }
  }
}

Thing Model

{
  "@context": ["http://www.w3.org/ns/td"], 
  "@type": "Thing",
  "properties": {
    "brightness" : {
      "type": "integer",
      "minimum" : 0,
      "maximum" : 100,
      "forms": [{"href": "/things/lamp/properties/brightness"}]
    }
  },
  "links" : [{
    "rel": "type",
    "href": "https://webthings.io/models/lamp",
    "type": "application/td+json"
  }]
}

[egekorkan]

@benfrancis wrote:

There can also be many schemas with different granularity levels and anyone can make their own schemas.

Yes of course. What I wanted to say (but failed to) is that capability schemas or semantic annotations have always a repository behind them and thus a well-defined way to look and choose an annotation. I can write a Thing Model, store it anywhere I want and use it even for a single Thing.

In the last example you gave, I think they are definitely interchangeable. I was for example not aware of using Capability Schemas or semantic annotations where the schema is this verbose. Most semantic annotations are just further specifying what that interaction or Thing means and not necessarily giving a template like you have shown here.

[benfrancis]

Having reviewed the latest Editor's Draft, it is still not clear to me under what circumstances a Thing Description should use a Thing Model (via a link) vs. a context extension (via semantic annotations).

It's also not clear to me from the specification what a Consumer is expected to do when it comes across a Thing Description which links to a Thing Model. Is it meant to fetch the Thing Model and all of its children/sub-models? Is it meant to construct a complete Thing Model from all of its component parts (as defined by the extension, import and composition mechanisms)? Is it meant to validate the Thing Description against the Thing Model?

If so then that's a lot to ask Consumers to implement and considerably increases the requirements when processing a Thing Description.

If not, then what is the purpose of including the link to the Thing Model in the first place? How is that information meant to be used by a Consumer?

I can see that designing a sophisticated templating language for building Thing Descriptions could be useful for development environments and back end systems. What I'm not clear about is the reason for standardising that templating language as part of the Thing Description specification.

As with the Scripting API, I think this feature might be better suited to a helper library implementation, rather than a specification. There could be multiple competing templating engines for Thing Descriptions in the same way that there are templating engines for HTML. If Thing Models are not something which Consumers need to process directly, then there doesn't seem to be a need to standardise them as part of the Thing Description specification.

Above all, I'm concerned about adding yet another layer of abstraction to the WoT Architecture which seems to overlap with existing features. There are now quite a few abstractions which a Consumer needs to consider:

• A Consumer may parse Form metadata to derive a protocol binding from the vocabulary defined in a protocol binding template
• A Consumer may parse a profile member to derive a protocol binding from an interoperability profile
• A Consumer may parse semantic annotations to derive that a Thing is an instance of one or more capability schemas from a context extension
• A Consumer may parse a link to derive that a Thing is an instance of a Thing Model and all of its children

I'm interested to see the level of adoption this feature gets in WoT implementations, but I personally don't plan to implement it in WebThings because I'm not clear on what value it provides.

[benfrancis]

See this related discussion under the iot.schema.org repository: https://github.com/iot-schema-collab/iotschema/issues/86#issuecomment-1108558400

There's some confusion about what Thing Models are meant to provide and their relationship with semantic annotations.

[sebastiankb]

I will provide a PR that is placed at the beginning of the TM chapter which provide some text that explains the relation to semantic annotations.