Closed mmccool closed 2 years ago
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.
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, 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 document appears to currently be unpublished - what status are you planning to give to this? How does it relate to the Guidelines?
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) 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, 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, "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 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.
[2] 2019-07-11 previous TAG review comment
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.
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, 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.
Response from WoT Security TF:
Dear TAG members,
thanks again for your extensive review.
@rhiaro We will work through the soceital impact questionnaire: https://github.com/w3c/wot-architecture/issues/807 Is there a Markdown version of the questionnaire?
We will address your review comments in individual issues, these are tracked with a dedicated label: https://github.com/w3c/wot-architecture/labels/address%20TAG%20feedback
Hi @mlagally - the Societal Impacts Questionnaire is at the moment on the outside an html doc, but on the inside markdown, so you can take the text from this page for markdown versions of the headings and descriptions for each question.
@mmccool Thank you for your comprehensive responses about the Security and Privacy documents, I really appreciate you taking the time to explain that and highlight actions. That all sounds like a positive direction.
Based on the responses to feedback, and assuming adequate discussion of and resolution to the open issues (linked by github above) that will track the various points, I'm going to close this review request. If you do any major restructuring and think it would be helpful for us to re-review at some point, please do open another review request. I will continue to follow the progress you make on the open issues with interest, and hope that your work progresses smoothly.
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:
You should also know that...
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/.