Consistent modeling of Capabilities/Interactions/DataValues

[vcharpenay]

Currently, the iotschema vocabulary is somewhat inconsistent in the sense that class definitions and instances are mixed. For instance, the vocabulary includes the statements iot:providesOutputData schema:domainIncludes iot:InteractionPattern and iot:Temperature iot:providesOutputData iot:TemperatureData. As a consequence, iot:Temperature which is a subclass of iot:InteractionPattern, must also be an instance of this class. These two statements contradict each other.

[vcharpenay]

Instead, I would suggest that we remove the statement iot:Temperature iot:providesOutputData iot:TemperatureData and replace it with an RDF shape that states that any temperature interaction must provide some temperature data, e.g. by defining a WoT Thing Description. Here is a SHACL definition for this temperature interaction:

iotsh:TemperatureShape a sh:NodeShape ;
  sh:targetClass iot:Temperature ;
  sh:property [
    sh:path ( iot:providesOutputData [ sh:zeroOrMorePath ( iot:field iot:value ) ] ) ;
    sh:node iotsh:TemperatureValueShape ;
    sh:minCount "1" ;
    sh:description "a temperature interaction must provide some temperature data"
  ] .

(iotsh: maps to a namespace within iotschema where only shapes are defined; iot:field and iot:value map to JSON Schema terms, see next comment below.)

Such a definition could be downloaded from the iotschema website or even rendered along the lines of the SHACL playground (bottom left panel). The semantics of iot:Temperature would then be better defined as the class of all definitions validating the above shape.

[vcharpenay]

As you might have already noticed, I don't use "TemperatureData" in my example but instead "TemperatureValue". It is indeed quite complicated to reuse data definitions across IoT systems if they force a specific structure for the data (as schema:PropertyValue does).

For instance, temperature data is exposed as follows by OCF and IPSO devices (respectively):

{
  "rt":           ["oic.r.temperature"],
  "id":           "unique_example_id",
  "temperature":  20.0,
  "units":        "C",
  "range":        [0.0,100.0]
}

{
  "bn": "/3303/0/",
  "e": [{
    "n": "5700",
    "v": 20.0
  }],
}

In either case, the only interesting bit is the numeric value itself but the structure of the two JSON objects differ significantly. Following what's been defined in the W3C Web of Things group for data definitions, my suggestions would be to define classes for numeric/boolean/string values only and use them to annotate arbitrary JSON schema definitions, as follows:

{
  "type": "object",
  "fields": [{
    "name": "temperature",
    "value": {
      "@type": "iot:TemperatureValue",
      "type": "number"
    }
  }]
}

{
  "type": "object",
  "fields": [{
    "name": "e",
    "value": {
      "type": "object",
      "fields": [{
        "name": "v",
        "value": {
          "@type": "TemperatureValue",
          "type": "number"
        }
      }]
    } 
  }]
}

It would then be necessary to include JSON schema terms in iotschema to allow for such definitions. One could later consider aligning this definition with schema:QuantitativeValue.

[mjkoster]

This looks reasonable to use a shape for the data value constraint definition.

I'm not sure of the distinction between "Data" and "Value". I just changed the TD examples to "...Data"

We want to be able to have the shape to be able to describe how a number constraint is expressed e.g. value range, value resolution (float, integer, number of significant digits) and also how units and other qualifiers may be expressed.