search

w3c / wot-profile

Web of Things (WoT) Profile
http://w3c.github.io/wot-profile/
Other
16 stars 8 forks source link

Make it clearer that it's not necessary to implement a profile to be WoT-compliant #402

Closed benfrancis closed 2 weeks ago

benfrancis commented 2 months ago

@egekorkan mentioned on the WoT mailing list that "Some within Siemens thought that one must implement a Profile to become a WoT-compliant implementation, which is not the case."

I just re-read the introduction to the WoT Profiles specification and I think section 1.1 Motivation explains this fairly well, but perhaps there is room for improvement. What text could be added here to make this more clear?

Otherwise, this might be a case of improving documentation elsewhere, such as on the W3C WoT website https://www.w3.org/WoT/documentation/

egekorkan commented 2 months ago

I need to check where the root of the confusion comes from but my guess is that it is possible to understand that the lack of out-of-the-box interoperability is no interoperability at all, which is not the case.

mlagally commented 2 months ago

I also reviewed the https://w3c.github.io/wot-profile/#motivation section agen and agree with @benfrancis and @egekorkan, that it should be improved. Here's a proposal:

The Thing Description specification is designed to be protocol-agnostic and flexible enough to describe a wide range of existing ("brownfield") IoT devices, rather than specifying a fixed protocol or application programming interface (API) which all devices must implement.

This open ended flexibility provides interoperability by describing devices that use different protocols in the same way by using Thing Descriptions. Thing Descriptions enable to generate a common UI for devices across different protocols in an interoperable way.

However additional requirements are necessary to guarantee ad-hoc interoperability on the Web of Things, because it's nearly impossible to create a single WoT Consumer [wot-architecture] which is guaranteed to be able to communicate with any Web Thing [wot-architecture] out of the box.

lu-zero commented 1 month ago

I like the proposed text, might be good to make a PR so we can land it and close this issue.

benfrancis commented 1 month ago

This open ended flexibility provides interoperability by describing devices that use different protocols in the same way by using Thing Descriptions.

This wording is a bit confusing. I initially read it as "devices that use different protocols in the same way", whereas what I think you're trying to say is that it provides a common mechanism for describing devices that use different protocols.

Thing Descriptions enable to generate a common UI for devices across different protocols in an interoperable way.

Generating a user interface is only one use case of a Thing Description.

Nit: "enable to generate" is not grammatically correct.

I've created a PR with my attempt at refining this section (text below):

The W3C WoT Thing Description [wot-thing-description11] specification defines an information model and JSON-based representation format for describing the capabilities of connected devices and the interfaces with which to communicate with them. Thing Descriptions are designed to be protocol-agnostic and flexible enough to describe a wide range of existing ("brownfield") IoT devices.

In order to provide this level of flexibility the Thing Description specification includes a number of extension points including protocol bindings, payload bindings, security mechanisms, link relations and semantic contexts. As long as all of the capabilities of a device can be described using a Thing Description and a Consumer implements all of the extensions used, the Consumer should be able to interoperate with that device. However, the result of this extensible architecture is that any given Consumer can only interoperate with a subset of possible Web Things.

This specification is designed to complement the Thing Description [wot-thing-description11] specification, by enabling ad-hoc interoperability through the use of "profiles". A profile prescribes a finite set of extensions and defaults that a Thing can be constrained to in order to guarantee out-of-the-box interoperability with any Consumer which implements that profile.

Profiles are designed specifically for new ("greenfield") implementations where developers have the freedom to conform to a prescriptive protocol binding and set of common constraints, in order to benefit from this additional level of interoperability.

Does this address the confusion?