Clarify concerns on Human readability

[mlagally]

No description provided.

[benfrancis]

Please see the feedback I already provided in #156 (comment)

Human readability

❌ Oppose

I think this should be addressed through recommendations in the Thing Description specification, not constraints in profiles.

This topic has now been discussed ad nauseam over a period of 2.5 years, see:

1. Reduce Number of Goals or Differentiate #7
2. Reduce or remove the constraints in section 7.2 Baseline Information Model #10
3. Human readable documentation #27
4. Consider creating a Constrained Profile #59
5. device categories - initial draft #70
6. Refine Goals and Scope #73
7. Restructure WoT Core Profile section #78
8. WIP: reworking data model section #93
9. Remove WoT Core Data Model and update Core Profile introduction - closes #10 #125
10. generic UI support #138

In the interests of closing this discussion, I have two further suggestions for resolving this issue:

Option 1 - Removal

The quickest way to resolve this issue, and my recommendation, is to simply remove this as a general goal of the WoT Profile specification given the number of objections (not just clarifications) provided by Working Group members regarding how this goal conflicts with other goals.

Note that there's nothing stopping someone from creating a linter tool, as @relu91 suggested, which can check a Thing Description for a set of recommended best practices. These best practices could even be formalised in a W3C Working Group Note like the Security and Privacy Guidelines.

Option 2 - Refinement

As I understand it, in the current specification this requirement basically boils down to whether the following members should be mandatory for Thing Descriptions complying to the Core Profile:

• title
• description
• created
• modified
• support

I assume this would mean that if one of these members was omitted, the Thing Description would be considered invalid and the Consumer would stop processing it. This would harm interoperability, since it would prevent a Consumer interacting with a Thing with an otherwise valid Thing Description, and it increases implementation complexity because a Consumer must validate these additional constraints when processing a Thing Description.

If other Working Group members are not willing to drop human readability as a general goal of the WoT Profile specification, and we're now too late to add human readability recommendations in the Thing Description 1.1 specification, then another alternative would be to make these constraints RECOMMENDED rather than MANDATORY for the Core Profile, and specify that Thing Descriptions which break these assertions SHOULD print a warning on the developer console, rather than just stop processing the Thing Description altogether. I suggest this could be achieved with two simple assertions in a Recommended Practices section of the Core Profile:

1. "It is RECOMMENDED that title, description, created, modified and support members are always provided where applicable, in order to improve human readability."
2. "If one of these members is not provided, Consumers SHOULD print a warning on the developer console to remind developers of this recommendation."

This would still increase implementation complexity, but it would mitigate the impact on interoperability.

Note: With this option, I suggest this goal should only be applied to the Core Profile and not a goal of all profiles, since it may not be appropriate for all future profiles, such as a Constrained Profile, where it would conflict with further requirements.

As I say, my preference is option 1.

[egekorkan]

Regarding option 2, I think we need to define a general approach on what happens when a TD claims to be compliant to a profile but is not. I can also open an issue about this but I think this was discussed somewhere that I am not finding now.

[mlagally]

I strongly prefer option 2 with a couple of additional considerations.

1. Please consider real world deployments and not development scenarios. Usually there will not be a developer, just a user. Think of your parents or untrained personnel which is just using / operating machinery. How frequently does a mobile phone user check the developer console? Do we expect a user who pays significant money for devices and consumers to read console logs?

2. We should move away from the "best effort fallback, make it work somehow" thinking. If you buy a device and it is profile compliant, it must work. No workarounds or "make it work 80%" of use cases. Think of consumers calling customer service of the thing manufacturer and asking for a refund.

3. When a TD is not profile compliant, a consumer must reject it. A consumer provides a guarantee to the user that all devices that are connected to it work as specified.
   If a device is not 100% compliant to the profile, there will be likely limitations on what the consumer can do with the device.
   When the consumer fails, the customer calls customer service of the consumer manufacturer and asks for a refund.

This is what is meant by "out of the box interoperability".

[benfrancis]

@mlagally wrote:

1. Please consider real world deployments and not development scenarios. Usually there will not be a developer, just a user. Think of your parents or untrained personnel which is just using / operating machinery. How frequently does a mobile phone user check the developer console? Do we expect a user who pays significant money for devices and consumers to read console logs?

It's not the end user who needs to know that the title/description of an interaction affordance is missing, it's the developer who created the Thing and is testing it with Consumers. If the description was omitted at development time then it's already too late for the end user.

2. We should move away from the "best effort fallback, make it work somehow" thinking.

This is how interoperability works on the web. If it worked the way you are proposing, browsers would refuse to render most web pages.

If you buy a device and it is profile compliant, it must work. No workarounds or "make it work 80%" of use cases. Think of consumers calling customer service of the thing manufacturer and asking for a refund.
3. When a TD is not profile compliant, a consumer must reject it. A consumer provides a guarantee to the user that all devices that are connected to it work as specified. If a device is not 100% compliant to the profile, there will be likely limitations on what the consumer can do with the device. When the consumer fails, the customer calls customer service of the consumer manufacturer and asks for a refund.

So you're saying that if a Consumer can't display a human-friendly description for a particular property (which may not even be in a language the user can read) because the developer forgot to provide it, then the Consumer should just refuse to communicate with the device altogether? And that's less likely to generate a customer service call?

This is what is meant by "out of the box interoperability".

I would call that "out-of-the-box inoperable" rather than "out-of-the-box interoperable". But I guess we still need to agree on a definition... #155

The approach you are describing would work if WoT was like Bluetooth, Zigbee or Wi-Fi where there was some kind of centralised testing and certification process WoT devices had to go through before they could be sold. But given that isn't how W3C standards work, implementations have to be resilient enough to cope with situations where developers aren't necessarily following best practices.

As an end user, which of the two options at the bottom would you prefer?

[mlagally]

Thanks @benfrancis for providing this example.
I have seen TDs which contain A1, A2, A3, A4 for properties. The UI in this case would be incomprehensible.
If we have proper validation / conformance verification, the example you describe does not pass, i.e. a device cannot claim to be profile compliant.

Note that the objective of the profile is to provide interoperability guarantees for industrial, home and other devices. It goes beyond a Web browser where different implementations may break on certain content.

[mlagally]

It will become clearer when we have a common definition of OOTBI.

[egekorkan]

I think there is a fundamental issue: W3C standards, unlike Zigbee, IEEE, IEC etc. do not have guarantees since W3C's business model does not involve certification.

If we have proper validation / conformance verification, the example you describe does not pass, i.e. a device cannot claim to be profile compliant.

The first part of this conditional sentence can never be true since we as W3C WoT WG cannot do conformance verification.

i.e. a device cannot claim to be profile compliant.

No one can stop a device or platform to create a TD that claims to be compliant to a profile. Similarly, a property affordance can be claimed to be a string but the device can deliver a number. Thus, Consumer applications should not simply break down in case of such simple inconsistencies

[mlagally]

This level of verification can be done by JSON schema validation.
As discussed on the call, there's no conformance regime or certification, but still a lot of baseline validations can be automatically performed.