w3c/wot-binding-templates

Web of Things (WoT) Binding Templates

Web of Things (WoT) Binding Templates

General information about the Web of Things can be found on https://www.w3.org/WoT/.

---

Binding Templates enable a Thing Description to be adapted to a specific protocol, data payload formats or platforms that combine both in specific ways. This is done through additional descriptive vocabularies, Thing Models and examples that aim to guide the implementors of Things and Consumers alike.

Logistics

• Call information: We use the W3C Calendar. You can find the next WoT TD/Binding Templates calls at https://www.w3.org/groups/wg/wot/calendar.
• Wiki (contains agenda): https://www.w3.org/WoT/IG/wiki/WG_WoT_Thing_Description_WebConf
• Contribution rules

Publications

• Latest Editor's Draft (syncs to this repository's main branch)
• Latest Working Draft
• Other deliverables: (Examples are bindings)
  • HTTP Binding Template
  • CoAP Binding Template
  • MQTT Binding Template
  • Modbus Binding Template
  • BACnet Binding Template
  • XML Binding Template

---

Instructions for Editors and Contributors

If you have followed the Contribution rules and want to contribute, please follow the instructions below.

Tooling

Some HTML files are automatically rendered from RDF sources. To render them, install Node.js (if necessary) and run:

$ npm i # to do once to install dependencies
$ node render.js

This rendering process is mandated through the use of a Husky pre-commit hook. Make sure to run npm install first to install husky in the first place.

Formatting

Please use EditorConfig by installing a plugin for your favorite editor. This detects the .editorconfig file and adjusts your IDE's behavior regarding indentation, line endings and more. Additionally, please adjust your IDE to use 120 line length, where each line that is longer than 120 should be continued in the following line.

If you do not wish to use EditorConfig, please set the following settings in your editor:

• Indentation Style: space
• Indentation Size: 4
• End of Line: lf
• Charset: utf-8

Labeling Conventions

We use the GitHub labels found at https://github.com/w3c/wot-binding-templates/labels. Please try to reuse the labels before creating new ones.

Known Implementations

The W3C WoT collects known implementations at https://www.w3.org/WoT/developers/. Implementations of Binding Templates are found under all categories.

wot-binding-templates's Issues

"unobserveproperty" is missing

"unobserveproperty" needs to be added in the following sections.
1.1.1 Protocol Methods and Options
2.3.1 Bindings for Properties

In addition, section 1.1.1 also needs to include "readallproperties", "writeallproperties", "readmultipleproperties", and "writemultipleproperties".

Mapping JSON to CBOR

Many target protocols will use CBOR for payload data; an example is OCF. The current proposal uses JSON for the payload template and will depend on an automatic conversion to CBOR.

However, the CBOR definition (https://tools.ietf.org/html/rfc7049) includes the following text, emphasis mine:

This specification puts no restrictions on CBOR-based protocols. An
encoder can be capable of encoding as many or as few types of values
as is required by the protocol in which it is used; a decoder can be
capable of understanding as many or as few types of values as is
required by the protocols in which it is used. This lack of
restrictions allows CBOR to be used in extremely constrained
environments.

In other words, a CBOR decoder does not need to support all CBOR features. This can lead to some issues when using general conversion from JSON, since specific JSON values can map to several different CBOR data types, depending on range and precision requirements. For example, suppose a particular decoder assumes that all floating-point numbers are 32-bit (single precision) and does not support other floating-point formats in the CBOR specification, such as 16-bit (half precision) floats. A general encoder might choose to use such a format unsupported by a target decoder for a given element of data given no other constraints.

Other features of CBOR that might not be supported on all devices are streaming string data (due to memory limitations) and specific number representations, such as bignums or 64-bit integers.

One possible resolution to the above situation would be to add some global options to the encoder to disallow certain CBOR features to ensure compatibility with the target device. These can be global options, rather than options on specific data items, since they arise from limitations of the CBOR encoder itself.

How does a Protocol Binding represent an item which is created as a result of an interaction

Several use cases involve invocation of an action or subscription to an event where an item is created as a result of the interaction.

How do Protocol Bindings work for exposed things?

We have focused on how to use Protocol Bindings to adapt an existing (ecosystem) thing to a Consumed Thing interface.

The discussion around there not being a "Standard WoT Protocol Binding" makes me wonder about using Protocol Bindings to construct Exposed Thing instances.

Maybe it will be obvious, but I think we should work through an example or 2.

Meta-interaction is missing from section 2.3 Interaction Types

There needs to be a sub-section in section 2.3 discussing meta-interaction at Thing level, and how binding works at the meta-interaction level.

subprotocol example and prose alignment with TD spec

In section Protocol Methods and Options, there is an example for subprotocol.

{
"subprotocol": "longpoll"
}

As an example, it would be better to show an example in context (such as below excerpted from TD spec).

{
"op": "subscribeevent",
"href": "https://mylamp.example.com/overheating",
"subprotocol": "longpoll"
}

In the paragraph that precedes the example in question, there are mentions of:

long polling, EventSource, or a simple non-multiplexed websocket protocol

To be consistent with TD spec, it should probably be changed to:

long polling (longpoll), WebSub [websub] (websub) and Server-Sent Events [eventsource] (sse)

Inconsistency between OCF Batch Payload Example and Schema

The constant value definitions in Example 7 DataSchema for OCF Batch Payload are:

"const": "/light/level"
"const": "/light/time"

To be consistent with Example 3 OCF Batch Example, they should be changed to:

"const": "/example/light/level"
"const": "/example/light/time"

Section 2.1.2 Data Types and value constraints not consistent with TD spec

In Section 2.1.2, it says:

It is up to the client to adapt to the range and type as well as the engineering units provided.

This is true for downstream payload (from Thing to Consumer).

For upstream payload, on the other hand, Consumer needs to honor those constraints as much as possible.

According to section 8.2 Data Schemas of TD spec, it says:

In general, Consumers should follow the data schemas strictly, not generating anything not given in the WoT Thing Description, but should accept additional data from the Thing not given explicitly in the WoT Thing Description.

Observable Properties

The concept of Observable Properties is already in the TD Editor's Draft and might end up in the Scripting API Editor's Draft soon. However, it is still completely open, how this should work on the protocol level.

For CoAP and some HTTP extensions, a single entry could work in the protocol binding:

"link": {
    "href": "coaps://mytemp.example.com/temp",
    "mediaType": "application/json",
    "http:methodName": "get",
    "observe": "coap:observe"
}

or "observe": "http:longpoll".

If reading the Property works through HTTP, but observing through WebSockets, we have a problem. Question is, if this case should even be in scope. A Thing providing this has to implement two different kind of interaction mechanisms anyway, so it could also simply model this as two Interactions: one normal Property and one Event.

Thoughts?

Is "allOf" in EXAMPLE 6-8 correct?

According to JSON Schema Validation, "allOf" means "An instance validates successfully against this keyword if it validates successfully against all schemas defined by this keyword's value.". Would @mjkoster check the EXAMPLE 6-8?

What are priorities for the next revision, next plugfest

• Created action
• Websocket based notification
• Webhook/web callback based notification
• simple TD changes...

Ex. 11 uses non-existing HTTP vocabulary term

The term http:messageHeader used in example 11 (see below) does not exist in the RDF vocabulary (RDF terms are case-sensitive).

"http:messageHeader":
  [
    {
      "http:fieldName": "Accept",
      "http:fieldValue": "application/json"
    },
    {
      "http:fieldName": "Transfer-Encoding",
      "http:fieldValue": "chunked"
    }
  ]

The proper term here would be http:headers, as follows:

"http:headers":
  [
    {
      "http:fieldName": "Accept",
      "http:fieldValue": "application/json"
    },
    {
      "http:fieldName": "Transfer-Encoding",
      "http:fieldValue": "chunked"
    }
  ]

MQTT Binding: Describing connection to the broker

Issue #13 tries to use MQTT as example for a Binding for Event.

A problem is that MQTT is not stateless: a SUBSCRIBE needs a preceeding CONNECT. So there needs to be implicit knowledge, that the connection needs to be established before an Interaction can be performed. This can be seen similar to a TCP connection that needs to preceed an HTTP request. Yet what about the information that needs to go into the CONNECT message? Should it be specified, if yes where, or can it be left open (as MQTT has no clear rules for agreed values, e.g. for last will message)?

Any thoughts?

Structure of protocol binding block and terminology

Issue raised as w3c/wot-architecture#3 was closed.
On the other hand, the issue about terminology of current protocol binding, I have.

Before starting WG, the architecture building blocks are reviewed according to WG charter.
We have introduced "protocol binding" with "binding templates" as one of blocks for communication between WoT servients which supports at least one of "http", "CoAP", "Web-socket" or "MQTT" defined by binding template.

Now the discussion for creating protocol binding document leads to following 2 issues.

1. the protocol binding block consists of 2 layers.

Top layer might be very thin and just extracting common API type from run-time such as "Property", "Action" and "Event".

Bottom layer is mapping data model for each protocol which is described in current practice as follows;
e.g. For HTTP,
API Type "Property"
"Read" is mapped to "GET"
"Write" is mapped to:"PUT"
API Type "Action"
"Invoke" is mapped to "POST"
"Update task:" is mapped to "PUT (on handle resource)"
"Cancel task" is mapped to "DELETE (on handle resource)"
API Type "Event"
"Subscribe" is mapped to "POST + (Long-)Polling/Chunking/Streaming of returned handle resource"
"Update subscription" is mapped to "PUT (on handle resource)"
"Cancel subscription" is mapped to "DELETE (on handle resource)"

This bottom layer is just the same as "binding template", I think.

I wonder that we should provide new name both of these 2 layers or no need.

2. All of protocols implementation must be covered by protocol binding or not

All of protocols such as OCF-defined over HTTP, one M2M defined over HTTP might be able to implemented as 1)'s bottom layer.

on the other hand, I figure out "legacy communication" block explicitly in architecture document. That is because current Panasonic's air conditioner WoT server implementation over Echonet is monolithic and it works well as "WoT Server".
So, I'd like to keep this legacy communication block in WoT architecture for accepting wide variety of implementation.

I'd like to get any comments.

'base' missing in Example 15

All interactions are relative without any global base

Broken links in Binding Spec to context files

See the discussion in w3c/wot-architecture#374

Section name 2.2.1 "Relation Types" is not accurate

Form no longer has "rel". What we have now is "op".

We should change the section title to something like "Operation Types".

Form Relation Types describe the expected result of performing the operation described by the form

This sentence also should change to something like:
"Form Operation Types describe intended semantics of performing the operation described by the form."

Section 2.2.2 Media Types should clarify the usage of "profile" attribute's in TD

Section 2.2.2 Media Types mentions profile attribute.

Additionally, there may be a profile which points to a URI for further description, for example a form with profile=http://iotschema.org/protocols/ipso.jsonld indicates that the target representation follows a set of additional encoding rules and constraints which are further defined at the URI by the profile attribute's value.

The profile attribute is not defined in TD.
I would suggest to remove this from this section.

Add the "subProtocol" form element

As discussed in the 2018-02-18 main WoT call, the subProtocol term is to specify which mechanism(s) to use for getting asynchronous notifications over http.

the choices are [ "LongPoll", "EventSource", and WebSocket" ]

where WebSocket is the simple upgrade to a dedicated socket for each interaction

PR #32 has this change

Event Implementation Proposal (HTTP+WebSocket)

"HTTP + Websocket" event implementation proposal had been presented both in the Main and TD Web meetings.

The AIs generated from the Web meetings:

1. Definition about the events in TD

This AI can be divided into the following 2 parts.
1.1. How to subscribe and unsubscribe the events? (e.g. uri, filter, handle)
1.2. How to get the event data? (e.g. uri includes protocol information)

2. Concrete payload data

I would like to brush up my proposal by referring to the protocol binding templates ( @mjkoster ), automotive wg ( @ashimura ), https://w3c.github.io/wot-thing-description/ , and so on.

See also w3c/wot-thing-description#17.

Links becoming Web Forms

After more complexity was pushed down to the Protocol Bindings, the link elements became quite verbose. The carry a lot of information about how to construct the request, so that they are rather Web forms than Web links!

Thus my proposal: Rename the link element of Interactions to form, which frees up the term link to be used to list the relations of this Thing to other Things (the Web links to other Things).

Review Comments: W3C Editor's Draft 23 January 2018

The review comments below apply to the W3C Editor's Draft 23 January 2018 at:
https://rawgit.com/mjkoster/wot-binding-templates/initial-spec-contribution/index.html

Examples in chapter 2

The examples are very useful to understand the concepts.
However the spec needs to give explicit references to OCF, IPSO, SenML, LWM2M
e.g.:
[SenML] - https://tools.ietf.org/html/draft-ietf-core-senml-12

OCF

• Which version of the OCF specification is used? 1.0 or 1.3?
• Attribute names in the example need fixing:

• Example:

[
{
"href" : "/example/light/level",
"rep" : {
"dimmingSetting": 50
}
} , {
"href" : "/example/light/time",
"rep" : {
"rampTime": 10
}
}
]

These name changes need to be carried through to the examples further down.

Chapter 2.2.3

It should be described how additional protocols can be integrated, so a guideline for binding to other protocols would be useful.

HTTP binding

If we consider HTTP, do all protocol implementations support the same set of header options? Is there a way for a thing to set protocol headers?

Chapter 3

This chapter informatively describes abstract methods (invokeAction, cancelAction, modifyAction, readProperty, writeProperty, subscribeEvent, unsubscribeEvent, observe) on the classes from the Vocabulary Definition in chapter 5 of the TD spec. Chapter 5 does not contain these methods. They need to be normatively specified in the TD.

What is "modifyAction" doing?

What is the purpose of "observe"?

Chapter 4

what is meant with the term "value scaling"?

Chapter 5

"observe" is currently specified for all elements of the TD. Is that intentional?

Media Types should be Content Types

Section 2.2.2 Media Types should be renamed as "Content Types".

Also, this section describes "profile" of a form, which is not defined in TD spec.
I would suggest to remove this.

Protocol Binding for OPC-UA

Is OPC-UA protocol-bindable (i.e. does it satisfy the WoT requirements)? Can we get it done this year or is it too much to bite off for now?

Review comments from August 2018

It appears a set of comments posted quite a while ago have not been addressed.

Please find the comments here.

CoAP Blockwise Indicator

It would be good to have metadata in the TD that tells from which payload size blockwise transfers should be used.

In addition -- or combined, there should be metadata if blockwise transfers are supported at all by the Thing.

no vacabulary defintion for CoAP and MQTT yet

in section section 3.3 we should clarify that CoAP and MQTT has no standardized RDF representation yet like for http

subscription, data, cancellation need to be added

Section 2.1.1 Payload Structure, in the first paragraph mentions input and output.

We should also mention subscription, data, cancellation in the same paragraph.

RDF-compliant inputData/outputData modeling

Comments from PR #20 by @vcharpenay:

I see two changes here: first, the @type statement is split into type parts and, second, you merge DataField and DataSchema classes.

Let me address them separately on this example:

"fields": [
    {
        "name": "level",
        "@type": ["sch:levelvalue"],
        "type": "integer",
        "min": 0,
        "max": 255
    },

Note: what about relying on the deployed iotschema.org vocabulary for your examples? Here, sch:levelvalue corresponds to http://iotschema.org/CurrentLevel. There is a typo in the class definition (hence, the 404 page) but the class exists.

Type statement

@type is a JSON-LD reserved keyword that maps to rdf:type. I assume that in the statement _:subject rdf:type sch:levelvalue, I assume that the statement subject (_:subject) is something like "203 with timestamp 2018-01-19T09:46:16+00:00", i.e. an actual level value.

The example schema definition above would map to RDF statements like:

_:subject
    rdf:type sch_levelvalue ;
    td:type td:Integer ;
    xsd:minInclusive "0" ;
    xsd:maxInclusive "255" .

in which, _:subject is the schema definition that validates "203 with timestamp 2018-01-19T09:46:16+00:00" and not the value itself. In fact, it would be more consistent if @type was integer, as defined here. For the same reason, "@type": ["integer", "sch:levelvalue"] would be an incorrect definition.

DataField vs. DataSchema

I am not sure that the change you propose here is consistent with the JSON schema validation spec, where fields must have a name and a value, which in turn must be a valid JSON schema. The spec is hard to interpret, though. But anyway, to me, this change also limits the reuse of schema definitions. For instance, one could give a unique URI to the definition of a byte value:

{
    "@id": "http://example.org/Byte",
    "name": "byte value",
    "@type": "Integer",
    "minimum": 0,
    "maximum": 255
}

You would then simply declare the following in your TD, as defined the current spec:

"fields": [
    {
        "name": "level",
        "value": "http://example.org/Byte"
    },

If you merge DataField and DataSchema, you cannot simply reference this new Byte type.

Introduction section structure and content

I think that Introduction section does not need to have a subsection structure.
Currently, section 1 only contains one subsection 1.1.
I would suggest to flatten the content by removing the structure in Introduction.

Additional comments regarding the content.

Protocol Binding Templates consist of reusable vocabulary and design pattern extensions to the WoT Thing Description format that enable an application client to interact, using a consistent interaction model, with Things that expose diverse protocols and protocol usage.

With regards to "design pattern extension to the WoT Thing Description", can we simply say "extension to the WoT Thing Description"? Does saying "design pattern" add anything to the meaning of the sentence? Note that there is also a mention to "design pattern" in the Abstract of the document.

As a starting point, a superset of REST and PubSub can cover most standard communication patterns. Common methods are GET, PUT, POST, DELETE, PUBLISH, and SUBSCRIBE.

This sounds like we are defining a vocabulary for those common methods.

However, I think the plan is to define (or re-use existing) vocabularies for protocols, which means we are not defining the common methods as a vocabulary.

I think we need to re-word the above quoted sentence to reflect this.

WoT Protocol Bindings depend on consistent use of Media Types for customization of the upper layers.

At first glance, this sentence is not very clear to me.
I suggest to describe more to make it clearer for readers of this Introduction section.

My understanding is that consistent use of Media Types is to enable properly processing serialized documents by indicating through Media Types the serialization format and additional data constraints and rules, so that the upper layer knows what to do with the data.

Consider the Mozilla pattern for events

uriVariables needs to be described

Section 2.2 Forms Element needs to describe uriVariables.

Compile proposal for URI Templates

With the DataSchema we can currently describe payloads. Many existing APIs also take parameters in the URI (e.g., the query), which would, for instance, be part of Action arguments.

We should include a mechanism similar to DataSchema to describe URI Template parameters, when href contains such a URI Template.

Do we need a protocol binding to describe notification using WebHooks?

The Web Hook pattern is where the notifying entity (exposed thing in WoT) sends notifications by using a PUT or POST method on a "Web Hook" resource in the observing entity (Application or Consumed Thing in WoT).

Many systems and devices support the Web Hook pattern. Typically, there is a way create or update a Web Hook address in the notifying entity that points back to the observing entity.

A protocol binding for Web Hooks would need to explain how the client configures a callback address on the device for delivery of notifications. There should be some way for a client to manage its web hooks, e.g. to remove them when it is done with them.

Web hooks may also be used for direct communication between devices or things.

One example of a Web Hook pattern is implemented by the IETF CoRE Dynlink draft, using links with "bnd=push".

https://datatracker.ietf.org/doc/draft-ietf-core-dynlink/

This pattern would also be needed if we wanted to give a thing the ability to be configured to publish to a pub/sub broker or to a multicast address on property update or event emit.

Is a binding template specification necessary?

What is the reason that an abstract template binding specification is necessary? Would it not be simpler to just create specification(s) with concrete bindings to the small number of web protocols that are needed?

For example:

• HTTP binding
• WebSocket binding (which extends the HTTP binding)
• CoAP binding (which is very similar to the HTTP binding but adds a pub/sub mechanism).

Note that MQTT is not a web protocol and therefore I see it as existing at a different level of abstraction to the Web of Things, requiring a gateway to bridge MQTT to a Web Thing protocol.

I understand there could be different serialisations to deal with like JSON and CBOR, but hopefully the number of those is small too. Formats which don't converge on a W3C standard serialisation (like SenML, OCF and LWM2M) could also be bridged to the W3C format using a gateway.

The reason I ask this is that trying to come up with an abstract specification which can be applied to any protocol (including non-web protocols) and any data format creates a huge amount of complexity which I'm not convinced is going to achieve the intended outcome.

I would argue that an abstract specification which can be applied to hundreds of combinations of protocols and data formats is not going to make ad-hoc interoperability possible. Interoperability will require converging on a very small set of web protocols and data formats, but with software which can bridge the Web of Things to other protocols. This is what has happened with the web of pages which has converged on HTTP and HTML, but can provide a layer of abstraction on top of services using other underlying protocols like SMTP, IRC, CalDAV etc.

Start list of protocols and platform dialects to describe

We need a list of protocols that serves as input to find the vocabulary needed to have protocol binding descriptions. The list items should be prioritized in the sense where to begin; this should be based on the available information and experts to help. Overall, this will be related to the liaisons W3C WoT has.

Initial (unsorted) list to be extended:

• ("vanilla") HTTP
• ("vanilla") CoAP
  • CoAP
  • CoAP-over-TCP
  • CoAP-over-WebSockets
• OCF
  • OCF CoAP
• oneM2M
  • oneM2M HTTP
  • oneM2M CoAP
  • oneM2M MQTT
  • oneM2M WebSockets
• ("vanilla") MQTT (lets use MQTT5, since previous versions do not provide the facilities required for open, WoT-like systems (e.g., no headers for Media Type etc.)
• OPC UA
  • UA-Binary over TCP

Inputs for MQTT Binding

Based on the Bundang meeting there was several decisions made (also see slides):

1. A MQTT client that publish data to a topic with the retain=true flag it can be defined as a Property since the broker will always response with the latest cached value that was published to this topic.
2. A MQTT client that publish data with the retain=flalse flag must use the WoT event definition.

3. A MQTT client that makes subscription to an topic to initate an internal action when a corresponding data is published to this topic. In that case this action must be defined as a WoT action.
4. Defining terms for MQTT based binding:

• mqtt:qos Quality of service level as number (0=at most once, 1=at least once, 2=exactly once)

• mqtt:retain Retain flag as boolean. If true, the broker will store the last retained message and the corresponding QoS for that topic

• mqtt:dup Duplicate flag for duplicated delivery

It has to be evaluated if a MQTT command term is also required (how about MQTTv5?).

Typo: readData, writeData in rel -> readProperty, writeProperty

In the first full example, the switch and brightness properties use rel values of readData and writeData. According to the text, these should be readProperty and writeProperty. The second example DOES use these values instead.

MQTT Vocabulary needs better terms

As a continuation of #61, we need to clarify which terms the MQTT vocabulary should use.

1. As of July 2019, commandCode is used whereas controlPacketTypeValue or short controlPacketValue is used in the MQTT spec as @sebastiankb mentioned.
2. Also we use "mqv:commandCode":8 instead of "mqv:commandCode":SUBSCRIBE .

I think that the first part is clear whereas the second one needs discussion

subProtocol lowercase only

in section 3.3.4 subProtocol should be subprotocol as defined in TD spec

@type inconsistencies in the examples

Hello,

I noticed that the semantic annotations in some examples in the wot-binding-template specification do not seem to follow the specification of DataSchema properly, as defined in https://w3c.github.io/wot-thing-description/#x6-5-1-3-semantic-annotation.

Here is how example 5 currently looks like:

{
  "schema": {
    "type": "object",
    "field": [
      {
        "name": "level",
        "@type": ["iot:LevelData],
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        }
      },
      {
        "name": "time",
        "@type": ["iot:TransitionTimeData"],
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 65535
        }
      }
    ]
  }
}

Correct me if I'm wrong, but I think the @type annotation describing the semantics of the fields should be part of the schema and not stay outside of it. So for instance the last field should look like:

{
        "name": "time",
        "schema": {
             "@type": ["iot:TransitionTimeData"],
             "type": "integer",
             "minimum": 0,
             "maximum": 65535
}

This is anyway how it has been defined in the wot-thing-description specification. This is a small thing but can be confusing when browsing both specifications.

If this is indeed an error, I hope it will be fixed. If not, please disregard this issue.

align with the vocabulary in "CoAP in RDF" ontology and IANA CoRE Parameters page

Change "coap:optionCode" to "coap:optionNumber" in the binding and reference implementation

Binding for next PlugFest (Prague 2018)

This examples shall serve as goal definition for the WoT Binding Templates FPWD; let's update this first ("sticky") post to keep it in sync with our consensus. The example is based on Example 1 from the TD spec.

{
  "@context": [ "http://w3c.github.io/wot/w3c-wot-td-context.jsonld" ],
  "@type": [ "Thing" ],
  "name": "MyLampThing",
  "interaction": [
    {
      "@type": [ "Property" ],
      "name": "status",
      "shema": { "dataType": "boolean" },
      "writable": true,
      "observable": true,
      "form": [
        {
          "rel": "readProperty",
          "href": "coaps://mylamp.example.com:5683/status",
          "mediaType": "application/ocf+cbor",
          "coap:methodCode": 1,
          "coap:options": [
            {
              "coap:optionNumber": 2049,
              "coap:optionValue": "1.1.0"
            }
          ]
        }, {
          "rel": "writeProperty",
          "href": "coaps://mylamp.example.com:5683/status",
          "mediaType": "application/json",
          "coap:methodCode": 3
        }, {
          "rel": "observeProperty",
          "href": "coaps://mylamp.example.com:5683/status",
          "mediaType": "application/json",
          "coap:methodCode": 1,
          "coap:options": [
            {
              "coap:optionNumber": 6,
              "coap:optionValue": 0
            }
          ]
        }
      ]
    }, {
      "@type": [ "Action" ],
      "name": "toggle",
      "form": [
        {
          "rel": "invokeAction",
          "href": "https://mylamp.example.com:443/toggle",
          "http:methodName": "POST",
          "http:MessageHeader": [
            {
              "http:fieldName": "Pragma",
              "http:fieldValue": "no-cache"
            }
          ]
        }
      ]
    }, {
      "@type": [ "Event" ],
      "name": "overheating",
      "shema": { "dataType": "string" },
      "form": [
        {
          "rel": "subscribeEvent",
          "href": "mqtt://broker.example.com:8883/MyLampThing/events/overheating",
          "mediaType": "application/json",
          "mqtt:messageType": 3
        }
      ]
    }
  ],
  "link": [
    {
      "rel": "contains",
      "href": "https://mylamp.example.com:443/smart-meter/td"
    }, {
      "rel": "locatedAt",
      "href": "https://myroom.example.com:443/"
    }
  ]
}

Mention of XML should be dropped

Section 1.1.2 Media Types says that:

Standard bridges and translations from proprietary formats to Web-friendly languages such as JSON and XML are part of the adaptation needed

Since TD natively only supports JSON at this point, I suggest we drop mention of "XML" from the sentence above.

Event Binding for CoAP Multicast

CoAP devices may emit events by POSTing to a specific multicast address + well-known path.

This information can easily packed into a TD. Question is if that multicast address should go into href or rather the mechanism how to join the multicast group.

"Platforms" with more than one meaning should be clarified

For example, section 1.1 Protocol Adaptation uses "Platform" as "IoT Platforms".

On the other hand, section 1.1.4 Data Types and Value Constraints uses "Platform" in the sense of "System Platform".

Uses of "Platform" this word should be properly qualified and be given clarification.

Use cases and requirements for protocol binding

Before we go much further, it would be valuable to gather some use cases and the requirements they imply. Here are some initial ideas for discussion:

• A smart home with an application hub on which people can install apps for the IoT devices they have purchased. The hub supports a range of protocols, e.g. HTTP, Web Sockets, CoAP and Bluetooth. Users can access apps on the hub from their smart phones. An app is a collection of resources including an application script, and Web resources for the user interface on the phone. The application script registers a thing with the hub and provides an implementation that includes the code for communicating with IoT devices. This code is platform specific, e.g. using the CoAP and Bluetooth modules for a NodeJS based platform. The application script abstracts the device behaviour in terms of properties, actions and events, decoupling consumers of the thing from the details of the protocol used by the device.

• The user interface for a service for a smart home is implemented as a Web page that runs on a smart phone, and is loaded from a hub/gateway on the home's WiFi local area network. Things are exposed to web page scripts as JavaScript objects in the web page's execution environment. The scripts are decoupled from the messaging with the hub/gateway using a web page library. This library uses WebSockets for asynchronous messaging with simple JSON messages.

• A variant of the previous use case in which the Web page is loaded from an application hub in the cloud. Applications can access things exposed by this hub, other cloud-based hubs, or hubs behind firewalls, e.g. in people's homes. The hubs are connected via Web protocols, e.g. WebSockets, or HTTP. There are several ways to support two way asynchronous messaging over HTTP. One involves both end-points acting as HTTP clients and HTTP servers. Another involves the use of HTTP Server-Sent Events, which is essentially the same as CoAP GET + Observe.

• A cloud hub that exposes services as things for easier application development. This uses things as a "narrow waist" to decouple apps from the networking details for accessing these services. Some examples include the weather, and information about opening hours for a zoo.

• A related use case involves subscribing to filtered events from a cloud service. The consumer passes a set of parameters when subscribing that the provider interprets to filter events of interest.

• A smart device that publishes its own things rather than relying on a hub. The device is accessed via CoAP and is able to provide the thing descriptions either by itself or by reference to a cloud server.

Note that I have simplified the above accounts by leaving out details of discovery, security etc., as I don't think these are so important to the requirements for binding templates.

Revising the 'form' vocabulary?

w3c/wot-thing-description#88 raised questions about the terms in our vocabulary and raised one issue:

• href takes the target URI. Usually it is used for (hyper-)references. In HTML, the target resource of a form goes into the action attribute.

  • action could be used.
  • This aligns with the HTML vocabulary, but is not very expressive. Also, I see the conflict with Actions; going back to read-only Properties and write through an Action is one option; actually doing something new and catering for writeable and observable Properties another.

• mediaType takes the media type for the serialization. It assumes the same media type for requests and responses. In HTML, the field for the request payload media type is enctype (with a small enum for values). accept was deferred down to the input element (for file uploads together with enctype multipart/form-data) and is now deprecated for HTML forms. For WoT, accept is a proposed option for the request payload schema.

  • encType could be used for request payload media type.
  • mediaType (as type is overloaded) for resonse/notification/event payload media type (use case would be an Action that consumes a different media type than it returns, e.g., to convert payloads for a constrained Thing.
  • This aligns with the HTML vocabulary, but is not very expressive :/

• *:method is binding-specific.

  • method could be an overarching term that can accept values from different vocabularies such as http:method or coap:methodCode
  • @vcharpeneay Would this work for the ontology behind?

• rel semantically identifies the form. This is not supported in the human-centric HTML forms. The closest match would be name.

  • rel for forms would be an actual improvement needed for a Web of Things, so that machines can understand their meaning.

Clarifying the scope and motivation for binding templates

An important point is to clarify in our published report whether we are defining a general means to describe existing protocol usage, e.g. current devices and IoT standards, or we are prescribing how to use IoT protocols in a way that maps to the abstract interaction model for the web of things. I suspect we are trying to do both, which could be very confusing to readers.

A further consideration is that in general, a fully declarative description of protocol usage is going to be very challenging as there is so much freedom in how applications layer on top of the underlying protocols. We should acknowledge that and make it clear that that isn’t our objective. Rather, we plan to focus on specific IoT standards suites that prescribe how to use the underlying protocols.

Our work also allows for applications that produce things to handle the IoT device protocols themselves. This is the approach that Benjamin Francis (Mozilla) and I have followed in our respective NodeJS implementations. Applications installed on a home gateway act as producers and consumers of things. Such applications can also act as suppliers of things to cloud based application servers as a basis to provide access to applications running on platforms external to the home firewall. Producer applications on the home gateway can make use of platform specific networking modules to work with specific devices, e.g. those for Apple Home Kit, and Android Things, as well as Bluetooth and Zigbee based devices.

This shows that standards for binding templates is a nice to have feature, rather than being required. So we need to acknowledge that and clearly show the benefits of binding templates. A clear priority should be prescriptive protocol binding between application platforms and platforms for user interfaces such as web browsers and native apps on smart phones. For me at least, this means we should give a high priority to Web protocols like HTTP and WebSockets.

Is rel used as a single string or as array?

The latest document uses rel as a single string (e.g., Example 9) and as an array structure (e.g., Example 17). Should be both variants possible?