Why is Mozilla Web Thing API different from W3C Web of Things?

[Yacubane]

Recently, W3C WoT was published as official recommendation from W3C. W3C's WoT has some differences from Mozilla's implementation of Web Thing API. It seems that Mozilla based their API on older version of W3C's WoT. In docs we can read:

This proposal is intended to complement the current W3C Web of Things Working Group's

While the standardisation process continues, this document will continue to be maintained to reflect the current API implemented by Mozilla's own open source Web of Things implementation through Project Things.

Does it mean that Mozilla will stay with their similar but not the same API? Are there plans to migrate to official W3C WoT?

[mrstegeman]

For the most part, the two specs are compatible, and our thing descriptions may validate as W3C-compliant thing descriptions at this point.

The biggest difference is that we have concrete protocol bindings for HTTP and WebSockets. The W3C opted not to include any protocol bindings in their spec, instead opting to use the forms member to allow for an API description.

The problem is that this method is too generic, making it nearly impossible to build a client that can interact with any W3C-compliant device. Furthermore, it's actually impossible to describe our actions API via forms.

Due to these differences, we've opted to keep a different spec for now. There is a W3C Community Group working on a WebSocket protocol binding, so if they succeed with that (and hopefully an HTTP binding), we could probably merge the two.

[kgiori]

And on the #iot channel of chat.mozilla.org, @benfrancis gave this explanation:

benfrancis

Exciting news, the W3C Web of Things (Architecture and Thing Description specifications) just became official W3C recommendations https://www.w3.org/2020/04/pressrelease-wot-rec.html.en The Web of Things is now a standard.

madbilly

Great! So no more changes then? Is the Moz implementation the same as the W3C implementation?

benfrancis

No and no. Web standards are living standards and will continue to evolve, the Mozilla implementation is not currently the same as the W3C specification.

madbilly

So does that mean that the WebThings gateway will get another update mrstegeman and what would that mean for adapters/existing WebThings?

benfrancis

The Mozilla & W3C Thing Descriptions are very similar now. The biggest remaining difference is still links (https://iot.mozilla.org/wot/#link-object) vs. forms (https://www.w3.org/TR/wot-thing-description/#form) which in simple cases work the same, but are fundamentally different approaches in terms of whether a protocol for communicating with a device is defined declaratively in a Thing Description vs. in a separate specification. Mozilla's Web Thing API specification goes further than the W3C Thing Description specification in defining the actual request & response payloads of a REST API (https://iot.mozilla.org/wot/#web-thing-rest-api) and a WebSocket sub-protocol (https://iot.mozilla.org/wot/#web-thing-websocket-api). The basics of the REST API are covered by a set of defaults in the W3C specification (https://www.w3.org/TR/wot-thing-description/#http-binding-assertions) and the expectation was that the new WoT Profiles work item could define a full REST API. I intend to continue the standardization of the WebSocket sub-protocol through the Web Thing Protocol Community Group https://www.w3.org/community/web-thing-protocol/ The differences between the Mozilla specification and W3C specification are there for good reasons. So the question is whether Mozilla want to continue to maintain a separate specification with a view to converging via ongoing work in the new charter period, or give up their previous position and implement the current W3C specification in full. Or possibly neither given the current resources available to the project.

benfrancis

Another slight gotcha is that a Mozilla web thing won't respond in the way a W3C compliant WoT client would expect because it follows the Web Thing REST API specification rather than defining a payload format in a form. Resolving this difference is non-trivial. This is particularly true of action requests (https://iot.mozilla.org/wot/#actionrequest-resource), which are currently impossible to express in a W3C Thing Description because they create new resources which are subsequently fetched (this is a known limitation being addressed in a work item in the new WoT WG charter). Web Thing API

This document describes a common data model and API for the Web of Things. The Web Thing Description provides a vocabulary for describing physical devices connected to the World Wide Web in a machine

In summary, it's not as simple as just implementing the W3C specification, because the specification has known limitations. It would be possible to create a W3C web thing adapter in the meantime, though.

madbilly

Thanks for the explanation benfrancis, I remembered that there were differences and it seems they are still incompatible, so I presume that the Gateway won't be updated to match W3C. This is fine if the Gateway can support W3C things via another adapter though.

[Yacubane]

@mrstegeman @kgiori Thank you very much for detailed explanation! At this point I'm closing this issue.