Web of Things (WoT) Architecture

[mmccool]

Góðan dag TAG！

I am requesting a TAG review of:

• Name: Web of Things (WoT) Architecture
• Specification URL: https://cdn.staticaly.com/gh/w3c/wot-architecture/TAG-review/index.html?env=dev
• Explainer, Requirements Doc, or Example code: https://github.com/w3c/wot-architecture/blob/TAG-review/proposals/WoT%20Architecture%20Explainer.md
• Tests: N/A
• Github repo: https://github.com/w3c/wot-architecture
• Primary contacts: @mlagally, @mmccool, @mkovatsc

Further details (optional):

• Relevant time constraints or deadlines:
  • TAG review feedback expected by April 5th
  • CR transition planned for April 9th
    • last possible date to make June 25 deadline for REC
    • end of WG charter is June 30

Additional schedule details and constraints

• I have read and filled out the Self-Review Questionnare on Security and Privacy. The assessment is here; this assessment is shared with all Web of Things documents.
• I have reviewed the TAG's API Design Principles

You should also know that...

• The WoT Security and Privacy Considerations document provides extra discussion of security with an IoT focus.
• The related WoT Thing Description document is being submitted for TAG review at the same time.
  • Tests of implementations will be associated with this document
• The WoT Binding Templates informative WG note describes an optional WoT building block.
• The WoT Scripting API informative WG note describes an optional WoT building block.

We'd prefer the TAG provide feedback as (please select one):

• open issues in our Github repo for each point of feedback
• open a single issue in our Github repo for the entire review
• leave review feedback as a comment in this issue and @-notify [github usernames]

[mmccool]

The document had some broken links to the "WoT Security Best Practices" and "WoT Security Testing Plan" which I just fixed. I also added (in an editor's note) a link to the more up-to-date version of the WoT Thing Description document prepared for TAG review (along with a link to the previously published version).

[mlagally]

Since the initial submission of the architecture specification to TAG,
there were several terminology updates, which the architecture group
considers important to be part of the TAG review.

An update was provided in the TAG branch, the diff is at:
w3c/wot-architecture@9405c0a

The specification URL above refers to this version.

[mnot]

Just an observation. Having "binding layers" (in this case, WoT over HTTP/COAP/MQTT) is often a solution to a political problem, not a technical one, but it creates a lot of technical friction.

cf. Web Services.

[mkovatsc]

Just an observation. Having "binding layers" (in this case, WoT over HTTP/COAP/MQTT) is often a solution to a political problem, not a technical one

Yes, ideally all IoT products out there would use the same protocol. Unfortunately, this is not the case and it is a real technical problem for integrators, both in the consumer IoT space and the industrial IoT space. WoT originally got started to address this very issue, yet the hope is that we will see convergence over time toward the defaults defined by the WoT Thing Description.

[ylafon]

There is also an issue of upgradability of the software stacks involved, see TAG's Evergreen Finding which highlight the issue of security and evolution of implementations.

[ashimura]

@ylafon and @torgo we've been wondering about the final review results from the TAG, because we're planning to publish the update drafts as Proposed Recommendations on June 27th and want (wanted) to send out transition requests for the WoT Architecture (and the WoT Thing Description) today on June 20.

When I talked with @ylafon about the possible review results, he mentioned there would not be many comments in any case. So I'd like to confirm there would not be blocking comments for our Proposed Recommendation transition.

Regarding the comment above from @ylafon , we have "version" feature within the WoT Thing Description specification to manage the versions of the devices and applications. Also there was further discussion about data management during the WoT F2F meeting in Munich on June 6-7 and we're planning to include that topic (and more) in the updated WoT WG Charter for the next generation WoT standards. Please note that the current WoT WG's Charter expires the end of June and now we're generating an updated WG Charter.

[dbaron]

I might have some comments coming; I'll try to write them on Monday, though it's not clear to me how many would go here rather than in #357.

[ashimura]

Thanks a lot, @dbaron !

[dbaron]

My biggest concern here is probably around the tradeoff (alluded to above) between good interoperability versus complete coverage of existing devices. It seems like this set of specifications has built an architecture that falls far to one side of this tradeoff: it's chosen a complicated binding mechanism that requires plugfests to get implementations to interoperate with each other, and allows a wide range of binding layers some of which don't have solid specifications defining their URI schemes in an interoperable way or other obstacles to a clear path to interoperability. (This is the major point where the alternative Mozilla proposal takes a different approach; for each property, action, or event described, instead of the forms in the W3C Thing Description that allows many ways to connect to the thing for which the group has documented a number of binding templates, the Mozilla proposal describes links that must correspond to a much more fixed REST API or WebSocket API.)

Another concern here is the references to the scripting API which appears to be optional and (as I understand it) lacks implementor interest. It seems like if it's not going to become a part of the architecture, it would be better to acknowledge that reality.

I'm also concerned that the architecture overview says "The format can be processed either through classic JSON libraries or a JSON-LD processor": is this defined in a way such that both types of processing will yield the same results in all cases? If not, what leads to interoperability?

A few other notes:

• The definition of privacy (currently "The system should maintain the confidentiality of Personally Identifiable Information.") given seems far weaker than it should be. A better definition seems like it should consider concerns over information that is not (on its own) PII, and should consider the risks of sharing information even when it is kept confidential. It may be preferable to link to an existing definition elsewhere rather than writing your own.
• Likewise, the definition of security (currently "The system should preserve its integrity and functionality even when subject to attack.") appears (although it's a bit unclear) not to include revealing private information as a failure of security.
• The references section omits the names of authors for a number of the references that should have them. (This seems most important for the ones that don't have URLs.)

Also a few thoughts on the security and privacy considerations which I've reviewed somewhat quickly:

• The idea that thing descriptions shouldn't carry identifying information seems over-optimistic to me. It seems like (at least from the perspective of smart home use cases) thing descriptions are likely to have a significant amount of sensitive and identifiable information (although it might not be initially obvious how the information is sensitive), and systems need to be designed appropriately.
• The opening sentences of the section on software update (before the "Mitigation:") appear to suggest that avoiding having a software update system at all would be the best mitigation. While it's absolutely true that designing a secure software update system must be done carefully, experience has shown that having prompt software update to mitigate security vulnerabilities is essential for internet-connected devices, and (see The evergreen Web finding) essential for the progress of the Web.

[mlagally]

Dear TAG members,

since the initial request to TAG in March, the architecture specification has advanced significantly in the last months to pass the CR milestone.

There were some changes (e.g. the Binding Template specification as an informative reference),
so please review the version at https://w3c.github.io/wot-architecture.

Please provide the TAG provide feedback as individual issues in our Github repo for each point of feedback.

Many thanks,

Michael Lagally
WoT Architecture Co-Editor

[kenchris]

Hi there, @torgo asked me to look at the https://w3c.github.io/wot-scripting-api/

I have already gone over that a couple of time with @zolkis as he has asked for my input. To get some discussions going for our TAG meeting tomorrow, I had a quick glance over the latest API, so this is just a collection of random thoughts.

• Promise<object> readAllProperties(); <- shouldn't that be an async iterator?
• Same counts for Promise<ThingDescription> next();
• void emitEvent(DOMString name, any data); <- maybe follow the "dispatch" pattern, ie dispatchEvent
• The global IDL over view lists an empty interface WOT and then 3 partial interface WOT - can they be joined - might be a spec tooling issue.
• properties and events have a special meaning on the web, so I think that reusing the names might be confusing from a web perspective as they are not the same. Maybe others have comments?

[zolkis]

Thanks @kenchris .
The partial WoT interfaces come from the conformance classes (same reasoning and similar formulation as with the Presentation API). One can implement client, server and discovery in any combination.

The API has to be implementable in constrained environments, which usually have ECMAScript 5.1 and Promise backport.

readAllProperties() denotes a contract to read the state (as of multiple Properties) in one transaction. That is translated to a specific protocol request in a supported IoT deployment. That is the async part. Fetching the properties from the reply (as an object) is synchronous.

Emitting a WoT Event is again slightly different than emitting a JS event. You are right that properties and events have meanings in various contexts, that is why we defined their WoT specific counterparts in the WoT context. It might indeed be confusing, however this part should be discussed in the WoT Architecture and Thing Description, since the scripting API just follows the terms as defined there.

However, discovery could in theory be modeled with an async iterator, the problem is again semantics: the discovery-next() MAY issue a protocol request and wait for the answer.

[danielpeintner]

Thanks @kenchris

properties and events have a special meaning on the web, so I think that reusing the names might be confusing from a web perspective as they are not the same. Maybe others have comments?

FYI: The WoT Scripting API is meant to provide a scripting layer on top of the WoT thing description (which defines three types of interaction affordances: properties, actions, and events). Hence we aimed for using the same terms.

[mlagally]

Hi @torgo,

many thanks for the feedback from the TAG group in the respective repositories.
It is very useful for us to get some "fresh brains" look at the specifications,
since after a long time of discussions and spec creafting various terms and
conventions become very familiar, and is some cases we are no longer able to judge,
if there is language or concepts, that require more explanations.

For the architecture specification it would be ideal, if TAG would focus
on the normative chapters 4-7, specifically on chapters 6 and 7, and consider
if these chapters are clear for a new reader.

Many thanks,

Michael

[torgo]

Hi @mlagally : In reading through WoT Architecture again I have also taken a look at the Security & Privacy Document and one small piece of feedback I have is that I think something is missing from 3.3.1 (Home Environment Threats): specifically the threat of a user of the web thing using it to surveil another person without their knowledge or consent. I know this is a tricky one but it feels like something that we should be considering how to mitigate against if we want a web-of-things environment to be more privacy-friendly than a proprietary-based environment (in line with the Ethical Web Principles).

[kenchris]

I am OK with closing this issue

[hadleybeeman]

Hi @mlagally, @mmccool, @mkovatsc. As you requested, we looked the normative chapters, particularly 6 and 7, and think they are very clear for a new reader. Well done!

We'll close this review now. Let us know if we can do anything else to help.

[hober]

See also Pete Snyder's email to public-privacy yesterday.