W3C Web of Things enables applications to interact with, and orchestrate connected things at web scale. The standardized abstract interaction model exposed by WoT Thing Description enables applications to scale and evolve independently of the connected things.

Many network level protocols and standards for connected things have already been developed, and have millions of devices deployed in the field today. These standards are converging on a common set of transport protocols and transfer layers, but each has peculiar content formats, payload schemas, and data types.

Despite using unique formats and data models, the high level interactions exposed by most connected things can be modeled using the Event, Action, and Property Interactions of the WoT Thing Description.

Protocol Binding Templates enable a Thing Description to be adapted to the specific protocol usage across the different standards. This is done through additional descriptive vocabulary that is added to the Thing Description.

This document describes the initial set of design pattern and vocabulary extensions to WoT Thing Description that make up the Protocol Binding Templates. It is expected over time that additional protocols will be accommodated by further extending the Binding Templates, adding new design patterns and new vocabulary.

Please contribute to this draft using the GitHub Issue feature of the WoT Protocol Binding Templates repository. For feedback on security and privacy considerations, please use the WoT Security and Privacy Issues, as they are cross-cutting over all our documents.

Introduction

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.

Specifically, the Protocol Binding Template adapts to the underlying protocol in the following ways.

Payload Structure

The data definition language and schema of inputData and outputData elements is extended to allow nesting of arrays and objects. Value constants and variable specifications may be intermixed.

Data Types and value constraints

Simple data types and value constraints are currently used in a layered and descriptive way in WoT Thing Description. Additional forms of constraints are available to help adapt to the underlying data types.

Media Types

Maximum use should be made of Internet and Web Media Types in order to decouple applicaitons from connected things. Standard bridges and translations from proprietary early formats to web-friendly languages like JSON and XML are part of the adaptation needed.

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

Protocol Methods

There is a relatively small set of methods that can cover most standard communication patterns, based on REST and PubSub. GET, PUT, POST, DELETE, PATCH, OBSERVE, PUBLISH,and SUBSCRIBE

These are mapped to the abstract WoT interaction verbs InvokeAction, CancelAction, GetProperty, SetProperty, ObserveEvent, SubscribeEvent, UnsubscribeEvent

Protocol Options

Protocol Options are specified in the Protocol Binding, and are used to select transfer modes, to request notifications from observable resources, and to extend the semantics of the protocol methods.

Protocol Binding Templates Overview

This section describes each mechanism of the protocol binding template with examples

Payload Structure

Payload Structure is determined by the inputData and outputData elements. These share a common internal vocabulary, only being differentiated by the direction of the data transfer. An inputData binding element informs the client how to construct the data payload for a particular interaction. The outputData element informs the client how to extract information from the returned payload.

In addition to the example pattern in [TD] of an object with name/value constructs or simple arrays, Protocol Bindings for existing standards require nested arrays and objects, and some constant values will appear in objects.

For example, instead of the form commonly seen:

            {
              "level": 50,
              "time": 10
            }
          

SenML might use the following construct:

          [
            {
              "bn": "/example/light/"
            },
            {
              "n": "level",
              "v": 50
            },
            {
              "n": "time",
              "v": 10
            }
          ]
        

A Batch Collection according to OCF may be structured like this:

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

And an IPSO Smart Object on LWM2M:

          {
            "bn": "/3001/0/",
            "e": [
              {
                "n": "5044",
                "v": 0.5
              },
              {
                "n": "5002",
                "v": 10.0
              }
            ]
          }
        

The Protocol Binding template for each of these payloads will be structured according to the desired payload structure.

For the Simple Payload in Example 1 above, the inputData element would be structured as follows:

          {
            "inputData": {
              "type": "object",
              "fields": [
                {
                  "name": "level",
                  "value": {
                    "type": ["integer", "sch:levelvalue" ],
                    "min": 0,
                    "max": 255
                  }
                },
                {
                  "name": "time",
                  "value": {
                    "type": ["integer", "sch:ramptimevalue" ],
                    "min": 0,
                    "max": 65535
                  }
                }
              ]
            }
          }
        

For the SenML Payload in Example 2 above, the inputData element would be structured as follows:

          {
            "inputData": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "fields": [
                    {
                      "name": "bn",
                      "value": "example/light"
                    }
                  ]
                },
                {
                  "type": "object",
                  "fields": [
                    {
                      "name": "n",
                      "value": "level"
                    },
                    {
                      "name": "v",
                      "value": {
                        "type": ["integer", "sch:levelvalue" ],
                        "min": 0,
                        "max": 255
                      }
                    }
                  ]
                },
                {
                  "type": "object",
                  "fields": [
                    {
                      "name": "n",
                      "value": "time"
                    },
                    {
                      "name": "v",
                      "value": {
                        "type": ["integer", "sch:ramptimevalue" ],
                        "min": 0,
                        "max": 65535
                      }
                    }
                  ]
                }
              ]
            }
          }
        

For the OCF Batch Payload in Example 3 above, the inputData element would be structured as follows:

          {
            "inputData": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "fields": [
                    {
                      "name": "href",
                      "value": "/light/level"
                    },
                    {
                      "name": "rep",
                      "type": "object",
                      "fields": [
                        {
                          "name": "dimming",
                          "value": {
                            "type": ["integer", "sch:levelvalue" ],
                            "min": 0,
                            "max": 255
                          }
                        }
                      ]
                    }
                  ]
                },
                {
                  "type": "object",
                  "fields": [
                    {
                      "name": "href",
                      "value": "/light/time"
                    },
                    {
                      "name": "rep",
                      "type": "object",
                      "fields": [
                        {
                          "name": "ramptime",
                          "value": {
                            "type": ["integer", "sch:ramptimevalue" ],
                            "min": 0,
                            "max": 65535
                          }
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          }
        

For the IPSO/LWM2M Payload in Example 4 above, the inputData element would be structured as follows:

          {
            "inputData": {
              "type": "object",
              "fields": [
                {
                  "name": "bn",
                  "value": "/3001/0/"
                },
                {
                  "name": "e",
                  "type": "array",
                  "items": [
                    {
                      "type": "object",
                      "fields": [
                        {
                          "name": "n",
                          "value": "5044"
                        },
                        {
                          "name": "v",
                          "value": {
                            "type": ["float", "sch:levelvalue"],
                            "min": 0.0,
                            "max": 1.0
                          }
                        }
                      ]
                    },
                    {
                      "type": "object",
                      "fields": [
                        {
                          "name": "n",
                          "value": "5002"
                        },
                        {
                          "name": "v",
                          "value": {
                            "@type": ["float", "sch:ramptimevalue"],
                            "min": 0.0,
                            "max": 6553.5
                          }
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          }
        

Data Types and value constraints

Note that in Example 5 above, the values are floating point while the other examples have integer values. It is up to the client to adapt to the range and type as well as the engineering units provided.

Media Types

Media Types define the serialization details and other rules for processing the payloads. The media type is used to select a serializer/deserializer and to select an additional set of rules and constraints for the protocol driver.

For example, the mediaType "application/ocf+cbor" indicates that CBOR serialization is used, but also that OCF rules and namespaces apply to the processing of the representations.

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

Some special protocol drivers may be invoked by using a non-registered media type e.g. x- along with a custom URI scheme and its own set of protocol methods and options defined for that URI scheme.

Protocol Methods and Options

Each target protocol may specify different method names for similar methods, and there may be semantic differences beween similar methods of different protocols. Additionally, will use different methods for mapping to a particular WoT Interaction type. For example, POST may be used for setting a property value in one protocol, while PUT may be used in another. For these reasons, we require the ability to specify which method to use for a particular interaction. We also will provide vocabulary to differentiate between methods of different protocols.

The W3C RDF vocabulary for HTTP [ref] is used to identify the methods and options specified in the HTTP protocol bindings.

For the sake of consistency, we will derive a similar vocabulary for each target protocol, e.g. CoAP, MQTT.

Protocol Methods

The example below shows some method definitions for various protocols.

          "http:methodName": "get"
          "mqtt:methodName": "subscribe"
          "coap:methodName": "get"
        

Protocol Options

Header options in HTTP, CoAP, MQTT sometimes must be included in a protocol binding in order to successfully interact with the underlying protocol. The example below shows the structure of the definiton for http header options, according to the W3C HTTP Vocabulary in RDF.

          "http:messageHeader":
            [
              {
                "http:fieldName": "Accept",
                "http:fieldValue": "application/json"
              },
              {
                "http:fieldName": "Transfer-Encoding",
                "http:fieldValue": "chunked"
              }
            ]
        
Note: different links in a binding may need different header constructions, therefore the messageHeader construct is an extension of the TD element "link".

Returned Location Information

Sometimes an interaction returns information in the form of a header option or special payload back to the client when a long running operation such a a subscription or certain type of action is invoked. This can be the form of a created resource or handle.

Processing Model and Runtime

This section describes the processing model for Protocol Bindings with respect to the abstract WoT Interactions provided by the Scripting API.

inputData and outputData elements are processed and value scaling is performed in the application library or adaptation layer

link href, method, options, and mediaType are processed in a driver context isolated from the application

The application, or a protocol adaptation layer, fills in the inputData and sends it along with the selected link contents to the protocol driver or, in the case of get, recieves a payload form the protocol driver and uses outputData to extract the field values of interest.

The separation of execution context between the application and the protocol driver enables isolation of faut domains and isolation of security domains.

( discuss binding for Secure communications, security binding )

( discuss binding for Proxy Thing and Exposed Thing )

Bindings for Properties

This section describes unique aspects of protocol bindings for WoT Property type interactions

The abstract methods exposed for the Property Interaction are getproperty setproperty. These are mapped by using link relations that describe the abstract method, resulting in a semantic interpretatoin similar to HTML form submission.

        

For example a link having href=/example/level, rel=wot:setProperty, and coap:methodName=coap:post conveys the statement:

To do a setProperty of the subject Property (context of the link), perform a post on the resource at the target URI /example/level.

Properties may be observable, defined by the the TD keyword "observable". If there is an observe link and a retrieve link, the observe link may be indicated by including rel=wot:observe in the link. The observe link may also specify header options to use, for example CoAP obs=0 in the header to start observation.

Bindings for Actions

This section describes unique aspects of protocol bindings for WoT Action type interactions.

The abstract methods on Actions are invokeAction, modifyAction, and cancelAction.In the same way that the abstract methods on properties are mapped using link relations, the abstract methods of actions are also mapped.

        

For example a link with href=/example/levelaction, rel=wot:invokeAction, and coap:methodName=coap:post conveys the statement:

To do an invokeAction of the subject Action (context of the link), perform a post on the resource at /example/levelaction.

If the Action returns a handle to a created item, the protocol binding may indicate the manner in which the location or handle of the item is returned to the client by using the "expects" item in the link to describe the returned information.

Bindings for Events

This section describes unique aspects of protocol bindings for WoT Event type interactions.

The abstract methods on Events are subscribeEvent, unsubscribeEvent, and observe. The subscribeEvent operation returns a location or resource URI from which events may be obtained, either by observation or some other method.

By contrast, the MQTT subscribe operation is more like an observe of a pre-defined or yet-to-be defined item, also known as a topic.

The binding for Events allows either pre-defined URIs to observable or pubsub resources, or the pattern of subscription creation which returns an observable or pubsub URI.

If the binding offers a subscription, there will be a link with rel=wot:subscribeEvent

If the binding offers an observable Event resource from which events are obtained directly, there will be a link with rel=wot:observe

        

For example a link having href=/example/levelevent, rel=wot:subscribeEvent, and coap:methodName=coap:post conveys the statement:

To do a subscribeEvent of the subject Event (context of the link), perform a post on the resource at /example/levelevent.

If the Event supports subscription, the protocol binding may indicate the manner in which the location of the event source is returned to the client by using the "expects" item in the link to describe the returned information.

Vocabulary

This section specifies the vocabulary for protocol binding templates

Examples of Thing Descriptions including protocol bindings

OCF light and motion sensor using CoAP on LAN

LWM2M+IPSO environmental sensor from MQTT brokers, LAN and cloud

SmartThings Endpoint API using HTTP cloud-to-cloud

References

IANA link relations https://www.iana.org/assignments/link-relations/link-relations.xhtml

"profile" link relation https://tools.ietf.org/html/rfc6906

A media type defines both the semantics and the serialization of a specific type of content. In many cases, media types have some built-in extensibility or openness, so that specific instances of the media type can layer additional semantics on top of the media type's foundation. In this case, a profile is the appropriate mechanism to signal that the original semantics and processing model of the media type still apply, but that an additional processing model can be used to extract additional semantics.

HTTP vocabulary

Security and Privacy Considerations

Security and privacy considerations are still under discussion and development; the content below should be considered preliminary. Due to the complexity of the subject we are considering producing a separate document containing a detailed security and privacy considerations discussion including a risk analysis, threat model, recommended mitigations, and appropriate references to best practices. A summary will be included here. Work in progress is located in the WoT Security and Privacy repository. Please file any security or privacy considerations and/or concerns using the GitHub Issue feature.

Security is a cross-cutting issue that needs to be taken into account in all WoT building blocks. The W3C WoT does not define any new security mechanisms, but provides guidelines to apply the best practices from Web security, IoT security, and information security for general software and hardware considerations.

The WoT Thing Description must be used together with integrity protection mechanisms and access control policies. Users must ensure that no sensitive information is included in the TDs themselves.

The WoT Binding Templates must correctly cover the security mechanisms employed by the underlying IoT Platform. Due to the automation of network interactions necessary in the IoT, operators need to ensure that Things are exposed and consumed in a way that is compliant with their security policies.

The WoT Runtime implementation for the WoT Scripting API must have mechanisms to prevent malicious access to the system and isolate scripts in multi-tenant Servients.

Acknowledgements

Special thanks to all active Participants of the W3C Web of Things Interest Group and Working Group for their technical input and suggestions that led to improvements to this document.