search

w3c / wot-thing-description

Web of Things (WoT) Thing Description
http://w3c.github.io/wot-thing-description/
Other
132 stars 63 forks source link

PropertyAffordance section is missing `type` specific in "vocabulary terms" table #1390

Open thjaeckle opened 2 years ago

thjaeckle commented 2 years ago

During implementation of a TM->TD generator I noticed that the section PropertyAffordance is - when strictly comparing with the JsonSchema - missing several type specific terms.

It is declared to be "[...] a Subclass of the InteractionAffordance Class and the DataSchema Class." DataSchema does only declare "Vocabulary terms" common for all data types Subclasses. The subclass specific terms are declared in the subclasses themselves, e.g.:

Looking at the InteractionAffordance class those terms are also not defined.

The JsonSchema correctly contains the definitions that those type specific terms are part of the "property_element": https://github.com/w3c/wot-thing-description/blob/10000c7a6b11fb2d978682f07ebbfbc07203076c/validation/td-json-schema-validation.json#L518-L572

The specification however does not. So from my point the PropertyAffordance must either be a subclass of all of the available DataSchema subclasses (which would prevent redundancy in the spec) or it must declare all type specific terms in its "vocabulary terms" table.

Does this make sense?

egekorkan commented 2 years ago

Well PropertyAffordance is indeed a subclass of DataSchema, please see the screenshot below: image

thjaeckle commented 2 years ago

@egekorkan yes, that's what I mean the problem is. It only is a subclass of Data Schema without inheriting the subclass specific definitions depending on its type.

This is e.g. not enough, as it is nowhere specified that when a property is defined to be of type object, that it additionally holds properties and required definitions.

It only gets clear through examples and the json schema.

egekorkan commented 2 years ago

I think I understand the problem now. E.g. ObjectSchema inherits DataSchema, PropertyAffordance inherits DataSchema but there is no relationship between PropertyAffordance and ObjectSchema.

In a way, we need to say that PropertyAffordance inherits DataSchema and all the other types?

JKRhb commented 2 years ago

I guess this is an old discussion point, but would it also be an option (probably not until TD 2.0) to adjust the JSON Schema to reflect the current class structure? I think it would be a bit more intuitive and would make the specification easier to implement if a property/data schema like

{
  "type": "string",
  "minimum": 2,
  "minItems": 3
}

wasn't allowed.

In this case, however, you would probably need to have one inherited PropertyAffordance class for every DataSchema class.

egekorkan commented 2 years ago

Even when the inheritance/relationship is done in JSON Schema, it would still need additional ways to describe keys that are not allowed since by design, additional terms are allowed in TDs. Probably something that uses property names (http://json-schema.org/understanding-json-schema/reference/object.html#property-names) and then does not allow specific words in specific data schema children

sebastiankb commented 2 years ago

from today's TD call:

ektrah commented 2 years ago

IMHO the fundamental problem is that a property affordance is not a kind of data schema. An object schema is a kind of data schema, a number schema is a kind of data schema, etc. However, a property affordance is something where you can read or write a value, and that value conforms to some data schema (which we want to describe in the property affordance description).

thjaeckle commented 2 years ago

@ektrah true - for actions and events this is clearly separated in the elements input/output (for actions) and data (for events). For TD 2.0 that would probably be a better approach for properties as well - e.g. to have a data element aside from the property's title.

egekorkan commented 2 years ago

For TD 2.0 that would probably be a better approach for properties as well - e.g. to have a data element aside from the property's title.

Warning: This opens a can of worms.

This was actually the case before (around 2018). Below are the ways that this was done:

There are also multiple discussions around this:

If I were to summarize the discussion from my memory:

  1. From developer's perspective, it was more convenient to have constructs like mything.properties.temperature that results in the value rather than mything.properties.temperature.outputData.
  2. Somewhat similar to above, a property has a value and that should have a single data schema. It is weird if a property can have different data schema for writing and reading. (This is however happening in multiple IoT platforms).
  3. We wanted to use readOnly keyword for whole property and these from JSON Schema so property as a Data Schema made somewhat sense.

My personal opinion:

Note: I was not really active in WoT activities when these discussions took place so I would like to get opinions of @mkovatsc, @benfrancis , @draggett , @sebastiankb, and probably more people.

ektrah commented 2 years ago

TD 2.0 is a separate issue.

For TD 1.1, we have a syntax and I think we just need to touch up a bit the semantics. For example,

{
  "title": "Current Room Temperature",
  "type": "number",
  "minimum": -273,
  "maxumum": 655.35,
  "unit": "qudt:DEG_C",
  "readOnly": true
}

describes a property with title "Current Room Temperature". When reading and writing this property, the property value conforms to the data schema

{
  "type": "number",
  "minimum": -273,
  "maxumum": 655.35,
  "unit": "qudt:DEG_C",
  "readOnly": true
}

So, on the syntactic level, it the property description looks like a small extension of the data schema. On the semantic level, however, I don't think it makes a lot of sense to say that the affordance for reading the current room temperature is an instance of a data schema.

How could we describe the semantics more accurately without changing the syntax? Above, @JKRhb suggested "to have one inherited PropertyAffordance class for every DataSchema class". I think that could lead to the right direction. The inheritance tree would then look like this:

(probably with better names). The different kinds of PropertyAffordance would have the same syntax as their JSON Schema counterpart, but the semantics would be different in that the fields describe the value when reading and writing the property and not the property as such.

Would that work?

sebastiankb commented 2 years ago

@egekorkan

Note: I was not really active in WoT activities when these discussions took place so I would like to get opinions of @mkovatsc, @benfrancis , @draggett , @sebastiankb, and probably more people.

Oh yes, this is loooong time ago, and I can only roughly remember the decisions. One of the ideas was to be as aligned as possible with JSON schema. You might be surprised if you define TDs with properties affordances only that that the full TD definition is a valid JSON schema definition that can be used to validate the data instances (=payload data) of the properties affordances.

From developer's perspective, it was more convenient to have constructs like mything.properties.temperature that results in the value rather than mything.properties.temperature.outputData.

Yes, I can remember this point.

Somewhat similar to above, a property has a value and that should have a single data schema. It is weird if a property can have different data schema for writing and reading. (This is however happening in multiple IoT platforms).

Yes, I can also remember this motivation.

We wanted to use readOnly keyword for whole property and these from JSON Schema so property as a Data Schema made somewhat sense.

At property level there should already the hints of being readOnly and writeOnly. In early TDs version, we used a separate term for this (writable?), which we dropped due to the alignment of the JSON schema.

I would like to see this as well since it helps with quite a bit of stuff

Yes, lets re-evaluate this for TD 2.0 and maybe lets change this. But this would lead to the fact that the TD document (if only property affordance are defined) can not be used directly as JSON Schema document anymore. However, this should not be the main motivation.