Re: [w3ctag/design-reviews] Web of Things (WoT) Architecture 1.1 (Issue #736)

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.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/736#issuecomment-1162135635
You are receiving this because you are subscribed to this thread.

Message ID: <w3ctag/design-reviews/issues/736/1162135635@github.com>