Open egekorkan opened 1 month ago
Find below a first try to fill out the new use case template.
What I missed while filling out the template:
At the moment the TD does not provide a way to indicate whether writing a property returns a value.
There are many possible reasons why writing a property may return a value, e.g.,:
Note: There are also scenarios (maybe most of them) were "no" value is returned when writing. Hence, we should not forget about that common use-case.
Thing Descriptions are used.
HTTP, CoAP, Philips HUE, ..
At the moment the TD specification misses to describe what is "practice" in many environments.
The TD should allow do describe what is used/done in practice.
Add response
term to properties similar to response
in forms. The response might be fully missing or defining a completely different payload as sketched in the example below.
"properties": {
"value": {
"type": "number",
"forms": [{"href": "https://example.com/value"}],
"response": {
"contentType": "application/json",
"type": "boolean"
}
}
}
None
Below you can find a potential submission of the form for the use cases described in https://github.com/w3c/wot-thing-description/issues/757 and https://github.com/w3c/wot-thing-description/issues/300.
Besides the points mentioned by @danielpeintner above, I was also wondering if we should add a form field for implementation experience, e.g., if a submitter has already implemented a proposed feature because they needed it to cover the use case they are describing.
At the moment, TDs require both a security
and a securityDefinitions
field to be defined, even when there are no security mechanisms in place.
In that case, a NoSecurityScheme
or a reference to it has to be added to both fields, which mainly serves as an incentive to have some kind of security mechanism in place instead of "no security".
However, as there are scenarios where, for example, a plain HTTPS connection without authorization is the intended way of communicating with a Thing (e.g., in the context of public places or when using a Proxy), the way the feature is currently specified only introduces boilerplate and does not contribute to an substantial increase of security.
The mandatory split into security
and securityDefinitions
also creates some boilerplate that could be avoided by allowing for the "inlining" of security definitions, i.e., by defining them directly within the security
field and setting them as the default security mechanisms.
Both changes together can make TDs less verbose and more compact, which not only makes them easier to read but also more efficient when it comes to their size on the wire.
TDs are being used.
This use case applies to most protocols, devices, data types, and standards, if not all.
security
and securityDefinitions
should not be mandatory anymoresecurity
should allow for an inline definition of security schemes, instead of only containing references to the separately defined securityDefinitions
The potential solution for this problem is two-fold.
That would allow for the definition of this minimal TD:
{
"@context": "https://www.w3.org/wot/td/next",
"title": "Minimalistic Thing"
}
securityDefinitions
within security
WoT TD specificationA minimalistic solution to the second part of the problem could look like this:
{
"@context": "https://www.w3.org/wot/td/next",
"title": "Minimalistic Thing",
"security": {
"nosec_sc": {
"scheme": "nosec"
}
}
}
Here, the security
member defines both a NoSecurityScheme
and sets it as the
default security mechanism with the key nosec_sc
.
The example above is equivalent to following TD:
{
"@context": "https://www.w3.org/wot/td/next",
"title": "Less minimalistic Thing",
"securityDefinitions": {
"nosec_sc": {
"scheme": "nosec"
}
},
"security": "nosec_sc"
}
Note that in the case of inlined security definitions, there could also be a
separate securityDefinitions
field defined in addition to an inlined
security
member, like so:
{
"@context": "https://www.w3.org/wot/td/next",
"title": "Minimalistic Thing with additional securityDefinitions",
"securityDefinitions": {
"basic_sc": {
"scheme": "basic"
}
},
"security": {
"nosec_sc": {
"scheme": "nosec"
}
}
}
The TD specification should put assertions in place that disallow the
redefinition of keys in cases like this one or define which security definition
should have the higher priority (probably the ones defined in security
).
Note that inline security definitions could also be created within the security
field of form instances (e.g., within the form of a property), in a similar way
as outlined for the top-level security
field above.
Not at the moment.
We can use the text at the of this comment to fill and reply to each issue linked here.
Here is the template to use:
For the issues we have distributed, this template can be too verbose. Think of someone from the outside submitting this as a request.