#736: Web of Things (WoT) Architecture 1.1

Visit on Github.

Opened May 3, 2022

Ready for review. The WD will be updated shortly based on branch architecture-1.1-pre-cr-wd

Braw mornin' TAG!

I'm requesting a TAG review of Web of Things (WoT) Architecture 1.1

The W3C WoT formally describes the interfaces of IoT devices and platforms to ease integration across IoT ecosystems and application domains. Rich metadata based on URIs, hypermedia controls, and collaborative schema definitions allows clients to adapt to the peculiarities of a given IoT platform by configuring its protocol stack.

The WoT Architecture document serves as an umbrella for all WoT specifications, and sets the general goals of the W3C Web of Things. It defines the abstract architecture and the design space for current and future WoT building blocks, which are specified in separate documents.

Further details:

  • I have reviewed the TAG's Web Platform Design Principles
  • Relevant time constraints or deadlines: CR Transition planned for 30 August 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):
  • Major unresolved issues with or opposition to this specification:
  • This work is being funded by:

You should also know that...

  • Security and Privacy Questionnaire was done for WoT as a whole, but answers call out individual deliverables as appropriate.

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


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

Discussions

2022-06-13

Minutes

Amy: I'll draft a comment on this for the plenary which might also cover Discovery. Use case is that parties that want to put content side by side are being considerate and throughtful of user's privacy. So who does that?

2022-06-20

Minutes

Amy: they lean heavily on a non-normative document... asking how they test for conformance... They have 2 security docs... Also looked through the PING minutes... Will check in with Tess. lots of non-normative text in arch document. I went through the MUSTs and SHOULDs... a few are redundant... some seem like they could live in other specs... Some seem pointless / not conformance statements.

Dan: more like a value.

Amy: you wouldnt' be looking at the spec if you weren't in some kind of network... Seems like it's not worth having it there. Whole arch section marked as non-normative... made a few suggestions for how they might rearrange the doc. And then just reposition and turn arch doc into a note. Feel it would be much more digestable.

Hadley: happy to ship this feedback - strengthened a bit... it would help the spec authors to think about it better to meet the needs of their users... tie it to "implementers' needs"...

Max: very good start. One comment regarding the last part - concern about abuse of connected devices. Not relevant to this draft... the concern you raise is concern about general internet of things. For example connecting devices to the web platform may cause concern.

Amy: my thought is that .. when bad things happen outside the web .. when they happen on the web the harm is amplified because it connects to more people. I can make it more clear. Any potential abuses on internet connected devices would be amplified.

Dan: to amplify that... one feedback we had in the previous review was that we want the web to be a more ethical platform, which is why we wrote the Ethical Web Principles. We want the people building the web to be thinking about these use cases and to be building in mitigations. So when you use the Web of Things, it's less possible to abuse the system like you can with Internet of Things devices.

...It's one of the things that may have prompted them to include lots more security and privacy stuff in 1.1, which is great. We want to positively reinforce that, and add that we have additional thoughts, in a way that is not hitting them over the head.

Dan: Amy you are empowered to edit this feedback with the above comments taken on board and post it. And mark the issues as proposed closing so we can close at plenary.

Amy: I will also send a comment to discovery

Amy's draft feedback:

Thanks for the review request, and apologies for the delay. Being unfamiliar with the Web of Things work previously, I have done my best to review the set of related specs (Architecture, Description, Discovery, and security and privacy documentation) as thoroughly as possible.

We discussed this during our meeting today, and this feedback represents TAG consensus.

## Security & Privacy

Overall we are happy with the direction, and really appreciate the extensive security and privacy work that has been done. Treating all Thing Descriptions as if they contain PII is a sensible precaution. Making the Security and Privacy considerations normative makes a strong statement, though we'd like to know how you have been testing these requirements for conformance purposes?

The spec refers normatively to the [Security and Privacy Guidelines](https://w3c.github.io/wot-security/), but this is a NOTE, not a normative document and so can't be used as a normative reference. Are you planning to republish the Guidelines at some point (as it seems to have been updated since its last publication)? Also the [Security Best Practices](https://w3c.github.io/wot-security-best-practices/) document appears to currently be unpublished - what status are you planning to give to this? How does it relate to the Guidelines?

## Architecture

Regarding the Architecture specification specifically, the vast majority of the text is non-normative, and, while interesting and useful, we are not sure is appropriate for a REC-track document. Further, you have sections marked as non-normative (eg. [8. Abstract WoT System Architecture](https://w3c.github.io/wot-architecture/#sec-wot-architecture)) which contain normative MUSTs and SHOULDs.

Some of these statements could be moved to other REC-track documents - eg. regarding Thing Descriptions - if the relevant documents don't already make the same statements.

Some seem to be entirely unnecessary - eg. in [8.1.2 Links](https://w3c.github.io/wot-architecture/#links), that "Things MUST be hosted on networked system components [..]". Apologies if this has been misunderstood, but this seems more of a foundational premise than a feature to test for conformance purposes.

Some are redundant - eg. in [12.1.1 Thing Description Private Security Data Risk](https://w3c.github.io/wot-architecture/#sec-security-consideration-td-private), "MUST ensure that only Public Security Metadata is ever stored" and "MUST ensure that no Private Security Data is included" seem to be saying the same thing from different directions.

There are a number of normative references to non-normative documents - in [one case](https://w3c.github.io/wot-architecture/#bib-solid) to a document index rather than any specific specification - which need to be made into informative references.

Having reviewed all of the MUSTs and SHOULDs in the specification, our thought is to break the Security and Privacy sections into a separate, fully normative, Security and Privacy document. Then, to work through the remaining normative statements to see which are strictly necessary (ie. for interop, and testable) and of those which can fit in existing REC-track documents. The remainder of the Architecture document would work well as an informative NOTE, which provides additional background and context without implementers needing to sift through it to find what they actually need to design and build conforming Things.

We recognise that you've only asked us to review the difference between 1.0 and 1.1, and this kind of feedback is coming as a result of me personally not having been involved in the earlier review. However, given comments [1, 2] about how hard this has been to review, we'd say it's never too late (or too early) to make specifications more readable! We would be more than happy to re-review if this change is made.

[1] [2022-05-19 PING minutes](https://www.w3.org/Privacy/IG/summaries/PING-minutes-20220519#web-of-things-architecture-privacy-review)

[2] [2019-07-11 previous TAG review comment](https://github.com/w3ctag/design-reviews/issues/355#issuecomment-510337214)

## Compatibility

We can see a lot of work to survey the current (and, presumably, ever-changing) landscape of IoT devices, and the effort to bring fragmented ways of operating together. Can you summarise, or link to a summary of, what the compatibility story looks like in practice? Eg. what widely used devices would be compatible with this architecture out of the box? Or what would needed to be added to make them compatible? What is practically possible with what is out there today, if this suite of specs are published as-is? A few concrete examples would be really nice to help give us a better picture of the ecosystem.

## Bonus points

From an editorial perspective, implementers who are approaching this set of specifiations for the first time may be deterred by the volume of text. In particular where sections or paragraphs do not relate to specific, implementable requirements. The specification abstracts are all rather long and we think all of the specs would benefit from a thorough proof-read, with an eye to removing redundant text, simplifying language, removing filler, and overall shortening throughout. While background and context are useful, we would encourage containing such sections in their own documents, which may be optionally read, and keeping only the informative language that is really crucial for implementation in the specifications themselves.

We remain naturally concerned about the potential for abuse using internet-connected devices, most of which are in some way very personal even where they might be part of a large network, in a smart city or similar. The Web can further amplify such threats, or make them easier to carry out. We recognise that there is only so much that can be done in a technical specification and that ultimately you have little control over how malicious people or groups might use or mis-use devices or networks. That said, if members of the WG could find time to work through the [Societal Impact Questionnaire](https://w3ctag.github.io/societal-impact-questionnaire/), we would be very interested to see some discussion or notes on some or all of the questions from the WoT context. This is a draft document, and a work in progress, and filling it in is not a requirement for progressing the TAG review. (Feedback on the questionnaire itself, additional questions, etc, are all welcome too.)

Thanks again for your work. We anticipate closing this and the related issues, but await your acknowledgement of our feedback and an indication of your next steps.
2022-07-18

Minutes

Amy: still working on breaking up my comments into issues in their repo. There was a response about a security thing.

[bump to f2f]