Web of Things (WoT) 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.

{
    "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
}

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 4.1.1 4.1.2 Existing Protocol Binding Templates

The table below summarizes the currently specified protocols in their respective 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.
• 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.

[ WOT-THING-DESCRIPTION ] defines two mechanisms to describe how a payload of protocols a message over any protocol can be described in TDs using two mechanisms: Media Types: Media Types look like. Firstly, media types [ IANA-MEDIA-TYPES ] describe the encoding serialization used for sending and receiving the data with a protocol. They are represented with within the contentType in the Forms of a TD, which is mandatory for each Interaction Affordance. In some cases such as images, videos or any unstructured data, they are enough Secondly, it defines the Data Schema concept to describe the payload. Correct indication structure of Media 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 4.2.1.1 Content Types and 4.2.1.2 Data Schemas , you can find examples of how payload bindings can look like. At 4.2.2 Existing Payload Binding Templates you can find the current payload binding templates and 4.2.3 Creating a new Payload Binding Template Subspecification 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
        }
    }
}

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.

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.

Protocols may have defined sub-protocols 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 subprotocol item may be defined 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"
}