Using the New Use Case Template and Gathering Experience

[egekorkan]

We can use the text at the of this comment to fill and reply to each issue linked here.

• Evaluating composed Things as a work item #1902 @mjkoster
• Reconsider security & securityDefinitions being mandatory #757 @JKRhb (Allow "security" to include both SecurityScheme objects and declared identifiers #300 is also related)
• Should it be possible to indicate whether writing a property returns set value? #875 @danielpeintner

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]

• Should it be possible to indicate whether writing a property returns set value? #875 @danielpeintner

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

What I missed while filling out the template:

• Name/title of the concern/matter
• Possible disadvantages / concerns (we just list advantages)

---

• Submitter Contact Information: -
• Domain or Industry: -

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.,:

• the set value might be (slightly) different (e.g., rounding a number 1.2345 to 1.23 and notify that the provided value is not supported w.r.t. to digits)
• avoid reading the value again (after writing). Note: re-reading is different anyway since someone else might have written another value in the meantime.
• setting a value for Philips HUE lights returns a completely different payload (1)
• Pretty common to return a body in HTTP-based APIs (2)

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]

Below you can find a potential submission of the form for the use cases described in #757 and #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.

---

• Submitter Contact Information: –
• Domain or Industry: No specific domain/applicable to all domains

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

• Expressing that no security mechanisms are being used without unnecessary boilerplate
• Reducing boilerplate for cases, where security definitions are actually being used

Expectation

• security and securityDefinitions should not be mandatory anymore
• security should allow for an inline definition of security schemes, instead of only containing references to the separately defined securityDefinitions

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.

[egekorkan]

From the TD Call 18.09:

• The template should encourage the submitter to provide more verbose intro, wot usage, problem.
• There must be a non-technical use case introduction (e.g. I want to turn on/off my Philips Hue lights) that is motivating the use case.
• Persona-driven user stories can help here
• The expectation and solution proposal (basically a feature request) should be understood as examples and are optional

[mmccool]

Updating my user story examples for TPAC based on the above. I thought there were three examples but I'm only seeing two. Am I overlooking one? If so, please point me at it. Anyway, this is how I am writing the requirements user stories for the two I see above:

• As a consumer of WoT TDs, I want to know when or if writing a property returns a value so that I can understand when I can use this value to confirm writes.
• As a producer of WoT TDs, I want to be able to specify simple security schemes inline so that TDs are less verbose and easier to write in simple cases.

[egekorkan]

The third one is w3c/wot-usecases#303

Just on the first user story, it is also to show or deliver any information at all to the user application. So far, it is underspecified.