Meta Operation Payloads and Semantics

[egekorkan]

Submitter Contact Information

@egekorkan

Main Stakeholder

Eclipse Thingweb node-wot

Other Stakeholders

All Consumer implementations that only have a TD to build the correct request for meta operations

Details

Capability

Description of input and output needed for meta operations in a TD

Details

Any implementation that requires to build the correct request for meta operation such as `writeallproperties`, `readallproperties`, `readmultipleproperties` and to understand the response(s), currently does not have enough information in a TD. For example:

- How is the list of properties sent in `readmultipleproperties`? 
- What if `readallproperties` returns a different payload than a map?
- What happens in the case of other serialization formats than JSON?
- What if readmultiple is a static set of properties, which can happen in MQTT with wildcards
- Does `observeallproperties` return all properties no matter if they have changed or only the changed properties are sent?

The issues are labeled on the TD repo: https://github.com/w3c/wot-thing-description/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22meta%20operations%22
From most relevant to least, probably:

- https://github.com/w3c/wot-thing-description/issues/1349
- https://github.com/w3c/wot-thing-description/issues/1231
- https://github.com/w3c/wot-thing-description/issues/1643
- https://github.com/w3c/wot-thing-description/issues/1814
- https://github.com/w3c/wot-thing-description/issues/1976
- https://github.com/w3c/wot-thing-description/issues/1631

Note: This is protocol dependent but a level of abstraction is probably needed

Purpose

build correct requests and handle the response without trial and error

Details

Motivation

- https://w3c.github.io/wot-usecases/#UC-leaving-and-coming-home-1
- https://w3c.github.io/wot-usecases/#UC-retail-all-stop-button-outdoor-emergency-stop-plunger-1
- Probably most use cases are effected by this

[egekorkan]

After filling this:

• I think the headers with Details need the category name as well, i.e. Stakeholder Details
• We should automatically label the issue with the yaml template

[mmccool]

Find this a bit too high-level and abstract, and the capability points to a lot of issues but not a definition of the specific capabilities (there seem to be a lot) needed.

It would help to:

• Give a clear definition of "metaoperations" under "Details" for the Capability, or link to the Terminology section
• Maybe break this into a set of smaller user stories so each can be more precise