Refine Goals and Scope

[mmccool]

There has been a lot of discussion recently about conflicting requirements which seem to arise in turn from differences in assumptions about the purpose and goals of profiles. I would like to use this issue to discuss the purpose and goals of profiles, and ideally help the discussion reach a consensus that will allow us to make concrete progress.

[mmccool]

Some observations:

1. Any features or constraints that apply to all use cases should be in a core specification (e.g. the Thing Description recommendation itself), not in a profile.
2. By definition a profile should apply to a specific use case or context: a profile is "for" that context.
3. Even if we have multiple profiles in the future that share some common features, we don't have to extract those common features until we have examples of multiple profiles to worry about, at which point we can refactor.

Therefore I propose we focus on one particular context, and this context is not/does not need to be universal. As the issue of profiles was raised in the context of WebThings, and this is directly relevant to an actual product being developed, I propose we focus on that for now. We may also want to include ECHONET in this discussion since their architecture seems similar. This means we should worry only about supporting hubs that need to consume TDs from backends or from endpoints and then expose new TDs.

For concreteness, I propose calling this the "hub" or "home hub" profile. As I note above, we can defer factoring out common elements until we have examples of profiles for other contexts.

To narrow the scope in this specific context further, I also propose the following:

1. Assume the hub has a relatively large memory capacity and capability for consuming Thing Descriptions.
2. Assume endpoints will not, themselves, consume Thing Descriptions.
3. Limit protocols to HTTP, CoAP, and MQTT, since these are the protocols of interest in this context.

Assumptions 1 and 2 mean that if TDs are limited in size and complexity at all, those limits can be very large. We do not have to mandate a limit for small devices producing TDs because implementations will be self-limiting (they will do what they can do, and won't do what they can't). What matters for interoperability is the limitation on consumption.

There may be other such scope-limiting assumptions or statements we can make in this context that may be helpful. We should probably make a list of the functions that a hub needs to support (e.g. discovery, protocol translation, security, etc). and make sure that those can be accomplished in an interoperable way, but resist adding any additional constraints that do not satisfy those objectives.

These are just some thoughts to open the discussion.

Note: I have a theoretical example to support peer-to-peer pairing that violates assumption 2 above, however the "hub" profile can simply mandate that any pairing or orchestration is done through a hub, which greatly simplifies things. This is a profile though, and of course systems can be built that don't satisfy the profile, and that is fine. What matters is that a potential user knows that devices that both satisfy a given profile will interoperate.

[egekorkan]

I agree with the need for relaxing some requirements that also contradict with each other. However, I don't think that the point 3 is a good idea:

• We have very little experience with MQTT and CoAP in plugfests. Nearly everyone just uses HTTP.
• Consuming a TD that might have HTTP, CoAP or MQTT breaks out of the box interoperability since a Consumer MUST implement all the three.

[benfrancis]

@mmccool wrote:

1. Any features or constraints that apply to all use cases should be in a core specification (e.g. the Thing Description recommendation itself), not in a profile.

Strongly agree. I think most of the constraints being proposed for the data model should either be in the Thing Description specification, or not exist at all.

2. By definition a profile should apply to a specific use case or context: a profile is "for" that context.

I think I agree, but I'd like to better understand your definition of "use case" and "context". I strongly believe that profiles should not be application domain specific for example.

3. Even if we have multiple profiles in the future that share some common features, we don't have to extract those common features until we have examples of multiple profiles to worry about, at which point we can refactor.

Agree.

As the issue of profiles was raised in the context of WebThings, and this is directly relevant to an actual product being developed, I propose we focus on that for now. We may also want to include ECHONET in this discussion since their architecture seems similar.

I really appreciate the recognition for the concrete and immediate need that WebThings has here. I agree the ECHONET implementation presented on Monday has many similarities.

This means we should worry only about supporting hubs that need to consume TDs from backends or from endpoints and then expose new TDs.

For concreteness, I propose calling this the "hub" or "home hub" profile. As I note above, we can defer factoring out common elements until we have examples of profiles for other contexts.

To narrow the scope in this specific context further, I also propose the following:

1. Assume the hub has a relatively large memory capacity and capability for consuming Thing Descriptions.

2. Assume endpoints will not, themselves, consume Thing Descriptions.

3. Limit protocols to HTTP, CoAP, and MQTT, since these are the protocols of interest in this context.

I think there may be some misconceptions about the needs WebThings has here.

WebThings Gateway (WoT consumer & producer) is only one component of the WebThings platform, which also includes the WebThings Framework (currently 16 WoT producer/server implementations in different programming languages intended for building native WoT devices) and in future the WebThings Cloud (WoT consumer & producer as a cloud service) and the WebThings App (WoT consumer as a mobile app).

The common defining factor of all of these implementations is that they use a consistent (but currently non-standard) HTTP+JSON API and WebSocket sub-protocol and therefore support ad-hoc interoperability.

The Web of Things as it exists today does not allow ad-hoc interoperability because it is entirely protocol and serialisation agnostic and imposes very few constraints on what WoT producers can do. This open endedness makes it impossible to implement a WoT consumer which can talk to all WoT producers.

The goal that I originally expressed which I believe ultimately led to the current work on WoT Profile was for the definition of a concretely defined sub-set of the Web of Things for greenfield implementations which could guarantee ad-hoc interoperability between WoT producers and WoT consumers which are conformant with that profile.

In practice that means a scope which includes:
1. Mandating a single protocol (HTTP)
2. Mandating a single serialisation format (JSON)
3. Defining more concretely how those technologies are used to communicate with a WoT device

That might mean being more prescriptive in defining the request and response payloads used, including success and error conditions, approximating the style of the Web Thing REST API (which it seems is also quite similar to the ECHONET implementation).

I imagine this to be an extension of (and probably replacement for) the 8.3.1 Protocol Binding based on HTTP section of the Thing Description specification.

If such a profile existed then Mozilla's Web Thing API specification could finally be retired and there would also be no need for the "HTTP sub-protocol" proposed in the charter of the Web Thing Protocol Community Group.

What it does not mean is:

1. Profiles for specific application domains (see single profile or smart home + industrial profile #12)
2. Additional constraints on the WoT data model like arbitrary maximum sizes of resources (see Reduce or remove the constraints in section 7.2 Baseline Information Model #10)
3. Additional mandatory human-readable metadata (see Reduce or remove the constraints in section 7.2 Baseline Information Model #10)
4. A protocol agnostic abstraction which must also be implementable in other protocols like CoAP and MQTT (see Core/default profile should mandate HTTP support as a minimum requirement #24)
5. A profile which prevents a conformant device from also implementing other protocols and serialisation formats in addition to the mandatory ones (see Allow multiple forms for interaction affordances in Core Profile #60)

Since work started on profiles and much of the effort has been focused on defining requirements for constrained devices, I proposed that in addition to this "core" (possibly a bad name) profile which focuses on ad-hoc interoperability using HTTP+JSON, there may be a need for an additional "constrained" profile (mandating CoAP+CBOR) which focuses on the often conflicting needs of constrained devices (see #59).

@egekorkan wrote:

Consuming a TD that might have HTTP, CoAP or MQTT breaks out of the box interoperability since a Consumer MUST implement all the three.

Strongly agree.

[benfrancis]

It might also be useful to remind ourselves what the charter says is the goal of the interoperability profiles activity:

The WoT Thing Description (TD) provides a general framework for describing the interface to a Thing independent of the network protocol, data encoding, or security mechanism used. TDs are defined to be extensible, since IoT protocols, data encodings, and security mechanisms are constantly evolving. However, this openness works against interoperability since it is not clear in advance what technologies must be supported by a given implementation of a TD Consumer, and a TD Consumer can only work with Things using the technologies it includes an implementation for.

In many contexts, "plug and play" interoperability is desirable. For example, in the Smart Home context, the consumer needs to know in advance of purchase whether a set of devices will work with each other. Such predictability is also essential in many other contexts, including industrial use cases. Unfortunately the set of technologies that must be supported depend on context: protocols, data types, and security mechanisms essential in an industrial context may be an unnecessary burden for a home gateway to have to implement.

To resolve this problem this work item will define "profiles" which define subsets of TDs supporting only specific technologies. This work item will include the following:

1. Definition of a mechanism to identify the profile or profiles that a given TD is conformant to.
2. Definition of specific profiles.

[sebastiankb]

I think the discussion here goes in the right direction and I’m agree with @mmccool that we should concentrate on examples such as WebThing and ECHONET as well as from our PlugFest.

We are currently in the phase to create a first profile for WoT which should also be used as good example for other upcoming profile in the future. My recommendation is to focus on a small set of specific technologies for each profile, and the most obvious is to start with HTTP and JSON, as @benfrancis also suggests.

My recommendation is that the Profil Specification gives same basic introduction about the Profile concept for Web of Things and provides some basic assertions that should apply to all profiles that will exists. However, those assertions should be protocol and serialization independent and should be more generic such as the hierarchy level of the used data schema.

My proposal is that the concrete applied technology for a profile should be defined in the binding documents. Please aware that the Binding TF currently working on to create separate documents for each protocol such as for HTTP. This means that the upcoming document "WoT Binding based on HTTP" (please note that the title of the document is not yet decided) will copy and replace the HTTP content from the TD specification and binding. In this new document, I would suggest introducing a chapter that takes care of an instantiated WoT profile with HTTP and JSON and the expected payload and protocol behaviour. Such a profile chapter you will also find in the future in “WoT Binding based on CoAP” which suggest a default profile based on CoAP and CBOR etc.

[benfrancis]

@sebastiankb wrote:

My recommendation is that the Profil Specification gives same basic introduction about the Profile concept for Web of Things and provides some basic assertions that should apply to all profiles that will exists. However, those assertions should be protocol and serialization independent and should be more generic such as the hierarchy level of the used data schema.

My proposal is that the concrete applied technology for a profile should be defined in the binding documents. Please aware that the Binding TF currently working on to create separate documents for each protocol such as for HTTP. This means that the upcoming document "WoT Binding based on HTTP" (please note that the title of the document is not yet decided) will copy and replace the HTTP content from the TD specification and binding. In this new document, I would suggest introducing a chapter that takes care of an instantiated WoT profile with HTTP and JSON and the expected payload and protocol behaviour. Such a profile chapter you will also find in the future in “WoT Binding based on CoAP” which suggest a default profile based on CoAP and CBOR etc.

The "WoT Binding based on HTTP" document you are describing sounds like what I mean by a "core profile". I don't really mind whether it's called a profile, a protocol binding or a sub-protocol. I also wouldn't mind if there was a very short "WoT Profile" specification defining the profile mechanism and then separate documents for each profile/binding. However:

1. I don't believe defining an abstract core profile that can be implemented using any protocol and then a separate concrete instantiation of that as "protocol bindings" for HTTP, CoAP and MQTT will work. There are just too many differences between how the protocols work (e.g. request/response vs. publish/subscribe, poll vs. push) and I think it's likely that a device suited to HTTP is likely to have a separate set of requirements to a device suited to CoAP. A simpler and more practical approach would be to have a core profile which focuses on the majority of WoT implementations which exist today using HTTP+JSON and then a separate constrained profile which focuses on the needs of constrained devices and uses CoAP+CBOR.
2. I'm also not sure what an abstract profile would actually contain if it doesn't define a concrete way to communicate with a device. This kind of abstract thinking is what led to the current fixation on tweaking the data model rather than actually defining how to enable plug and play interoperability between producers and consumers.
3. A "Web of Things (WoT) Interoperability Profiles" specification is in the current charter, but a "WoT Binding based on HTTP" specification is not.

If it would be helpful, I could draft an alternative outline for a WoT Profile specification to demonstrate what I mean.

[sebastiankb]

I don't believe defining an abstract core profile that can be implemented using any protocol and then a separate concrete instantiation of that as "protocol bindings" for HTTP, CoAP and MQTT will work. There are just too many differences between how the protocols work (e.g. request/response vs. publish/subscribe, poll vs. push) and I think it's likely that a device suited to HTTP is likely to have a separate set of requirements to a device suited to CoAP. A simpler and more practical approach would be to have a core profile which focuses on the majority of WoT implementations which exist today using HTTP+JSON and then a separate constrained profile which focuses on the needs of constrained devices and uses CoAP+CBOR.

That is the reason why I wanted to make assertions that are independent of the technology. But you are right, it will be very difficult to find common claims that might not have a negative impact on a concrete profile with specific protocols and so on.

I'm also not sure what an abstract profile would actually contain if it doesn't define a concrete way to communicate with a device. This kind of abstract thinking is what led to the current fixation on tweaking the data model rather than actually defining how to enable plug and play interoperability between producers and consumers.

What I have in mind is a pattern that you may know from RFC 3986. This only gives a generic syntax for designing URIs (~basic introduction about the WoT Profile concept). Concrete implementations are given by other RFCs such as with RFC 4248 for telnet (~WoT HTTP-JSON Profile).

A "Web of Things (WoT) Interoperability Profiles" specification is in the current charter, but a "WoT Binding based on HTTP" specification is not.

Please be aware what I called "WoT Binding based on HTTP" will be a side / sub document of the existing WoT Binding document. The intention is that we no longer have different places for information about the use of certain protocols like HTTP. As you know, there are some places in the TD specification and different section in the binding document. I think for the reader it is better to have a single place that takes care of a specific binding.

If it would be helpful, I could draft an alternative outline for a WoT Profile specification to demonstrate what I mean.

Why not? This would clarify the deltas better and perhaps simplify the discussion. @mlagally @mmccool what do you think?

[benfrancis]

What I have in mind is a pattern that you may know from RFC 3986. This only gives a generic syntax for designing URIs (~basic introduction about the WoT Profile concept). Concrete implementations are given by other RFCs such as with RFC 4248 for telnet (~WoT HTTP-JSON Profile).

OK, what do you imagine the "generic syntax" for profiles would look like?

My preference would be that the generic syntax for profiles is simply a mechanism for denoting that a given thing description conforms to a given profile using a URI (see #2). Then everything else (the protocol and serialisation format and how they are used) is defined in the individual profile specification.

[sebastiankb]

My preference would be that the generic syntax for profiles is simply a mechanism for denoting that a given thing description conforms to a given profile using a URI (see #2). Then everything else (the protocol and serialisation format and how they are used) is defined in the individual profile specification.

Exactly, this is what I would also support. A generic document that explains the concept of WoT profiles and provides information what needs to be fulfilled as minimum when a new specific WoT profile is created. This may include:

• Unique profile identification, such as by an URI
• There should be answers to the specific use of the protocol and its behaviour
• There should be answers to the payload structure
• Which discovery option should be possible
• Security mechanism

A concrete profile like a "WoT HTTP-JSON Profile" have to follow this topic and should provide this information.

Btw: Profile will a topic in today's vF2F meeting. I hope, all of you can join to find an agreement asap.

[benfrancis]

Thank you for the productive conversation about profiles in the vF2F today.

I have provided suggestions above about what I think should be the goals and scope of the first version of the WoT Profile specification.

With regards to the content and structure of the specification, I like @sebastiankb's suggestion above regarding what should be included.

I have drafted a proposed tweaked outline of the WoT profile specification based on this list. Feedback welcome.

1. Introduction
2. Profiling Mechanism
3. Conformance
4. Foo Profile
   1. Introduction
   2. Identifier
   3. Protocol Binding
      1. Properties
         1. readproperty
         2. writeproperty
         3. readallproperties
         4. writeallproperties
         5. readmultipleproperties
         6. writemultipleproperties
         7. (observeproperty)
         8. (unobserveproperty)
         9. (observeallproperties)
         10. (unobserveallproperties)
      2. Actions
         1. invokeaction
         2. queryaction
         3. updateaction
         4. cancelaction
      3. Events
         1. readpastevents
         2. readallpastevents
         3. (subscribeevent)
         4. (unsubscribeevent)
   4. Links
   5. Security
   6. Discovery

Note: There is no "core data model" section. My thinking being that anything which adds new constraints or resolves ambiguities in the data model, and should apply to all WoT producers, should be in the Thing Description specification.

Introduction

A brief introduction explaining the concept of profiles and their goal in providing out-of-the-box interoperability for greenfield implementations, such that any WoT consumer and WoT producer which implement the same profile are guaranteed to be able to communicate with each other without modification.

I suggest narrowing the scope by focusing on this interoperability goal and removing any references to "limiting the implementation complexity for resource constrained devices" or "ensuring that a thing description is also useful for a human reader."

It might also be useful to explain that one profile is defined in this specification, but others (e.g. a constrained profile) may be defined in the future, and that it should be possible for devices to be compliant with multiple profiles at the same time if desired.

Profiling Mechanism

A brief description of the mechanism for a WoT producer to denote in its Thing Description that it conforms to a given profile. E.g. a new "profile" member for Thing Descriptions which provides the URI of a profile.

{
    "@context": "https://www.w3.org/2019/wot/td/v1",
    "profile": "https://www.w3.org/2021/wot/profile/foo",
    ...
    }
}

(or alternatively a special value for @context).

Conformance

What needs to be true for a given WoT producer or WoT consumer to be conformant with a given profile (i.e. that it conforms to all the normative requirements in the specification).

Foo Profile

Our first profile. I've called this "Foo Profile" because I think we have more agreement on what it should contain than what it should be called, so it might be better to name it once we've written it. The specification of the profile may be contained inside the main WoT Profile specification, or be a separate document.

Introduction

Explains that this profile mandates the use of HTTP and JSON and certain security schemes and discovery mechanisms.

The introduction could also provide two example Thing Descriptions which demonstrate how the profile is produced and consumed:

1. A simple TD exposed by a WoT producer which refers to the profile by its URI and includes a single form per interaction affordance which only specifies a href member
2. A normalised/processed version of the Thing Description which shows how the first TD would be represented internally by a WoT consumer, with all the defaults applied so there are multiple forms per interaction affordance including all the HTTP verbs, headers, expected response codes etc.

Identifier

This section would simply provide the identifier URI for the profile, e.g. https://www.w3.org/2021/wot/profile/foo and an example of how it should be used.

Protocol Binding

This section would describe how to carry out each of the "operations" defined in the Thing Description specification using HTTP+JSON, including any that are added in WoT Thing Description 1.1. I imagine this to be an extension of and replacement for the 8.3.1 Protocol Binding based on HTTP section of the WoT Thing Description specification.

If we can agree on a default mechanism for subscribing to events and observing properties then those operations can be included, otherwise they may be excluded from this HTTP-based profile (readpastevents may provide a fallback for events using a simple GET request).

Links

Types of link relations which conformant WoT producers MAY use, but conformant WoT consumers MUST support. E.g. an alternate link relation pointing to a text/html user interface for the device.

Security

Security schemes which conformant WoT producers MAY use, but conformant WoT consumers MUST support.

Discovery

Discovery mechanisms which conformant WoT producers MAY use, but conformant WoT consumers MUST support. E.g. DNS-SD/mDNS broadcasts.

[relu91]

In general, I like the structure proposed. Few minor comments.

Profiling Mechanism

A brief description of the mechanism for a WoT producer to denote in its Thing Description that it conforms to a given profile. E.g. a new "profile" member for Thing Descriptions which provides the URI of a profile.

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "profile": "https://www.w3.org/2021/wot/profile/foo",
  ...

}

(or alternatively a special value for @context).

+1 for a dedicated field in the TD schema. I'd not use @context unless we predict that profiles would introduce specific semantic tags or keywords. Since, as I understood, profiling will only regulate what is already defined in other vocabularies I don't think it's the case.

Protocol Binding

This section would describe how to carry out each of the "operations" defined in the Thing Description specification using HTTP+JSON, including any that are added in WoT Thing Description 1.1. I imagine this to be an extension of and replacement for the 8.3.1 Protocol Binding based on HTTP section of the WoT Thing Description specification.

In the recent TD calls, we discussed a possible refactoring of the current spec for protocol bindings. Basically, we agreed to evaluate dedicated documents for each protocol biding explaining default values and examples. In light of this proposal, we could re-evaluate again the decision and think if it still makes sense to have those protocol binding documents or move their content to the profiling spec. @sebastiankb what do you think?

[egekorkan]

I would say that the protocol bindings should not be mixed with the profiles since they tell how a protocol can/should be used in WoT whereas a profile will constrain that protocol to be used in a certain way.

[mlagally]

Hi @benfrancis,
many thanks for your elaborate proposal of the structure.
I agree with the basic structure of the protocol binding section, can you please elaborate what sections in brackets mean?
Are they optional? tbd?

I'm still convinced that we need the data model section to complete the profile work.

The TD specification has a completely different goal than the profile:

• it is a "catch all" for all possible variations of brown field and green field devices and is by design as flexible and open as possible, i.e. there are many optionalities and variations by design. These are not "flaws" that need to be fixed, but "design goals"
• The TD spec separates the data model and the protocol binding and external representation for a good reasons - a common data model can be made available via multiple protocol bindings, which is one of the use cases we have to satisfy.
• There are several aspects, e.g. action and event semantics that are completely independent of the protocol, also constraints on interaction affordances affect the model and not the protocol binding.

Your proposal is very valuable and brings the discussion forward in the right direction.

To make progress, I suggest we add your proposed chapter structure of the protocol chapter to the corresponding chapter of the document and discuss specific protocol binding aspects in our next Architecture calls.
After we have defined protocol binding mapping and constraints we have gained more experience on which constraints should be generalized for a common data model.

[benfrancis]

@relu91 wrote:

In the recent TD calls, we discussed a possible refactoring of the current spec for protocol bindings. Basically, we agreed to evaluate dedicated documents for each protocol biding explaining default values and examples. In light of this proposal, we could re-evaluate again the decision and think if it still makes sense to have those protocol binding documents or move their content to the profiling spec.

Thanks for bringing up this point. From other comments above there's clearly some overlap in the understanding of what belongs in a protocol binding and what belongs in a profile (I actually think there's also some overlap with Thing Models and capability schemas/semantic annotations too, since they can both be used to describe standard composable interfaces). This is all adding up to a complicated architecture of overlapping concepts.

In my ideal world there would only be two WoT specifications:

1. Web Thing Description - Specifies how to describe the capabilities of devices
2. Web Thing Protocol - Specifies how to communicate with devices over the web

In reality we (so far) have seven different specifications (Architecture, Thing Description, Binding Templates, Scripting API, Discovery, Profile, Security and Privacy Guidelines), plus various accompanying documents, defining different layers of abstraction which sometimes overlap, and it's not always clear how they fit together.

I agree that we should either have an HTTP Profile document or an HTTP Protocol Binding document, but not both, because they are essentially solving the same problem (or at least they should be). I guess the question is whether everything in the Foo Profile outline above (including links, security and discovery) belongs inside a protocol binding. If it does then we should consider only having the HTTP Protocol Binding document and a very simple Profile document (or even just a section in the TD spec) which just specifies how to refer to a protocol binding from a thing description. If it doesn't then maybe we should consider having an HTTP Profile document which includes the HTTP protocol binding, and no separate HTTP Protocol Binding document.

@egekorkan wrote:

I would say that the protocol bindings should not be mixed with the profiles since they tell how a protocol can/should be used in WoT whereas a profile will constrain that protocol to be used in a certain way.

This is a bit vague, they sound like the same thing to me. Can you provide concrete examples of things that are needed to achieve out-of-the-box interoperability which belong in a profile but not in a protocol binding?

@mlagally wrote:

can you please elaborate what sections in brackets mean?
Are they optional? tbd?

These are operations that I mentioned in the Protocol Binding section which may be in the profile if we can agree a default mechanism for observing properties and subscribing to events using HTTP, but may be omitted if not.

I'm still convinced that we need the data model section to complete the profile work.

I understand the points you're making, but I don't agree that any of the additional constraints being proposed in the data model section are actually necessary in order to facilitate out-of-the-box interoperability between WoT producers and WoT consumers.

Bearing in mind the discussion we had on a more focused goal of out-of-the-box interoperability (as opposed to limiting complexity for resource constrained devices and increasing human readability) and the context we have discussed (where it can be safely assumed that a WoT consumer is less constrained than the WoT producers it consumes), can you provide any examples of aspects of the data model which would prevent interoperability if they weren't present?

Does anyone else think that additional data model constraints (outside of the Thing Description specification) are necessary in order to facilitate out-of-the-box interoperability within the scope described above? The only example I can think of (which I don't think is actually covered in the current draft), is the issue of semantic interoperability (raised by @relu91 in the call yesterday), e.g. requiring consumers to support particular ontologies (e.g. units) and capability schemas. That could further enhance interoperability by allowing for richer interactions between producers and consumers, but I would characterise that as an enhancement rather than a blocking feature.

To make progress, I suggest we add your proposed chapter structure of the protocol chapter to the corresponding chapter of the document and discuss specific protocol binding aspects in our next Architecture calls.

I would be happy to contribute to the WoT Profile specification in order to achieve the goals set out above, but I think more drastic changes than this are probably needed in order to re-focus on the set of requirements discussed in this issue. Perhaps I misread the room, but there seemed to be some consensus about that in the meeting yesterday.

[benfrancis]

@mlagally I realised you provided some examples so let me address them directly.

* There are several aspects, e.g. action and event semantics that are completely independent of the protocol, also constraints on interaction affordances affect the model and not the protocol binding.

Action affordances:

• title - Not required for interoperability, only human readability.
• input - Constraining inputs to simple types may help constrained devices, but is not necessary for interoperability. Some actions may not have an input at all as the name of the action alone may be sufficient (e.g. "reboot").
• output - Constraining outputs to simple types may help constrained devices, but is not necessary for interoperability. Some actions may not have an output at all, in fact WebThings doesn't even support this feature yet because we haven't come across a use case.
• forms - Constraining forms to only one endpoint may actually work against interoperability by preventing devices from supporting multiple protocols or a legacy API in addition to a standard WoT API.
• format - This constraint probably belongs in the Thing Description specification.
• oneOf - I don't understand this one.
• uriVariables - Why can't uriVariables be used?

Event affordances:

• title - Not required for interoperability, only human readability.
• description - Not required for interoperability, only human readability.
• data - Why can't events contain an object as a payload, or no payload at all?
• forms - Constraining forms to only one endpoint may actually work against interoperability (see above).
• uriVariables - Why can't uriVariables be used?

General:

• title and description are not required for interoperability, only human readability
• Limiting the length of values is unlikely to make any tangible improvement to interoperability IMO. If it really is a problem then this should probably be in the Thing Description specification.
• Array of string/DataSchema - This can be checked for in one line of code in the implementation, it really doesn't harm interoperability
• enum - If this is a problem, this constraint probably belongs in the Thing Description

Hopefully this helps explain my reservations in a more concrete way?

[egekorkan]

@benfrancis wrote:

This is a bit vague, they sound like the same thing to me. Can you provide concrete examples of things that are needed to achieve out-of-the-box interoperability which belong in a profile but not in a protocol binding?

So a protocol binding has actually two parts:

1. Explaining the vocabulary terms that a protocol has, i.e. htv:methodName has values of "GET", "PUT", "POST", "DELETE", "PATCH".
2. Default terms that map a WoT operation to a set of vocabulary terms of the protocol, i.e. readproperty maps to "htv:methodName": "GET".

In a way, the default terms already give an idea of a profile, it would be the WoT Default HTTP Profile in this case, which has nothing but a constraint on how the protocol is used. This can be in the profile specifications but does not have to be since this mechanism can be used by different profiles as well. (This last half-sentence might need further discussion).

The first part allows one to map an action invocation to a DELETE request which is totally fine by the TD specification since there could be someone who developed a Thing like that.

To sum up, the second part mentioned above can be moved to a profile specification whereas the first part must stay in the respective binding document.

[benfrancis]

@egekorkan I think we are in agreement, just getting caught up on terminology.

Explaining the vocabulary terms that a protocol has, i.e. htv:methodName has values of "GET", "PUT", "POST", "DELETE", "PATCH".

As I understand it this is a "protocol binding template", not a "protocol binding", and would remain in the WoT Protocol Binding Templates specification.

Default terms that map a WoT operation to a set of vocabulary terms of the protocol, i.e. readproperty maps to "htv:methodName": "GET".

This part is the protocol binding, which is currently specified normatively in the WoT Thing Description specification (but only with very minimal defaults) and non-normatively (as more complete examples) in the WoT Binding Templates specification. I am suggesting both these sections should be replaced by a single HTTP Profile or HTTP Protocol Binding specification (depending on whether the protocol binding can cover everything needed by the profile).

[sebastiankb]

I also like the structure proposal above. @benfrancis It would be great if you could provide a PR. There we can better comment on your proposal.

@relu91

In the recent TD calls, we discussed a possible refactoring of the current spec for protocol bindings. Basically, we agreed to evaluate dedicated documents for each protocol biding explaining default values and examples. In light of this proposal, we could re-evaluate again the decision and think if it still makes sense to have those protocol binding documents or move their content to the profiling spec. @sebastiankb what do you think?

Well, for me we still need two different documents. The Foo Profile such as a " WoT HTTP-JSON" Profile gives some concrete details about the protocol usage, its expected behavoir (e.g., query states of actions) with payload structure expectation as well as answers about security and discovery topics. The HTTP binding specification, as example, gives some basic details how the annotation in forms have to be done to describe HTTP operation of a specific interactions (e.g., providing HTTP header metadata, methods etc.). This is relevant, e.g., when you want to define TDs of a legacy HTTP interfaces of a Thing which do not fulfill any Profile approach.

Above I had the idea to integrate a profile implementation such as "HTTP-JSON" as specialization with in the HTTP Binding document. Then we would have a single place which is only about "HTTP" with a specialization "Profile HTTP-JSON" chapter. However, my impression is that it is more desirable to have a self-contained profile document. In this case, I would keep the separation as motivated above.

[benfrancis]

@sebastiankb wrote:

The HTTP binding specification, as example, gives some basic details how the annotation in forms have to be done to describe HTTP operation of a specific interactions (e.g., providing HTTP header metadata, methods etc.).

I think this is "protocol binding templates" not "protocol bindings", which would stay in the generic Protocol Binding Templates specification.

So the question is just whether the default HTTP protocol binding should be:

1. Part of a Foo Profile chapter in the WoT Profile specification
2. Part of a separate Foo Profile document which defines the Foo Profile
3. A separate HTTP Protocol Binding document which defines the Foo Profile

See my question from above:

I guess the question is whether everything in the Foo Profile outline above (including links, security and discovery) belongs inside a protocol binding. If it does then we should consider only having the HTTP Protocol Binding document and a very simple Profile document (or even just a section in the TD spec) which just specifies how to refer to a protocol binding from a thing description. If it doesn't then maybe we should consider having an HTTP Profile document which includes the HTTP protocol binding, and no separate HTTP Protocol Binding document.

[sebastiankb]

I'm not 100% sure if I understood the question. The question is also what is meant by "default". Currently we have only a kind of basic "default" assumption about the op and htv:methodName in forms as defined here. This must be assumed by a TD processor if this information is not explicitly specified in the TD. If this is not intended (e.g. the Write property operation is to be applied with the POST method), the WoT producer must provide the htv:methodName in its TD explicitly for this type of interaction.

A profile foo should follow a specific protocol and and its specific assumptions (e.g., writeproperty with POST) which can be seen as a "default" in that profile context. Is this what you mean?

[benfrancis]

A profile foo should follow a specific protocol and and its specific assumptions (e.g., writeproperty with POST) which can be seen as a "default" in that profile context. Is this what you mean?

Yes, I see a common HTTP-based profile as extending (and replacing) the set of defaults currently defined for HTTP in the Thing Description specification.

I think we all agree that there should be a document that defines a common approach for communicating with devices over HTTP, which extends the current set of defaults (GET for read, PUT for write, POST for invoke) in the Thing Description specification. What doesn't seem to be clear is in which document that specification should be provided (e.g. the WoT profile document, a new [Foo] Profile document or a new HTTP Protocol Binding document which accompanies the current WoT Binding Templates document).

[benfrancis]

@mlagally Apologies I haven't yet found the time to send PRs to further discuss my proposed changes to the structure of the WoT Profile specification. I have a list of 5+ PRs I plan to send for different specifications following the two weeks of discussions in the vF2F and hope to pick that up late next week after some annual leave.

[mlagally]

@benfrancis many thanks for the heads up.
It would be better to have a few small and simple MRs that we can debate individually to make sure we can integrate them easily into the document.
Let's take several small steps to make sure we make progress.

[mlagally]

Arch call on 15.4.:

We agreed to adopt the structure of the protocol binding chapter outline in chapter 5.2 of the current document, specifically:

3. Protocol Binding
    1. Properties
        1. readproperty
        2. writeproperty
        3. readallproperties
        4. writeallproperties
        5. readmultipleproperties
        6. writemultipleproperties
        7. (observeproperty)
        8. (unobserveproperty)
        9. (observeallproperties)
        10. (unobserveallproperties)
    2. Actions
        1. invokeaction
        2. queryaction
        3. updateaction
        4. cancelaction
    3. Events
        1. readpastevents
        2. readallpastevents
        3. (subscribeevent)
        4. (unsubscribeevent)

We have to clarify the meaning of the round brackets (optional?) and also decide on whether the minimum profile has to include an event mechanism.
Observing properties also would not be required.
Reading events would already serve the purpose of a minimum event mechanism without a heavyweight burden on the protocol (no need of keeping a socket open).

[egekorkan]

If this is already decided to be in the spec, I am a bit puzzled since action-related operations other than invokeaction are not agreed upon anywhere as far as I know. A similar case applies to readpastevents and readallpastevents. Additionally, readmultipleproperties is not properly defined in the TD spec, is profile spec going to define a specific way on how to do it?

[benfrancis]

@egekorkan I have submitted a pull request (#77) with this new structure. So far it just includes the first set of operations for which we already have broad agreement:

• readproperty
• writeproperty
• readallproperties
• writeallproperties
• readmultipleproperties
• writemultipleproperties
• invokeaction

and then notes suggesting other operations which may also be included upon further discussion:

• observeproperty
• unobserveproperty
• observeallproperties
• unobserveallproperties
• queryaction
• updateaction
• cancelaction
• subscribeevent
• unsubscribeevent
• subscribeallevents
• unsubscribeallevents
• readpastevents
• readallpastevents

[benfrancis]

It was pointed out by @relu91 in #125 that it's not clear from the comments in this thread what the conclusion of this discussion was and that it would be to get that in writing and resolve this issue. I agree.

The current text of the specification says...

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.

My understanding of the general consensus on this and other recent threads on GitHub, and on the WoT Architecture calls, is that the latter two goals conflict with each other and therefore the scope should be reduced to only the first goal of interoperability.

Therefore, as originally proposed by @mmccool in #7 I would like to propose the following resolution...

Proposal: Reduce the scope of the WoT Profile specification to focus only on goal 1 ("guarantee interoperability among all implementations of the profile") and remove goals 2 ("limit the implementation complexity for resource constrained devices") and 3 ("ensure that a thing description is also useful for a human reader").

[mlagally]

I have the following counter proposal:

Define the scope of the profile to guarantee interoperability among all implementations of the profile for global deployments, while limiting implementation efforts and enabling implementations of generic clients.

This reflects more the recent conversations in the task force.

[relu91]

My preference would be to simply reduce to goal 1:

guarantee interoperability among all implementations of the profile.

This alone is already a complex task. Plus, as I said in other comments, I like when one thing has just one specific goal. I'm afraid that adding:

while limiting implementation efforts and enabling implementations of generic clients to

contribute to the noise in the discussion process. Just my 2 cents.

[mlagally]

The scope has been clarified and the Profile specification implements that scope.
Let's close this issue.