generic UI support

[mlagally]

The profile must contain enough information to enable consumers to build a generic UI.
Typical UIs for IoT applications contain at least text labels, units, gauges, timeline graphs.

[benfrancis]

Similar to #136, we agreed months ago that human readability is out of scope for the Core Profile, which is focused only on interoperability.

Are you proposing that we re-visit the scope of the specification again just over a month from our feature complete deadline?

This requirement and #136 are certainly not compatible.

We could re-visit whether human readability should be a goal of the Core Profile since it is at least not incompatible with an HTTP protocol binding, but I suggest we need group consensus in order to change direction again so late in the publication schedule.

[benfrancis]

Following up on comments from other issues...

What exactly would it mean to make members like title and description mandatory? Would it mean that a WoT Consumer must stop parsing a Thing Description if these members are missing and not allow a user to interact with the device? That seems like a barrier to interoperability rather than an aid.

I'm not arguing that these strings are not important, of course they are important for usability and developers should absolutely be encouraged to include them in all Thing Descriptions (not just those following the Core Profile). But imagine if a web browser refused to render a web page just because it had a missing <title> tag or <meta name="description"> tag, or because it had too many levels of nested <div>s in the page*. Large parts of the web would just stop working.

The general approach on the World Wide Web is to make a best effort based on the content made available to the client and apply a series of fall-backs, not to just stop processing altogether if something that would be desirable to have is missing. There are other systems of incentives like search engine rankings and richer UI representations which encourage best practices.

For a web page, if no <title> element is provided for a page then browsers tend to fall back to displaying the URL.

For a Thing Description, if no title member is provided for an interaction affordance, then it can fall back to the interaction name provided as the key in the map.

I agree with the principle that Thing Descriptions should provide human-readable strings to help with the automatic construction of a UI, but refusing to interact with a device because it has a missing description member in one of its interaction affordances doesn't seem like the best way to incentivise that.

Instead, my suggestion is to propose a set of recommendations in the Thing Description specification which define best practices for all Thing Descriptions, not make these constraints mandatory parts of an interoperability profile, since that could have the opposite than intended effect.

---

*Actually that last one doesn't sound like such a bad idea, maybe we should suggest it for the HTML specification 😂

[mlagally]

I'm not arguing that these strings are not important, of course they are important for usability and developers should absolutely be encouraged to include them in all Thing Descriptions (not just those following the Core Profile). But imagine if a web browser refused to render a web page just because it had a missing <title> tag or <meta name="description"> tag, or because it had too many levels of nested <div>s in the page*. Large parts of the web would just stop working.

I think the IoT deployments we are targeting with the Web of Things and specifically the Profile are very different from the "best effort, everything is permissible and works somehow" approach.

This is the purpose of the validation section and the JSON schema - the profile will impose interoperability guarantees that consumers can rely on, not just "yeah you SHOULD do it but if you are under time pressure it is fine to just ignore it"

When a consumer relies on mandatory titles for constructing a UI and the title is not present it cannot build a UI. The schema validation has already rejected that TD, so it is not profile compliant.

[benfrancis]

@mlagally wrote:

When a consumer relies on mandatory titles for constructing a UI and the title is not present it cannot build a UI.

But if it doesn't rely on mandatory titles then it could still construct a UI by falling back to interaction affordance names instead.

The schema validation has already rejected that TD, so it is not profile compliant.

To clarify, are you saying that if a Thing Description is just missing a description member from one of its interaction affordances, that would render the whole Web Thing unusable by a compliant WoT Consumer?

If so then that doesn't sound like an "interoperability guarantee" to me, it sounds like a non-interoperability guarantee.

[egekorkan]

To clarify, are you saying that if a Thing Description is just missing a description member from one of its interaction affordances, that would render the whole Web Thing unusable by a compliant WoT Consumer?

Maybe a generic solution to this would be nice, i.e. what happens when I say I am profile compliant but I am not. There are cases where this can be detected by schema, like lack of descriptions or contentType, and cases where it cannot be put in a TD (at least is not mandated in profile spec) like response with status code 200 for readproperty. Let's name the schema-detectable cases case 1 and the other one 2:

1. The consumer has the schema of the core profile. It makes validation step and finds an error, what should happen? Simply stop using the TD or try to do everything as usual? I think that trying to find OK failures (like lack of description) and fatal ones (like using MQTT instead of HTTP) is a bit difficult since parsing JSON Schema validator results is not so easy and asking each consumer to do that is a bit too much I think.
2. The consumer has a very strict implementation that follows the profile spec word by word. Ideally, it should throw an error if a readproperty is responded with 201 instead of 200. Or should it?

My proposal would be to properly think of the use MAY/SHOULD/MUST where MUST assertion imply that the Thing/TD will behave in a specific way and failure to do so means that Consumer stops using the Thing. SHOULD would mean that this feature should not cause a failure in the Consumer implementation, meaning that Consumers should implement handlers for SHOULD based features.

[danielpeintner]

1. [...] I think that trying to find OK failures (like lack of description) and fatal ones (like using MQTT instead of HTTP) is a bit difficult [...]

I think it is even more complicated. I assume a TD can still be profile compliant even if it has an MQTT form. It only needs to have an HTTP form also for each interaction. If we forbid such situations, it is no longer possible to have a TD that is compliant to the profile and maybe other profiles in the future.
Am I wrong?

[benfrancis]

@egekorkan wrote:

My proposal would be to properly think of the use MAY/SHOULD/MUST where MUST assertion imply that the Thing/TD will behave in a specific way and failure to do so means that Consumer stops using the Thing. SHOULD would mean that this feature should not cause a failure in the Consumer implementation, meaning that Consumers should implement handlers for SHOULD based features.

I agree with this, but for me it again raises the question of if all we're saying is "A Web Thing SHOULD provide a title" in order to improve usability, then why not apply that assertion to all Thing Descriptions in the Thing Description specification rather than only for the Core Profile. Why should titles only be recommended for the Core Profile? It has no impact on interoperability and is equally applicable to greenfield and brownfield devices.

@danielpeintner wrote:

I think it is even more complicated. I assume a TD can still be profile compliant even if it has an MQTT form. It only needs to have an HTTP form also for each interaction. If we forbid such situations, it is no longer possible to have a TD that is compliant to the profile and maybe other profiles in the future.
Am I wrong?

You are wrong in the sense that currently there's currently an assertion in the WoT Core Data Model section which prevents this. But I completely agree with you that it should be possible for a Web Thing to conform with the Core Profile whilst also supporting other profiles and/or protocols, which is why about a year ago I filed #60 to suggest removing that assertion.

[relu91]

I'm leaving this comment after my review. I agree with the direction of taking this human readability constraint elsewhere. In particular, I think this issue is something already well known on the web and in the industry.

The usual pattern is to leave it to additional tools or specs that describe guidelines about good behaviors and well-known patterns. Additionally to @benfrancis's example above I want to mention that the same applies to code. A browser does not care about the "readability" of a piece of code it just needs to be sufficiently valid to understand how to execute it. Then people came up with tools to enforce a good code quality like https://eslint.org/ or, regarding markup languages, https://developers.google.com/web/tools/lighthouse (for Web Pages).

The same stands for Thing Descriptions they must be "operatively" valid: it must be possible to invoke/read/write/subscribe/observe any of its affordances. Then we can define linting rules to recommend good behaviors that will allow humans readability, better UIs, etc. To me, this sounds like a good separation of concerns between what are the minimal requirements to make something work and how to build/maintain a complex system of components.

Therefore, my proposal would be to move completely the discussion in w3c/wot-thing-description#1195 and close this issue.

@danielpeintner wrote:

I think it is even more complicated. I assume a TD can still be profile compliant even if it has an MQTT form. It only needs to have an HTTP form also for each interaction. If we forbid such situations, it is no longer possible to have a TD that is compliant with the profile and maybe other profiles in the future.
Am I wrong?

You are wrong in the sense that currently there's currently an assertion in the WoT Core Data Model section which prevents this. But I completely agree with you that it should be possible for a Web Thing to conform with the Core Profile whilst also supporting other profiles and/or protocols, which is why about a year ago I filed #60 to suggest removing that assertion.

I agree with this too, but it is a separate issue tracked in #60 (as mentioned).

[mlagally]

The usual pattern is to leave it to additional tools or specs that describe guidelines about good behaviors and well-known patterns. Additionally to @benfrancis's example above I want to mention that the same applies to code. A browser does not care about the "readability" of a piece of code it just needs to be sufficiently valid to understand how to execute it. Then people came up with tools to enforce a good code quality like https://eslint.org/ or, regarding markup languages, https://developers.google.com/web/tools/lighthouse (for Web Pages).

This is not about beautifying code or making sure that that things are matching to a style guide.
It is about ensuring a guaranteed minimum level of out-of-the-box interoperability.

Automatic integrating multiple things from different vendors without further guidelines, documentation etc. is a KEY use case of the Profile. How do you build a dashboard if you cannot put labels on a UI because you don't have tiles? How do you place a description in a hovering text box?
How can you display a gauge or a graph if you don't know the range? How do you handle numeric values without a unit when you have different teams cooperate?

[relu91]

This is not about beautifying code or making sure that that things are matching to a style guide.

Indeed to me, the aforementioned tools are more than just styling guides. They can convey good practices that allow developers to understand and use the code better.

Automatic integrating multiple things from different vendors without further guidelines, documentation etc. is a KEY use case of the Profile. How do you build a dashboard if you cannot put labels on a UI because you don't have tiles? How do you place a description in a hovering text box?

You can still have such systems with the fallback mechanisms described by @benfrancis, just not "beautifully" described/visualized systems 😃 .

How can you display a gauge or a graph if you don't know the range? How do you handle numeric values without a unit when you have different teams cooperating?

I've realized that this issue has a broader scope than rather just human-readable information. I was specifically commenting on TD fields that just convey human documentation (title, description, and their brothers' titles and descriptions). IMHO range ( minimum and maximum etc. from the https://w3c.github.io/wot-thing-description/#integerschema) and unit have a Data Type functionality that might, indeed, influence interoperability.

[benfrancis]

See also: #152 (comment)

[mlagally]

Defer to Profile 2.0.
We should revisit once we have APA requirements.