Feedback on First Public Working Draft of Web of Things (WoT) Profile

Hi everyone,

I’m very pleased to see the idea of a core profile being worked on, thank
you for all the work that has gone into it. (Apologies that I have not been
able to be as hands-on as I’d hoped to be with the first draft, but I’ve
had a bit of a crazy year with being made redundant from my job, starting a
business and starting a family!)

I’d like to offer some feedback on the first public working draft of the
WoT Profile specification [1].

Firstly, my interest in the specification comes from:
* Using the Web of Things for smart building solutions at my new tech
startup Krellian [2], including digital signage and building automation
* The WebThings open source project [3], over which Krellian has recently
taken responsibility after spinning the project out [4] of Mozilla at its
new home of webthings.io. (I recently posted a blog post [5] about
Krellian’s future vision for WebThings, including better compliance with
the W3C Thing Description specification and a native mobile app which can
act as a general purpose Web of Things client, for which a core profile
would be extremely useful)
* My role as Chair of the Web Thing Protocol Community Group [6], whose
charter includes defining a common sub-protocol for the Web of Things built
on HTTP and WebSockets (plus potentially CoAP in the future)

My hopes for the WoT Profile specification are to promote ad-hoc
interoperability on the Web of Things, but also ideally to fulfil the Web
Thing Protocol Community Group’s requirements [7] for a common HTTP (and
CoAP) sub-protocol for the Web of Things, such that the community group can
focus on defining only a WebSocket sub-protocol.

I would also like to provide feedback on the Discovery specification, but
that will have to wait until the new year. (Apologies if I don’t reply to
comments for the next couple of weeks, I’m not ignoring you, just spending
some time with my family!)

*tl;dr: *Whilst I wholeheartedly agree with the broad goals for the
specification, in my opinion the current specification does not meet its
own stated goals because a) the proposed goals conflict with each other in
some areas and b) it is both too prescriptive and not prescriptive enough.
My core recommendation is therefore to split the core profile into a Core
Profile and Constrained Profile, each with more constraints on the
protocols that conforming implementations *must* support, more flexibility
in the protocols which conforming devices *can* support and a focus on two
separate sets of otherwise conflicting goals.

*Abstract*

Out of the box interoperability implies, that devices can be integrated
> into various application scenarios without deep level adaptations.
> Typically only minor configuration operations are necessary (such as
> entering a network key, or IP address) to use the device in a certain
> scenario. These actions can be done by anyone without specific training.
>

This definition of “out of the box interoperability” is a little vague. It
could be more concretely defined as “any WoT consumer and WoT producer
which implement the same profile are guaranteed to be able to communicate
with each other without modification”.

This document incudes a binding of the core data model to HTTP(S) and
> selected notification sub-protocols. The core data model can be bound to
> other protocols - it is expected that bindings to other protocols (e.g.
> MQTT, CoAP) will be defined in the near future.
>

I suggest that the level of extensibility implied by this paragraph
contradicts the definition of out of the box interoperability above,
because if a WoT consumer and WoT producer implement the same profile but
use different protocols, they can not in fact work together without
significant “adaptations”.

At best this would mean that the Core Profile must be split into the Core
HTTP Profile, Core MQTT Profile and Core CoAP Profile. Additional profiles
would need to be defined for every additional supported protocol. This goes
against the stated goal of the specification to “enable out of the box
interoperability among things and devices” and in fact “enables out of the
box interoperability among subsets of things and devices”.

Devices that constrain their use of the Thing Description to the WoT Core
> Profile can interoperate with each other out-of-the-box.
>

This statement is a better definition of interoperability, but for the
reasons described above it is demonstrably false.

*1.1 Deployment Scenarios*

I would additionally note that whilst it may not be possible for a brown
field device to conform to the Core Profile, it is possible to bridge such
a device to the Core Profile using a gateway or proxy.

*1.2 Why a Core Profile?*

The WoT Core Profile was defined with the following main goals:
> * guarantee interoperability among all implementations of the profile.
> * limit the implementation complexity for resource constrained devices.
> * ensure that a thing description is also useful for a human reader.
>

Looking at this set of goals, I would suggest that the first goal has not
yet been met by this draft of the specification and the second and third
goals conflict with each other in many areas.

I propose that both of these issues could be solved by separating out the
core profile into a Core Profile (which requires HTTP + JSON support) and
Constrained Profile (which requires CoAP + CBOR support). This would allow
for guaranteed interoperability among all implementations of each profile,
and could perhaps allow the latter profile to focus on the goal of
“limiting implementation complexity for resource constrained devices” while
the former profile focuses on “ensuring that a thing description is also
useful for a human reader”.

*1.3 Out-of-the-box interoperability*

Devices, which implement the Core Profile, are out-of-the-box interoperable
> with other Core Profile compliant devices.
>

Again, this statement is demonstrably false with the open ended flexibility
of protocols allowed by the current specification.

*4. Profiling Mechanism*

* If you constrain your TD to the Core Profile, all other devices that
> conform the Core Profile can interoperate with it out of the box.
> * If you have additional needs your device is free to implement other
> profiles or add-ons at your own choice, but other devices that only
> implement the Core Profile will most likely not be able to use these
> additions.”
>

With the current specification I actually don’t think either of these
statements are true. The former is not true because the Core Profile is not
prescriptive enough about protocol use (as described above) and the latter
is not true because the specification is too prescriptive in constraining
each operation of each interaction affordance to only one form. If a device
wants to conform to the core profile using one protocol but also support
other profiles using other protocols, that is not possible.

*5.1.1 General*

The prescription of mandatory fields and the limiting of the length of
strings seem to be working against each other in this set of constraints. I
suggest that if there was a separate Core Profile and Constrained Profile
the former could focus on human readability while the other focuses on
reducing resource requirements for constrained devices.

*5.1.2.1 Mandatory Fields*

I would argue that none of these fields need to be mandatory in order to
guarantee out-of-the box interoperability. An id is not necessary if the
URL of the Thing Description can be used as a fallback identifier for a
thing. title and description are not needed for interoperability, they are
useful for human readability but increase the resource requirements of
constrained devices. The security field may not be needed for devices which
are intentionally publicly available with no authentication. The rest of
the fields are just nice-to-have additional metadata but are neither
necessary for interoperability nor human readability and increase resource
requirements of constrained devices.

*5.1.2.2 Recommended Practice*

The recommendation to use empty strings for values that can not be
determined makes the mandatory fields largely pointless. It seems to be
based on the same rationale that led to the security member of the Thing
Description being mandatory, namely that by inconveniencing the developer
by forcing them to include members of a Thing Description that they don’t
actually need will somehow encourage them to adopt some best practice.

The recommendation for what to include in the support field is oddly
specific and probably unnecessary. Suggesting that it be an email address
or URL is probably sufficient.

*5.1.3.1 Data Schema Constraints*

I don’t fully agree with the rationale regarding relational databases
because there are various ways of storing nested data structures in
relational databases, but I don’t think the conclusion of only allowing
arrays and objects at the top level of a data schema is unreasonable. The
theoretically infinitely nested nature of data structures can be
challenging when trying to represent a web thing in a user interface. This
may be overly constraining for very complex devices though, and simply
result in a Thing Description which is less human readable, again
highlighting the conflict between different goals.

Forbidding the type value from being null may be problematic for use cases
where the value of a property may be represented by a binary format (e.g.
an image or video stream).

*5.1.4.1 Mandatory fields*

For reasons described above, I don’t necessarily agree that title,
description and type should be mandatory, though title and description
could be mandatory in a Core HTTP Profile for which human readability is
more important than resource constraints.

*5.1.4.2 Additional Constraints*

The Array of Form of each property MUST contain only a single endpoint for
> each operation readproperty , writeproperty , observeproperty ,
> unobserveproperty.
>

I strongly disagree with this constraint. It should be possible to have a
device which conforms to the Core Profile (e.g. using HTTP), but can also
be communicated with using other protocols (e.g. using CoAP or WebSockets).

uriVariables MUST NOT be used.
>

I don’t have a strong opinion on this, but it may be a problem if a
solution is ever provided for dealing with long-running actions (e.g. via
dynamic resources), which is something the current draft does not specify.

*5.1.4.3 Recommended Practice*

I suggest there needs to be some constraint on the values of the unit
member of a property. Mozilla’s Web Thing API specification constrains this
to (the long form of) SI units [8]. This has worked well for the set of
capability schemas [9] that have been defined for WebThings so far, but may
not be sufficiently formally defined as an ontology for other implementers.

*5.1.8 Links*

A couple of top level links the WebThings project has found useful are:

1. An alternate link relation which points to a resource of type text/html
which provides an HTML user interface for users to interact with the device
2. An alternate link relation which points to a resource with a WebSocket
URI, which acts as a WebSocket endpoint for the whole device (using a
defined WebSocket sub-protocol)

Both of these could be useful for a Core profile to support, the HTML user
interface in particular.

*5.2 Protocol Binding*

I won’t comment too much on this section because the Editor’s Note
highlights that this section will undergo significant changes in the next
draft and it’s clearly currently missing a lot of features.

I’m very pleased to see a default protocol binding being part of the Core
Profile. My main feedback would be that currently it overlaps a great deal
with the “Protocol Binding based on HTTP” section of the Thing Description
specification [10], and currently adds very little to that existing text. I
would suggest that this protocol binding specification should either be
defined in the Thing Description specification or the Profile
specification, but not both. It may be appropriate to remove it from
version 1.1 of the Thing Description specification if the Profile
specification is going to define a default protocol binding going forward.

I’m pleased to see the beginning of defining error conditions in the
protocol binding. It is notable that the protocol binding still does not
have a proposed solution for event subscriptions or action queues, but I
note that these are highlighted as open issues in section 6.

*Conclusion*

In conclusion, whilst I fully support the overall goals for the
specification, in my opinion the current specification does not meet its
own stated goals because:
 * The proposed goals conflict with each other in some areas
 * It is both too prescriptive and not prescriptive enough to enable a rich
Web of Things ecosystem which benefits from ad-hoc interoperability between
WoT producers and WoT consumers

Therefore, my main recommendation is to split the core profile into a Core
Profile and Constrained Profile, each with:
* More constraints on the protocols that conforming implementations *must*
support
* Fewer constraints on the protocols which conforming devices *can* support
* A focus on two separate sets of otherwise conflicting goals


I have filed GitHub issues for my three most important proposed changes:
* https://github.com/w3c/wot-profile/issues/59
* https://github.com/w3c/wot-profile/issues/60
* https://github.com/w3c/wot-profile/issues/10

Best regards

Ben

1. https://www.w3.org/TR/2020/WD-wot-profile-20201124/
2. https://krellian.com/
3. https://webthings.io/
4. https://hacks.mozilla.org/2020/12/flying-the-nest-webthings-gateway-1-0/
5.
https://medium.com/krellian/introducing-the-webthings-iot-platform-9fe4f97c0c72
6. https://www.w3.org/community/web-thing-protocol/
7. https://w3c.github.io/web-thing-protocol/requirements/
8. https://iot.mozilla.org/wot/#property-object
9. https://iot.mozilla.org/schemas/
10. https://w3c.github.io/wot-thing-description/#http-binding-assertions

-- 
Ben Francis
Founder
Krellian Ltd. <https://krellian.com>