Wot-thing-description: Semantic information in TDTs

[kolotu]

If you consider a TDT to describe a class of Thing Descriptions, you probably want to allow to reuse one TDT for multiple TDs that are very similar, but do not necessarily share all properties defined in the TDT.
Therefore it might be practical to define some semantic vocabulary for the TDT to describe whether a property is i.e. mandatory in every TD instance, or optional.

In Eclipse Vorto there is vocabulary that covers that adds semantic information to the defined properties:

• mandatory
• optional
• extension (the property extends a supertype with more metadata)
• breakable (calling the operation can lead to a fault status)
• multiple (this property can also be a list)

See below for a complete figure showing the Vorto vocabulary and see here for further information about vortolang

[sebastiankb]

Many thanks for this input. We should evaluate the semantic equivalence to the features

• mandatory / optional
• extension (the property extends a supertype with more metadata)
• breakable (calling the operation can lead to a fault status)
• multiple (this property can also be a list)

Maybe, mandatory / optional can be managed via Shape?

@vcharpenay can you evaluate those points?

[vcharpenay]

@kolotu, can you elaborate on the meaning of breakable? It seems to me that it's not specific to class definitions (TDTs) but more something device descriptions (TD documents) could include.

[vcharpenay]

From the point of view of RDF, the TD model is simply a SHACL shape, that is, a schema over an RDF graph (see td-validation.ttl). SHACL is a quite versatile schema language, so it is always possible to create TDTs as SHACL shapes that are more restrictive than the generic one.

The example below gives a shape that requires a certain TD to have a temperature property:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/shacl#",
    "td": "https://www.w3.org/2019/wot/td#"
  },
  "@id": "urn:ex:TemperatureThingTemplate",
  "property": {
    "path": "td:hasPropertyAffordance",
    "minCount": 1,
    "maxCount": 1,
    "node": {
      "@id": "urn:ex:TemperatureAffordance",
      "property": {
        "path": "td:name",
        "hasValue": "temperature"
      }
    }
  }
}

You can see that it uses minCount and maxCount which one can use to emulate optional and multiple.

[vcharpenay]

It is also possible to emulate extension by stating that a TDT is the conjunction of some shape and its parent. Here is another example, where the above shape is "extended" to restrict the temperature value to the interval [-40,40].

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/shacl#",
    "jsonschema": "https://www.w3.org/2019/wot/json-schema#"
  },
  "@id": "urn:ex:RestrictedTemperatureAffordance",
  "and": [
    "urn:ex:TemperatureAffordance",
    {
      "property": {
        "path": "jsonschema:minimum",
        "hasValue": -40
      },
      "property": {
        "path": "jsonschema:maximum",
        "hasValue": 40
      }
    }
  ]
}

In fact, SHACL defines many more constraints than just this 'and' restriction. It roughly has the same expressiveness as JSON schema.

[vcharpenay]

You can see that SHACL shape definitions are a bit verbose. It would of course be better to simply define TDs as if they were templates and add a few keywords. This is the approach of schema.org to define ProductModels as if they were Products.

But I think it would be good to at least provide some equivalence with SHACL to have a clear semantics for each keyword we add to TDTs.

[kolotu]

@vcharpenay breakable describes that the invocation of the operation could lead to a fault state - similar to the throws Exception method signature in Java.
Breakable does not provide further details about the potential fault state, as that is more device-specific.

[sebastiankb]

just for information: Thing Description Template (TDT) will be called as Thing Model in the future