Introduction to Protocol Binding Templates

[[WOT-THING-DESCRIPTION]] defines abstract operations such as readproperty, invokeaction and subscribeevent that describe the intended semantics of performing the operation described by the form in a Thing Description. In order for the operations to be performed on the affordance, a binding of the operation to the protocol needs to happen. In other words, the form needs to contain all the information for a Consumer to, for example read a property, with the protocol in the form.

Most protocols have a relatively small set of methods that define the message type, the semantic intention of the message. REST and PubSub architecture patterns result in different protocols with different methods. Each target protocol may specify different method names for similar operations, and there may be semantic differences between similar method names of different protocols. Additionally, Things may use different methods for performing a particular WoT operation. For example, an HTTP POST request may be used for a writeproperty operation in one Thing, while HTTP PUT may be used in another. For these reasons, Thing Descriptions require the ability to specify which method to use per operation.

Common methods found in REST and PubSub protocols are GET, PUT, POST, DELETE, PUBLISH, and SUBSCRIBE. Binding Templates describe how these existing methods and associated vocabularies can be used in a Thing Description to bind to the WoT operations. This is done by defining the URI scheme of the protocol and mapping the protocol methods to the abstract WoT operations such as readproperty, invokeaction and subscribeevent. In some cases, additional instructions are provided to explain how the vocabulary terms should be used in different cases of protocol usage.

The examples below shows the binding of the readproperty operation for the HTTP and Modbus protocols. Please note that these are examples and please always refer to the corresponding binding to learn about the relevant vocabulary terms and their values.

                                    {
                                        "href": "http://example.com/props/temperature",
                                        "op": "readproperty",
                                        "htv:methodName": "GET"
                                    }
                                

                                    {
                                        "href": "modbus+tcp://127.0.0.1:60000/1",
                                        "op": "readproperty",
                                        "modbus:function": "readCoil",
                                        "modbus:address": 1
                                    }
                                

The form elements in the examples above convey the following statements:

• Left Example: To do a readproperty of the subject Property Affordance by performing an HTTP GET request on the resource props/temperature to the host at example.com on port 80 (Port 80 is assumed as per [[RFC2616]]).
• Right Example: To do a readproperty of the subject Property Affordance using the readCoil function of Modbus at coil 1 of the device with the 127.0.0.1 address at its port 60000

                                    {
                                        "op": "invokeaction",
                                        "href": "http://192.168.1.32:8081/example/levelaction",
                                        "htv:methodName": "POST"
                                    }
                                

                                    {
                                        "op": "subscribeevent",
                                        "href": "mqtt://iot.platform.com:8088",
                                        "mqv:filter": "thing1/events/overheating",
                                        "mqv:controlPacket": "subscribe"
                                    }
                                

The form elements in the examples above convey the following statements:

• Left Example: To do an invokeaction of the subject Action Affordance by performing an HTTP POST request on the resource example/levelaction to the host at 192.168.1.32 on port 8081.
• Right Example: To do a subscribeevent of the subject Event Affordance by connecting to the MQTT broker at iot.platform.com and port 8088, then subscribing to the topic thing1/events/overheating.

In some cases, header options or other parameters of the protocols need to be included. Given that these are highly protocol dependent, please refer to the bindings listed in [[[#protocol-bindings-table]]]. Additionally, protocols may have defined Subprotocols that can be used for some interaction types. For example, to receive asynchronous notifications using HTTP, some servers may support long polling (longpoll), WebSub [[WebSub]] (websub) and Server-Sent Events [[eventsource]] (sse).

The use of a subprotocol is expressed with the subprotocol field, as defined in [[!WOT-THING-DESCRIPTION]]. It can be used in a form instance to indicate the use of one of these protocols, for example long polling with its special use of HTTP:

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

The values that the subprotocol term can take is not constrained by the [[!WOT-THING-DESCRIPTION]] since different protocols can have different Subprotocols. For WebSockets, the IANA-registered Websocket Subprotocols [[iana-web-socket-registry]] may be used. For CoAP, "subprotocol":"cov:observe" can be used to describe asynchronous observation operations as defined by [[RFC6741]]. The subprotocols can be defined and explained as a part of a protocol or platform binding subspecification.

Overall, a protocol binding template specifies the values and structure of certain vocabulary terms in a TD. The table below lists the vocabulary term, the class it belongs to and whether the subspecification is required to specify the values the term can take. In addition to these, additional terms for describing protocol options are typically added.

Existing Protocol Binding Templates

The table below summarizes the currently specified protocols in their respective Binding Template Subspecification.

Using a Thing Description with a Protocol Binding Template Subspecification

Protocol Binding Templates contain vocabularies that extend the vocabulary found in the [[WOT-THING-DESCRIPTION]]. This means that the way a TD is consumed and how the interactions happen with the Thing are adapted to such vocabularies. The steps below explain how this process typically looks like.

1. Detect the protocol: Upon the activation of a form to execute the operation, the Consumer SHOULD look at the href member and the base (if exists) and identify the protocol.
2. Choose the correct protocol stack: The Consumer SHOULD use choose the correct protocol from its protocol software stacks.
3. Validate the forms part of the TD: Using the JSON Schema instances provided in the respective subspecification or through programmatically checking key value pairs, the Consumer MAY validate the respective form terms in order to verify they are correctly specified in the TD instance.
4. Start communication: The Consumer SHOULD send requests for the chosen operation as specified by the form and additional behavior that is expected. These are specified using the different form terms such as subprotocol or other vocabulary terms introduced by the protocol binding. The interaction affordance data exchanged with the Thing SHOULD be according to the Data Schema and Content Type present in the TD. The corresponding Data Schema to the operation can be found in the [[WOT-THING-DESCRIPTION]], table called Mapping op Values to Data Schemas.

Creating a new Protocol Binding Template Subspecification

When creating a new protocol binding template subspecification, e.g. based on a new communication protocol, the proposed document should enable implementations of this binding in an interoperable way for Consumer and Producer implementations. More specifically, each Binding Template Subspecification MUST specify the following:

• URI Scheme: For identification of the used protocol, a standardized URI scheme [[RFC3986]] value MUST be declared in the form of a string. This URI Scheme is used in TDs at top level base or in the href term of the forms container. These can be officially registered ones at IANA [[iana-uri-schemes]] (e.g. "https://", "coap://") or they can be declared in the protocol subspecification (e.g. "mqtt://", "modbus+tcp://"). How the full URI can be constructed for different affordances (or resources) MUST be specified as well.
• @context Usage and Ontology: A vocabulary that allows adding protocol options to a Thing Description forms SHOULD be provided to allow semantic annotations of the operations with protocol specific information. The prefix and IRI to be used in the @context in order to link to the vocabulary of the protocol SHOULD be also provided. The prefix SHOULD use the v suffix notation in order to avoid confusion with the URI scheme of the protocol (e.g. htv for HTTP and mqv for MQTT).
• Mapping to WoT Operations: Most protocols have a set of methods or verbs that adds a meaning to the messages of the protocol. A protocol binding template MUST be able to map WoT operation types (readproperty, invokeaction, etc.) to concrete protocol message types or methods. When specifying the mapping, the mapping SHOULD be bidirectional, i.e. it should be clear how to do a readproperty operation with the given protocol and how an existing implementation's endpoints can be mapped to a WoT operation should be also clear.
• JSON Schema: A JSON Schema to validate the forms of a TD using the Protocol Binding SHOULD be provided. This allows validation of the URI scheme and the vocabulary terms. The JSON Schema instance SHOULD follow the template provided in the Binding Templates GitHub Repository.
• Specification: The official specification document of the protocol SHOULD be provided. This SHOULD be a static version, i.e. the exact document used during the writing of the binding that is guaranteed to not change. If this is not possible, the specification should be marked with a date of access. When the specification is not publicly available and cannot be linked with a static version, an editor's note should be provided in the introduction, explaining how to get access to the specification.

A template is also provided for new protocol binding template specifications at the GitHub Repository.

Introduction to Payload Binding Templates

[[WOT-THING-DESCRIPTION]] defines two mechanisms to describe how a payload of a message over any protocol can look like. Firstly, media types [[IANA-MEDIA-TYPES]] describe the serialization used for sending and receiving the data with a protocol. They are represented within the contentType in the Forms of a TD, which is mandatory for each Interaction Affordance. Secondly, it defines the Data Schema concept to describe the structure of the messages, which are used together with media types. The combination of the two allows any message to be described in a TD, allowing correct serialization and deserialization of the messages by the Thing and Consumers.

In the rest of this section at [[[#payload-bindings-contentType]]] and [[[#payload-bindings-dataschema]]], you can find examples of how payload bindings can look like. At [[[#payload-bindings-table]]] you can find the current payload binding templates and [[[#payload-bindings-creating]]] explains how new payload binding templates can be created.

                        {
                            "forms":[
                            {
                                "href": "http://example.com/properties/temperature",
                                "op": "readproperty",
                                "contentType": "application/json"
                            },
                            {
                                "href": "coap://example.com/properties/temperature",
                                "op": "readproperty",
                                "contentType": "text/plain;charset=utf-8"
                            }]
                        }
                    

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

                                        {
                                            "type": "object",
                                            "properties": {
                                                "level": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 255
                                                },
                                                "time": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 65535
                                                }
                                            }
                                        }
                                    

Overall, a payload binding template specifies the values and structure of certain vocabulary terms in a TD. The table below lists the vocabulary term, the class it belongs to and whether the subspecification is required to specify the values the term can take. In addition to these, additional vocabulary terms can be added and restrictions to Data Schema terms can be placed.

Existing Payload Binding Templates

Creating a new Payload Binding Template Subspecification

Each payload binding template subspecification, SHOULD contain the respective media type. Ideally this media type has been registered at the IANA registry [[IANA-MEDIA-TYPES]] with a corresponding mime type (e.g. application/json). If it is not registered, the binding document can propose a mime type. Additionally, how that media type is represented in a Data Schema SHOULD be demonstrated with examples. In all cases, the following information SHOULD be provided:

• Specification: The official specification document of the payload format SHOULD be provided. This SHOULD be a static version, i.e. the exact document used during the writing of the binding that is guaranteed to not change. If this is not possible, the specification should be marked with a date of access. When the specification is not publicly available and cannot be linked with a static version, an editor's note should be provided in the introduction, explaining how to get access to the specification.

Introduction to Platform Binding Templates

There are already various IoT platforms on the market that allows exposing physical and virtual Things to the Internet. These platforms generally require a certain use of a protocol and payload. Thus, they can be seen as a combination of the and . In these cases, the use of protocol and payload bindings needs to be supported with how they are related to each other in the specific platform.

For example, Things of a certain platform can require the usage of HTTP and Websockets together with certain JSON payload structures. Thus, Platform Binding subspecifications provide Thing Models and examples of TDs that allow to semantically group multiple binding templates. This allows creation of TDs for these platforms in a consistent manner and makes it easier to develop Consumers for them.

Since Platform Binding Templates combine the usage of protocol and payload binding templates, the vocabulary terms and values they can specify are the combination of vocabulary terms in [[[#table-protocol-terms]]] and [[[#table-payload-terms]]]. Similarly, a Platform Binding subspecification SHOULD NOT introduce new protocol binding templates or media types inside its own document. If a Platform Binding subspecification requires the usage of protocol or media type, corresponding protocol or payload binding templates MUST be created first.

Existing Platform Binding Templates

The table below summarizes the currently specified platform binding template subspecifications.

Creating a new Platform Binding Template Subspecification

Depending on the platform and the variety of devices it proposes, each platform binding template subspecification will be structured differently. When the platforms offer a reasonable set of device types, a Thing Model for each device type SHOULD be provided. In other cases, possible devices SHOULD be generalized by providing a set of example Thing Models or TDs. In all cases, the following information SHOULD be provided:

• Protocol: The protocol used by the platform SHOULD be specified and linked to a protocol binding template subspecification when a corresponding one exists.
• Media Type: The media type used by the platform SHOULD be specified and linked to a payload binding template subspecification when a corresponding one exists.
• API Documentation: A static link pointing to the used API Documentation or Specification of the platform SHOULD be provided. When the documentation is not publicly available and cannot be included in a static version in the respective folder, an editor's note should be provided in the introduction, explaining how to get access to the documentation.