search

w3c / wot-thing-description

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

Using the New Use Case Template and Gathering Experience #2039

Open egekorkan opened 1 month ago

egekorkan commented 1 month ago

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:

- Submitter Contact Information: (For the test runs, please leave it empty)
- Domain or Industry (If your use case is from a [specific domain](https://w3c.github.io/wot-usecases/#domains), please identify it here.):

## Introduction 
> Give a basic, non-technical introduction to the use case. Multiple lines are possible

## WoT Usage

> How do you already use Web of Things specifications such as Thing Description, Discovery, Bindings, Profiles, Scripting API? If you are not using WoT, please write "None". For the test run, TD is always present.

## Technical Environment

> What kind(s) of protocol, device, data type, and/or existing standard are present in the environment of the use case?

## Problem

> What is the problem you want to highlight with this use case? What is missing in the specifications? 

## Expectation

> How should this problem be solved? What is your expectation for the specifications to include?

## Solution Proposal

> Do you already have a technical solution in mind? Please provide example TDs, specification text, code, or similar

## Other Comments

> Do you have any other information you wish to provide? If there are any security, privacy, accesibility or internationlization concerns, please provide them here

For the issues we have distributed, this template can be too verbose. Think of someone from the outside submitting this as a request.

danielpeintner commented 1 month ago

Find below a first try to fill out the new use case template.

What I missed while filling out the template:

Introduction

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.

WoT Usage

Thing Descriptions are used.

Technical Environment

HTTP, CoAP, Philips HUE, ..

Problem

At the moment the TD specification misses to describe what is "practice" in many environments.

Expectation

The TD should allow do describe what is used/done in practice.

Solution Proposal

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"
        }
    }
}

Other Comments

None

JKRhb commented 3 weeks ago

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.

Introduction

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.

WoT Usage

TDs are being used.

Technical Environment

This use case applies to most protocols, devices, data types, and standards, if not all.

Problem

Expectation

Solution Proposal

The potential solution for this problem is two-fold.

Make both fields optional in the WoT TD specification

That would allow for the definition of this minimal TD:

{
  "@context": "https://www.w3.org/wot/td/next",
  "title": "Minimalistic Thing"
}

Introduce a way to define securityDefinitions within security WoT TD specification

A 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.

Other Comments

Not at the moment.