Web of Things (WoT) Thing Description 1.1: TAG and Security Review

[mmccool]

Braw mornin' TAG!

I'm requesting a TAG review of the Web of Things (WoT) Thing Description 1.1.

In the WoT Architecture, a Thing is defined as an abstraction of a physical IoT device such as a sensor (temperature, CO2, ...), an actuator (lamp, motor, ...), or a virtual entity (e.g., composition of one or more Things, a weather service). The Thing Description (TD) provides descriptive metadata for a Thing's network interface.

• Explainer¹ (minimally containing user needs and example code): Explainer11.md
• Specification URL: the lastest stable published version is here: 2022-03-11 WD. However, the current Editor's Draft has an updated set of Security and Privacy considerations.
• Tests: Testing process (WIP) in github; see also the draft implementation report
• User research: Use cases (includes stakeholder input)
• Security and Privacy self-review²: answers for TD1.1
• GitHub repo (if you prefer feedback filed there): repo
• Primary contacts (and their relationship to the specification):
  • Sebastian Kaebisch, Siemens AG
  • Takuki Kamiya, Fujitsu Research of America
  • Michael McCool, Intel
  • Victor Charpenay, Siemens AG
• Organization(s)/project(s) driving the specification: N/A
• Key pieces of existing multi-stakeholder review or discussion of this specification: see use case document above
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): N/A

Further details:

• [x] I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines:
  • Detailed schedule for all deliverables
  • TD 1.1 proposed milestones:
    • CR Candidate (e.g. including fixes for feedback points): May 1, 2022
    • CR Transition: mid-May, 2022
    • PR Transition: mid-June, 2022
• The group where the work on this specification is currently being done: WoT WG
• The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): WoT WG
• Major unresolved issues with or opposition to this specification: None (WIP: may want to link to outstanding issues in tracker that have been pushed to TD 2.0)
• This work is being funded by: members

You should also know that...

• Previous review of 1.0 version

In the Thing Description 1.1 specification, text and table entries highlighted with a yellow background will indicate a feature associated with an at-risk assertion for which insufficient implementation experience exists. When an entire section is at-risk the words "This section is at risk." will be placed at the start of the section and highlighted with a yellow background.

• The WoT Security and Privacy Considerations document provides extra discussion of security with an IoT focus.
• The related WoT Architecture 1.1 document is being submitted for TAG review at the same time.
• The related WoT Discovery document will be submitted for TAG review shortly.
• The related WoT Profile document will be submitted for TAG review shortly.

There are also some related informative documents:

• The WoT Binding Templates informative WG Note describes an optional WoT building block. This Note explains how to use the WoT Thing Description for specific IoT protocols.
• The WoT Scripting API informative WG Note describes an optional WoT building block, and describes a JS API that can be used to implement behaviour in a WoT Thing (exposing a network API described by a WoT Thing Description) or a device consuming (reading) a WoT Thing Description.
• The WoT Use Cases and Requirements informative WG Note includes a collection of stakeholder-submitted use cases driving requirements.

During the TAG review period, we plan to update the test results in the implementation report to reduce the number of at-risk assertions as much as possible before CR submission. The link above refers to the master branch of the repository, not the TAG-review branch.

We'd prefer the TAG provide feedback as (please delete all but the desired option):

🐛 open issues in our GitHub repo for each point of feedback

---

WIP! Will delete below only once this issue is complete and the referenced documents are ready for review.

CAREFULLY READ AND DELETE CONTENT BELOW THIS LINE BEFORE SUBMITTING

Please preview the issue and check that the links work before submitting.

In particular, if anything links to a URL which requires authentication (e.g. Google document), please make sure anyone with the link can access the document. We would prefer fully public documents though, since we work in the open.

¹ We require an explainer to give the relevant context for the spec review, even if the spec has some background information. For background, see our explanation of how to write a good explainer. We recommend the explainer to be in Markdown.

² A Security and Privacy questionnaire helps us understand potential security and privacy issues and mitigations for your design, and can save us asking redundant questions. See https://www.w3.org/TR/security-privacy-questionnaire/.

[mmccool]

Ready for review.

[maxpassion]

Hi, I have a clarification question: does this specification aim to work only for the IoT devices that have an IP address?

[egekorkan]

Hi @maxpassion :

Hi, I have a clarification question: does this specification aim to work only for the IoT devices that have an IP address?

We have looked at your question at the TD call of 20.04. There can be two parts to this question:

1. Does this specification aim to work only for the IoT devices?
2. Does this specification aim to work only for the IoT devices that have an IP address?

• Regarding 1: The WoT TD is not meant for general web services, but there are often web services associated with IoT systems, such as proxies, shadows, and digital twins, for which WoT TDs are appropriate.

• Regarding 2: Until now, we have focused on IP-based protocols, such as HTTP, CoAP, MQTT etc.

If you would like more information, we can schedule a joint call or you can join our main call (https://www.w3.org/events/meetings/18c35c2a-47d6-44fe-b198-e438256544f3/20220427T080000)

[torgo]

Hi folks - we discussed in today's TAG call. We're largely happy with this. We'll keep this open until we get the review requests for the other WoT items - particularly the architecture - so we can do a more thorough pass.

[hadleybeeman]

Hi @mmccool! Thanks for this. We've reviewed it in our W3C TAG meetings this week.

Apologies for the delay; we wanted to look at this in parallel with (our review of Web of Things (WoT) Architecture 1.1.

It looks fine to us, and we are happy to see the strengthened security and privacy work.

We also note that your issue 791 from our previous review, should be clearer about where the definition of the HTTP Protocol Binding is, is still open. Can you tell us a bit about your thoughts/plans for this? It looks like you're choosing to defer it — we are curious to hear if it's causing you trouble or why deferring it made sense for the group.

Many thanks!

[egekorkan]

Thank you for the positive comments! Regarding the HTTP Binding Issue:

Until somewhat recently, the binding templates document was a monolith with everything put together. Now, each protocol has its own document that can be clearly referenced. However, with TD 1.1 we want to stay backwards compatible and we cannot remove such an important part. With TD 2.0, this will be possible and it would make more sense that way.

[hadleybeeman]

Thanks, @egekorkan — that's helpful.

We'll close this then, and put the bulk of our feedback on Web of Things under our TAG design review for Architecture 1.1.