W3C Web of Things enables applications to interact with and orchestrate connected Things at Web scale. The standardized abstract interaction model exposed by the WoT Thing Description enables applications to scale and evolve independently of the individual 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 Property, Action, and Event interaction patterns 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 used in the Thing Description.

This document describes the initial set of design pattern and vocabulary extensions to the 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 vocabulary and new design patterns.

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.

Protocol Adaptation

Protocol Binding Templates enable clients to adapt to the underlying protocol and network-facing API constructions. Once the base protocol (e.g., HTTP, CoAP, MQTT, etc.) is identified, the following adaptions specifiy the particular use within the given Platform.

Protocol Methods and Options

Most protocols have a relatively small set of methods that define the message type, the semantic intention of the message. As a starting point, a superset of REST and PubSub can cover most standard communication patterns. Common methods are GET, PUT, POST, DELETE, PATCH, PUBLISH, and SUBSCRIBE.

The protocol methods are mapped to the abstract WoT Interaction verbs readProperty, writeProperty, observeProperty, invokeAction, subscribeEvent, unsubscribeEvent.

Possible protocol options are also specified in the Protocol Binding. They are used to select transfer modes, to request notifications from observable resources, or otherwise extend the semantics of the protocol methods.

Media Types

Maximum use should be made of IANA-registered Media Types (e.g., application/json) in order to decouple applications from connected Things. Standard bridges and translations from proprietary formats to Web-friendly languages such as 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.

Payload Structure

Data serialized to a standard Media Type still remains in a structure specific to the Platform data model and needs to be understood by clients (cf. various types of JSON documents).

The data definition language and schema of inputData and outputData elements allows for describing arbitrary structures by 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. A Platform-specific 8-bit unsigned integer, for instance, can be defined as Integer with a minimum of 0 and maximum of 255; the system-specific representation (e.g., exact number of bits) on server and client is not relevant for interoperability.

Protocol Binding Templates Overview

This section describes the mechanisms of protocol binding templates with examples.

Data Elements

The inputData and outputData elements describe the payload structure and data items that are passed between client and server during interactions. The naming is from the perspective of the server; therefore inputData are sent from client to server, and outputData are returned from server to client in responses.

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",
                "field": [
                  {
                    "name": "level",
                    "@type": ["sch:levelvalue],
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 255
                  },
                  {
                    "name": "time",
                    "@type": ["sch:ramptimevalue"],
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 65535
                  }
                ]
              }
            }
          

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

            {
              "inputData": {
                "type": "array",
                "item": [
                  {
                    "type": "object",
                    "field": [
                      {
                        "name": "bn",
                        "type": "string",
                        "const": "example/light"
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "field": [
                      {
                        "name": "n",
                        "type": "string",
                        "const": "level"
                      },
                      {
                        "name": "v",
                        "@type": ["sch:levelvalue"],
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 255
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "field": [
                      {
                        "name": "n",
                        "type": "string",
                        "const": "time"
                      },
                      {
                        "name": "v",
                        "@type": ["sch:ramptimevalue"],
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 65535
                      }
                    ]
                  }
                ]
              }
            }
          

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

            {
              "inputData": {
                "type": "array",
                "item": [
                  {
                    "type": "object",
                    "fields": [
                      {
                        "name": "href",
                        "type": "string",
                        "const": "/light/level"
                      },
                      {
                        "name": "rep",
                        "type": "object",
                        "field": [
                          {
                            "name": "dimming",
                            "@type": ["sch:levelvalue"],
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 255
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "field": [
                      {
                        "name": "href",
                        "type": "string",
                        "const": "/light/time"
                      },
                      {
                        "name": "rep",
                        "type": "object",
                        "field": [
                          {
                            "name": "ramptime",
                            "@type": ["sch:ramptimevalue"],
                            "type":"integer",
                            "minimum": 0,
                            "maximum": 65535
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          

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

            {
              "inputData": {
                "type": "object",
                "field": [
                  {
                    "name": "bn",
                    "type": "string",
                    "const": "/3001/0/"
                  },
                  {
                    "name": "e",
                    "type": "array",
                    "item": [
                      {
                        "type": "object",
                        "field": [
                          {
                            "name": "n",
                            "type": "string",
                            "const": "5044"
                          },
                          {
                            "name": "v",
                            "@type": ["sch:levelvalue"],
                            "type": "float",
                            "minimum": 0.0,
                            "maximum": 1.0
                          }
                        ]
                      },
                      {
                        "type": "object",
                        "field": [
                          {
                            "name": "n",
                            "type": "string",
                            "const": "5002"
                          },
                          {
                            "name": "v",
                            "@type": ["sch:ramptimevalue"],
                            "type": ["float"],
                            "minimum": 0.0,
                            "maximum": 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.

Form Element

The "form" element contains the URI pointing to an instance of the interaction and descriptions of the protocol settings and options expected to be used when between the client and server for the interaction.

Relation Types

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

For example, the Property interaction allows read and write operations. The protocol binding may contain a form for the read operation and a different form for the write operation. The value of the "rel" attribute of the form indicates which form is which and allows the client to select the correct form for the operation required.

            "rel": "readProperty"
            "rel": "writeProperty"
          

The vocabulary in section 5 lists the recommended set of form relations, and the full TD examples in section 6 contain example uses of form relation types.

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 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.

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 between 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 use the same ontology design pattern to derive a vocabulary for each target protocol, e.g. CoAP, MQTT.

The example below shows some method definitions for various protocols.

            "http:methodName": "get"

            "mqtt:methodName": "subscribe"

            "coap:methodCode": "0.01"
          

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 definition 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 forms in a binding may need different header constructions, therefore the messageHeader construct is an extension of the TD "form" element.

Returned Information

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

Forms for Created Items

An interaction may create a new item, such as an event subscription. A form template for interacting with the created item may be included in the protocol binding, with the URI of each item to be obtained via returned information (see above) when the item is created.

Interaction Types

This section describes unique aspects of protocol bindings for the three WoT interaction types.

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 readProperty writeProperty. These are mapped by using form relations that describe the abstract method, resulting in a semantic interpretation similar to HTML form submission.

          

For example a form having href=/example/level, rel=writeProperty, and http:methodName=post conveys the statement:

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

Properties may be observable, defined by the TD keyword "observable". If there is an observe form and a retrieve form, the observe form may be indicated by including rel=observe in the form. The observe form may also specify header options to use, for example CoAP observe option=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 form relations, the abstract methods of actions are also mapped.

          

For example a form with href=/example/levelaction, rel=invokeAction, and http:methodName=post conveys the statement:

To do an invokeAction of the subject Action (context of the form), 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 form 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.

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 form with rel=subscribeEvent

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

          

For example a form having href=/example/levelevent, rel=subscribeEvent, and http:methodName=post conveys the statement:

To do a subscribeEvent of the subject Event (context of the form), 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.

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.

Form elements 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 form contents to the protocol driver or, in the case of get, receives 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 fault domains and isolation of security domains.

Binding for Secure communications, Security Binding

Binding for Proxy Thing and Exposed Thing, Proxy Binding

Vocabulary

This section specifies the vocabulary for protocol binding templates

inputData and outputData Vocabulary

InputData and outputData elements describe the structure of the payload. General purpose Protocol Bindings require the addition of constant fields in payloads. The "value" keyword is extended to allow the use of value constants in the inputData and outputData elements.

Interaction Verbs

Interactions have one or more defined interaction verbs for each interaction pattern. Form Relations allow an interaction to have separate protocol mechanisms to support different interaction verbs.

Property Interactions

Properties provide '"read" and, optionally, "write" operations, which map to GET and PUT/POST of a REST API. Properties may also by observed, though some properties may not be observable.

readProperty

writeProperty

observe

Action Interactions

Actions provide '"invoke" and, optionally, "cancel" or "update" operations, which can also map to GET, PUT, POST, and DELETE of a REST API.

invokeAction

updateAction

cancelAction

observe

Event Interactions

Events may directly expose observable resources from which to obtain event instances. Events may provide '"subscribe" operations to create subscription resources, which may in turn be observed in order to obtain the events.

subscribeEvent

updateSubscription

cancelSubscription

observe

Form Vocabulary

Extensions to the form vocabulary provide a way to inform the client about protocol methods, options, and status codes.

HTTP form vocabulary

http:methodName [ "GET", "PUT", "POST", "DELETE"]

http:MessageHeader example: [ {"http:fieldName": "accept", "http:fieldValue": "text/plain"} ]

http:fieldName [ accept, content-type, transfer-encoding ]

http:fieldValue

CoAP form vocabulary

coap:methodCode [ "0.01", "0.02", "0.03", "0.04" ]

coap:options example: [ { "coap:optionCode": 6, "coap:optionValue": 49 } ]

coap:optionCode

coap:optionValue

MQTT form vocabulary

mqtt:methodName [ "PUBLISH", "SUBSCRIBE" ]

mqtt:options example: [ { "mqtt:optionName": "qos", "mqtt:optionValue": 1 }]

mqtt:optionName [ qos, retain ]

mqtt:optionValue

Examples of Thing Descriptions including protocol bindings

TD with simple payload format

        {
          "@context": [
            "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
            "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
        	  {"iot": "http://iotschema.org/"}
          ],
          "@type": [ "Thing", "iot:Light", "iot:Dimmer", "iot:BinarySwitch" ],
          "base": "http://example.com",
          "name": "Lamp",
          "interaction": [
            {
              "name": "Switch State",
              "@type": ["Property", "iot:SwitchStatus"],
              "outputdata":  {
                "@type": ["iot:SwitchData"],
                "type": "boolean"
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json"
                }
              ]
            },
            {
              "name": "Current brightness",
              "@type": ["Property", "iot:CurrentDimmer"],
              "outputdata":  {
                "@type": ["iot:DimmerData"],
                "type": "number"
              },
              "form": [
                {
                  "href": "/example/light/currentdimmer",
                  "mediatype": "application/json"
                }
              ]
            },
            {
              "name": "Switch On",
              "@type": ["Action", "iot:SwitchOn"],
              "outputdata":  {
                "@type": iot:SwitchData,
                "type": "boolean",
                "const": true
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json"
                }
              ]
            },
            {
              "name": "Switch Off",
              "@type": ["Action", "iot:SwitchOff"],
              "outputdata":  {
              "@type": iot:SwitchData,
              "type": "boolean",
              "const": false
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json"
                }
              ]
            },
            {
              "name": "Set brightness level",
              "@type": ["Action", "iot:SetDimmer"],
              "inputdata":  {
                "@type": ["iot:DimmerData"],
                "type": "number"
              },
              "form": [
                {
                  "href": "/example/light/currentdimmer",
                  "mediatype": "application/json"
                }
              ]
            }
          ]
        }
      

TD with complex payload and multiple protocol options

        {
          "@context": [
            "http://w3c.github.io/wot/w3c-wot-td-context.jsonld",
            "http://w3c.github.io/wot/w3c-wot-common-context.jsonld",
        	  {"iot": "http://iotschema.org/"}
          ],
          "base": "http://example.com/",
          "@type": [ "Thing", "iot:Light", "iot:Dimmer", "iot:BinarySwitch" ],
          "name": "Lamp",
          "interaction": [
            {
              "name": "Switch State",
              "@type": ["Property", "iot:SwitchStatus"],
              "outputdata":  {
                "type": "object",
                "observable": "true",
                "field": [
                  {
                    "name": "switch",
                    "@type": ["iot:SwitchData"],
                    "type": "boolean",
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json",
                  "rel": "td:readProperty",
                  "http:methodName": "http:get"
                },
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json",
                  "rel": "td:writeProperty",
                  "http:methodName": "http:post"
                },
                {
                  "href": "mqtt://example.com/example/light/currentswitch",
                  "rel": "td:observe",
                  "mqtt:methodName": "mqtt:subscribe"
                }
              ]
            },
            {
              "name": "Current brightness",
              "@type": ["Property", "iot:CurrentDimmer"],
              "outputData": {
                "type": "object",
                "observable": "true",
                "field": [
                  {
                    "name": "brightness",
                    "type": "integer",
                    "@type": ["iot:DimmerData" ],
                    "minimum": 0,
                    "maximum": 255
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/currentdimmer",
                  "mediatype": "application/json",
                  "rel": "td:readProperty",
                  "http:methodName": "http:get"
                },
                {
                  "href": "/example/light/currentdimmer",
                  "mediatype": "application/json",
                  "rel": "td:writeProperty",
                  "http:methodName": "http:post"
                },
                {
                  "href": "mqtt://example.com/example/light/currentdimmer",
                  "rel": "td:observe",
                  "mqtt:methodName": "mqtt:subscribe"
                }
              ]
            },
            {
              "name": "Transition Time",
              "@type": ["Property", "iot:TransitionTime"],
              "outputData": {
                "type": "object",
                "field": [
                  {
                    "name": "transitiontime",
                    "type": "integer",
                    "@type": ["iot:TransitionTimeData" ],
                    "minimum": 0,
                    "maximum": 255
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/transitiontime",
                  "mediatype": "application/json",
                  "rel": "td:readProperty",
                  "http:methodName": "http:get"
                },
                {
                  "href": "/example/light/transitiontime",
                  "mediatype": "application/json",
                  "rel": "td:writeProperty",
                  "http:methodName": "http:post"
                }
              ]
            },
            {
              "name": "Switch On",
              "@type": ["Action", "iot:SwitchOn"],
              "outputdata":  {
                "type": "object",
                "field": [
                  {
                    "name": "switch",
                    "type": "boolean",
                    "const": true
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json",
                  "rel": "td:invokeAction",
                  "http:methodName": "http:post"
                }
              ]
            },
            {
              "name": "Switch Off",
              "@type": ["Action", "iot:SwitchOff"],
              "outputdata":  {
                "type": "object",
                "field": [
                  {
                    "name": "switch",
                    "type": "boolean",
                    "const": false
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/currentswitch",
                  "mediatype": "application/json",
                  "rel": "td:invokeAction",
                  "http:methodName": "http:post"
                }
              ]
            },
            {
              "name": "Set brightness level",
              "@type": ["Action", "iot:SetDimmer"],
              "inputData": {
                "type": "object",
                "field": [
                  {
                    "name": "brightness",
                    "type": "integer",
                    "@type": ["iot:DimmerData"],
                    "minimum": 0,
                    "maximum": 255
                  },
                  {
                    "name": "transitiontime",
                    "type": "integer",
                    "@type": ["iot:TransitionTimeData"],
                    "minimum": 0,
                    "maximum": 65535
                  }
                ]
              },
              "form": [
                {
                  "href": "/example/light/",
                  "mediatype": "application/json",
                  "rel": "td:invokeAction",
                  "http:methodName": "http:post"
                }
              ]
            }
          ]
        }
      

References

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

"profile" 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.