Web of Things (WoT) Binding Templates

W3C Editor's Draft

More details about this document
This version:
https://w3c.github.io/wot-binding-templates/
Latest published version:
https://www.w3.org/TR/wot-binding-templates/
Latest editor's draft:
https://w3c.github.io/wot-binding-templates/
History:
https://www.w3.org/standards/history/wot-binding-templates
Editors:
Michael Koster (Invited Expert)
Ege Korkan (Siemens AG)
Feedback:
public-wot-wg@w3.org with subject line [wot-binding-templates] … message topic … (archives)
Contributors
In the GitHub repository
Repository
We are on GitHub
File a bug

Copyright © 2017-2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

W3C Web of Things enables applications to interact with and orchestrate connected Things at the 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, standards and platforms 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 affordances of the WoT Thing Description.

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.

This core specification document acts as a base and explains how other binding templates should be designed. Concrete binding templates are then provided in their respective documents, referred to as subspecifications, that are linked to from this document.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/wot-binding-templates/ for the Editor's draft.

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Editor's note: The W3C WoT WG is asking for feedback

Please contribute to this draft using the GitHub Issue feature of the WoT 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.

This document was published by the Web of Things Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

Binding Templates consist of multiple specifications, referred to as a subspecification in this document, that enable an application client (a WoT Consumer) to interact, using WoT Thing Description[WOT-THING-DESCRIPTION] (TD), with Things that exhibit diverse protocols, payload formats and their usage. These subspecifications are categorized into three:

1.1 Relationship Between Binding Template Documents

Each Binding Template Subspecification is an independent document that has a separate list of authors and publication date. This document, called the Binding Template Core Specification, explains the binding mechanism by giving requirements per respective binding category and links to the respective subspecification. These can be found in sections 4.1 Protocol Binding Templates, 4.2.1 Introduction to Payload Binding Templates and 4.3 Platform Binding Templates

Binding Templates Overview and the relationships between each document type
Figure 1 Binding Templates Overview and the Relationships between each Document Type

Each Protocol and Payload Binding Template is specified in a way that they stay independent from each other. This means that each document can be read independently from each other and can also develop independently. However, Platform Binding Templates are dependent on the Protocol and Payload Binding Templates, since a given platform uses different protocols and payload formats that need to be specified first in their respective binding templates and referred to within a Platform Binding Template.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. Terminology

This section is non-normative.

The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Protocol Binding, Binding Template, Servient, Vocabulary, WoT Interface, WoT Runtime, etc. is defined in Section 3 of the WoT Architecture specification [WOT-ARCHITECTURE].

In addition, this specification introduces the following definitions:

Binding Template Subspecification, subspecification
A binding template document that is published separately from this document (called the core document) that specifies a binding template for a protocol, payload format or platform. All binding template subspecifications respect the rules set in the Core Specification.
Binding Template Core Specification, Core Specification
This document. All binding template subspecifications respect the rules set in the Core Specification.

4. Binding Template Mechanisms

This section describes the mechanisms of binding templates for protocols, payload formats and platforms.

4.1 Protocol Binding Templates

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

Example 1: Binding example of a readproperty operation to HTTP 
{
    "href": "http://example.com/props/temperature",
    "op": "readproperty",
    "htv:methodName": "GET"
}
Example 2: Binding example of an readproperty operation to Modbus 
{
    "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.2 Existing Protocol Binding Templates

4.1.2 Existing Protocol Binding Templates

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

Abbreviation Name Link to Binding Template Link to Ontology
HTTP Hypertext Transfer Protocol Binding Template Ontology
CoAP Constrained Application Protocol Binding Template Not available
MQTT Message Queuing Telemetry Transport Binding Template Ontology
Modbus Modbus Binding Template Ontology

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

4.2 Payload Binding Templates

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

4.2.1.1 Content Types

Content type includes the media type and potential parameters for the media type and it enables proper processing of the serialized documents. This way, the messages can be exchanged in any format and allow the upper layers of an application to adapt to different formats. In some cases such as images, videos or any unstructured data, content type is enough to describe the payload but in cases like JSON ([RFC8259]) a Data Schema is usually provided, like explained in 4.2.1.2 Data Schemas.

For example, a number payload can be serialized as JSON or XML and be indicated in the contentType of the forms with application/json or application/xml, respectively. Further parametrization is possible via the plus (+) or the semicolon (;) notations.

In the example below, you can find the form elements with content types for JSON and plain text with additional parameters. In this specific case, the forms describe that reading this property with http or coap result in different content types. For structured media types, a Data Schema is generally provided in the affordance level as explained in 4.2.1.2 Data Schemas and in the Data Schema section of the TD specification. However, for unstructured data such as images and videos, a Data Schema is typically not available.

Example 3: JSON and CBOR media types in forms 
{
    "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"
    }]
}

Other content types can be also expressed in TDs. In the list below, examples of different content type variations can be found. These content types can replace the ones in Example 3.

  • Structured Content Types without Parametrization
  • Structured Content Types with Parametrization
    • application/senml+json: SenML Data serialized in JSON [RFC8259]
    • application/senml+xml: SenML Data serialized as XML
    • application/ocf+cbor: OCF payload serialized in CBOR
    • text/csv;charset=utf-8: CSV encoded in UTF-8 [RFC4180]
  • Unstructured Content Types
    • image/jpeg: JPEG image
    • video/mp4: MP4 Video
    • application/octet-stream: Generic binary stream
4.2.1.2 Data Schemas

Data Schema concept to describe the structure of the messages, which are used together with media types. Even though it is largely inspired by JSON Schema [json-schema], it can be used for describing other payload types such as [XML], string-encoded images, bit representations of integers, etc. Data Schema SHOULD be used in addition to the media types.

4.2.2 Existing Payload Binding Templates

The table below summarizes the currently specified payload binding templates.
Abbreviation Name Media Type Link
JSON JavaScript Object Notation application/json TODO
XML eXtensible Markup Language application/xml Link
text text text/plain TODO
Unstructured Data Unstructured Data various TODO

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

4.3 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 propose a certain API specification over a protocol and media type. Thus, they can be seen as a combination of the 4.1 Protocol Binding Templates and 4.2 Payload Binding Templates. Platform Binding subspecifications provide Thing Models and examples of TDs on how to integrate these platforms in to the W3C Web of Things.

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

Name Link
Philips Hue TODO
ECHONET TODO
OPC-UA TODO

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

5. Examples of Thing Descriptions with Binding Templates

This section is non-normative.

The following TD examples uses CoAP and MQTT Protocol Binding Templates. These TD Context Extensions assume that there is a CoAP and MQTT in RDF vocabulary similar to [HTTP-in-RDF10] that is accessible via the namespace http://www.example.org/coap-binding# and http://www.example.org/mqtt-binding#, respectively. The supplemented cov:methodName member instructs the Consumer which CoAP method has to be applied (e.g., GET for the CoAP Method Code 0.01, POST for the CoAP Method Code 0.02, or iPATCH for CoAP Method Code 0.07). The supplemented "mqv:controlPacketValue" member instructs the Consumer which MQTT command has to be applied (e.g., 8 for the subscribing and 10 for unsubscribing).

A TD with simple payload format and protocols can be seen below. Here each interaction affordance has one form with one protocol.

Example 4: TD with a Simple Payload 
{
"@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {
    "iot": "http://iotschema.org/",
    "cov": "http://www.example.org/coap-binding#",
    "mqv": "http://www.example.org/mqtt-binding#"
    }
],
"@type": [ "Thing", "iot:Light", "iot:LevelCapability", "iot:BinarySwitchCapability" ],
"base": "http://example.com",
"title": "Lamp",
"id": "urn:dev:ops:32473-WoTLamp-1234",
"securityDefinitions": {"basic_sc": {
    "scheme": "basic",
    "in": "header"
}},
"security": ["basic_sc"],
"properties": {
    "switchState": {
    "@type": ["iot:SwitchStatus", "iot:SwitchData"],
    "type": "boolean",
    "writeOnly": false,
    "readOnly": false,
    "observable": false,
    "forms": [
        {
        "href": "/example/light/currentswitch",
        "op": ["readproperty", "writeproperty"],
        "contentType": "application/json"
        }
    ]
    },
    "brightness": {
    "@type": ["iot:CurrentLevel", "iot:LevelData"],
    "type": "number",
    "writeOnly": false,
    "readOnly": false,
    "observable": false,
    "forms": [
        {
        "href": "coap://example.com/example/light/currentdimmer",
        "op": ["readproperty", "writeproperty"],
        "contentType": "application/json"
        }
    ]
    }
},
"actions": {
    "switchOn": {
    "@type": ["iot:SwitchOnAction"],
    "input":  {
        "type": "boolean",
        "const": true
    },
    "forms": [
        {
        "href": "/example/light/currentswitch",
        "op": ["invokeaction"],
        "contentType": "application/json"
        }
    ]
    },
    "switchOff": {
    "@type": ["iot:SwitchOff"],
    "input":  {
        "type": "boolean",
        "const": false
    },
    "forms": [
        {
        "href": "/example/light/currentswitch",
        "op": ["invokeaction"],
        "contentType": "application/json"
        }
    ]
    },
    "setBrightness": {
    "@type": ["iot:SetLevelAction"],
    "input":  {
        "@type": ["iot:LevelData"],
        "type": "number"
    },
    "forms": [
        {
        "href": "/example/light/currentdimmer",
        "op": ["invokeaction"],
        "contentType": "application/json"
        }
    ]
    }
}
}

Another version of the previous TD with complex payload and multiple protocol options is shown below. Notably, the brightness property can be read via HTTP, written to via CoAP and observed via MQTT.

Example 5: TD with protocol options and complex payload 
{
    "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {
        "iot": "http://iotschema.org/",
        "cov": "http://www.example.org/coap-binding#",
        "mqv": "http://www.example.org/mqtt-binding#"
    }
    ],
    "base": "http://example.com/",
    "@type": [ "Thing", "iot:Light", "iot:LevelCapability", "iot:BinarySwitch" ],
    "title": "Lamp",
    "id": "urn:dev:ops:32473-WoTLamp-1234",
    "securityDefinitions": {"basic_sc": {
    "scheme": "basic",
    "in": "header"
    }},
    "security": ["basic_sc"],
    "properties": {
        "switchState": {
            "@type": ["iot:SwitchStatus"],
            "type": "object",
            "properties": {
            "switch": {
                "@type": ["iot:SwitchData"],
                "type": "boolean"
            }
            },
            "writeOnly": false,
            "readOnly": false,
            "observable": true,
            "forms": [
            {
                "href": "/example/light/currentswitch",
                "contentType": "application/json",
                "op": ["readproperty"],
                "htv:methodName": "GET"
            },
            {
                "href": "/example/light/currentswitch",
                "contentType": "application/json",
                "op": ["writeproperty"],
                "htv:methodName": "POST"
            },
            {
                "href": "mqtt://example.com/example/light/currentswitch",
                "op": ["observeproperty"],
                "mqv:controlPacketValue": "SUBSCRIBE"
            }
            ]
        },
        "brightness": {
            "@type": ["iot:CurrentLevel"],
            "type": "object",
            "properties": {
            "brightness": {
                "@type": ["iot:LevelData" ],
                "type": "integer",
                "minimum": 0,
                "maximum": 255
            }
            },
            "writeOnly": false,
            "readOnly": false,
            "observable": true,
            "forms": [
            {
                "href": "coap://example.com/example/light/currentdimmer",
                "contentType": "application/json",
                "op": ["readproperty"],
                "cov:methodName": "GET"
            },
            {
                "href": "/example/light/currentdimmer",
                "contentType": "application/json",
                "op": ["writeproperty"],
                "htv:methodName": "POST"
            },
            {
                "href": "mqtt://example.com/example/light/currentdimmer",
                "op": ["observeproperty"],
                "mqv:controlPacketValue": "SUBSCRIBE"
            }
            ]
        },
        "transitionTime": {
            "@type": ["iot:TransitionTime"],
            "type": "object",
            "properties": {
            "transitionTime": {
                "@type": ["iot:TransitionTimeData" ],
                "type": "integer",
                "minimum": 0,
                "maximum": 255
            }
            },
            "writeOnly": false,
            "readOnly": false,
            "observable": false,
            "forms": [
            {
                "href": "/example/light/transitiontime",
                "contentType": "application/json",
                "op": ["readproperty"],
                "htv:methodName": "GET"
            },
            {
                "href": "/example/light/transitiontime",
                "contentType": "application/json",
                "op": ["writeproperty"],
                "htv:methodName": "POST"
            }
            ]
        }
    },
    "actions": {
        "switchOn": {
            "@type": ["iot:SwitchOnAction"],
            "input":  {
            "type": "boolean",
            "const": true
            },
            "forms": [
            {
                "href": "/example/light/currentswitch",
                "contentType": "application/json",
                "op": ["invokeaction"],
                "htv:methodName": "POST"
            }
            ]
        },
        "switchOff": {
            "@type": ["iot:SwitchOffAction"],
            "input": {
            "type": "boolean",
            "const": false
            },
            "forms": [
            {
                "href": "/example/light/currentswitch",
                "contentType": "application/json",
                "op": ["invokeaction"],
                "htv:methodName": "POST"
            }
            ]
        },
        "setBrightness": {
            "title": "Set Brightness Level",
            "@type": ["iot:SetLevelAction"],
            "input": {
            "type": "object",
            "properties": {
                "brightness": {
                "@type": ["iot:LevelData"],
                "type": "integer",
                "minimum": 0,
                "maximum": 255
                }
                },
                "transitionTime": {
                "@type": ["iot:TransitionTimeData"],
                "type": "integer",
                "minimum": 0,
                "maximum": 65535
                }
            },
            "forms": [
            {
                "href": "/example/light/",
                "contentType": "application/json",
                "op": ["invokeaction"],
                "htv:methodName": "POST"
            }
            ]
        }
    }
}

6. Security and Privacy Considerations

Editor's note

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.

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

B. Temporary Sections

Editor's note

The below chapters are copied from other places in this document. They require discussion on where to place them, i.e. either here or another document of the working group, or to be completely removed.

B.1 Forms Element

The form elements contain the URI [RFC3986] pointing to an instance of the interaction and descriptions of the protocol settings and options expected to be used when between the Consumer and the Thing for the interaction.

B.1.1 Protocol Methods and Options

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:

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

B.2 subprotocol Vocabulary

The subprotocol field is defined in [WOT-THING-DESCRIPTION].

Currently, the supported values are longpoll, websub and sse defined for HTTP. Subprotocols can be used for asynchronous event delivery or observing Properties.

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]

B.3 Interaction Affordances

This section is non-normative.

This section describes unique aspects of protocol bindings for the three WoT Interaction Affordances.

B.3.1 Bindings for Properties

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

The abstract operations exposed for the Property Interaction are readproperty, writeproperty, observeproperty and unobserveproperty. These are mapped by using form operations that describe how the abstract operation is performed, resulting in a semantic interpretation similar to HTML form submission.

Additionally, the abstract operations exposed for multiple Property Interactions are readallproperties, writeallproperties, readmultipleproperties and writemultipleproperties.

Example 7: Example use of form operation for Property 
{
    "op": "writeproperty",
    "href": "/example/level",
    "htv:methodName": "POST"
}

The form element in the example above conveys the statement: "To do a writeproperty of the subject Property (context of the form), perform an HTTP 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 op=observeproperty in the form. The observe form may also specify header options to use, as specified in Observing in CoAP[RFC7641]for example setting the CoAP Observe option to 0 in the header, starts observation.

B.3.2 Bindings for Actions

This section is non-normative.

This section describes unique aspects of protocol bindings for Actions.

The abstract operation on Actions is invokeaction. In the same way that the abstract operations on Properties are mapped using form operation types, the abstract operation of Actions is also mapped.

Example 8: Example use of form operation for Action 
{
    "op": "invokeaction",
    "href": "/example/levelaction",
    "http:methodName": "POST"
}

The form element in the example above conveys the statement: "To do an invokeaction of the subject Action (context of the form), perform a POST on the resource at the target URI /example/levelaction."

B.3.3 Bindings for Events

This section is non-normative.

This section describes unique aspects of protocol bindings for WoT Event Interaction Affordances.

The abstract operations on Events are subscribeevent and unsubscribeevent. The subscribeevent operation may directly enable event instance delivery from the pre-defined URI to observable resources or pubsub topics encoded in URIs. Alternatively, it may return a location or resource URI from which event instance may be obtained, either by observation or some other mechanism, depending on the transfer protocol.

Usually, the unsubscribeevent only occurs when the transfer protocol has no implicit unsubscribe operation such as closing the connection. Examples are Webhooks that require particular unsubscribe requests.

If the binding offers an observable Event resource from which events are obtained, there will be a form which describes the required transfer layer operation, for example CoAP Observe or HTTP Long Polling.

Example 9: Example use of form operation for Events 
{
    "op": "subscribeevent",
    "href": "mqtt://wot.example.com/levelevent",
    "mqv:controlPacketValue": "SUBSCRIBE"
}

The form element in the example above conveys the statement: "To do an subscribeevent of the subject Event (context of the form), perform an MQTT SUBSCRIBE on the topic /levelevent on the broker at wot.example.com using the default MQTT port."

B.4 Data Schema

A data schema describes the payload structure and included data items that are passed between the Consumer and the Thing during interactions.

B.4.1 Payload Structure

Payload Structure is determined by DataSchema elements of a Thing Description. DataSchema elements should be used by an instance of a PropertyAffordance, input/output of ActionAffordance, data/subscription/cancellation of an EventAffordance or by a uriVariable of the InteractionAffordance. As indicated in the [WOT-THING-DESCRIPTION], DataSchema Vocabulary is a subset of JSON Schema [json-schema]

In the case of Action Affordances, the additional keywords input and output are used to provide two different schemas when data might be exchanged in both directions, such as in the case of invoking an Action Affordance with input parameters and receiving status information.

In the case of Event Affordances, the additional keywords data, subscription and cancellation are used to describe the payload when the event data is delivered by the Exposed Thing, the payload needed to subscribe to the event and the payload needed to cancel receiving event data from the Exposed Thing, respectively.

In addition to the example pattern in [WOT-THING-DESCRIPTION] of an object with name/value constructs or simple arrays, Protocol Bindings for existing standards may require nested arrays and objects, and some constant values to be specified.

Below are examples of different payloads and their corresponding DataSchema.

For example, a simple payload structure may use a map:

Example 10: Simple JSON Object Payload 
{
"level": 50,
"time": 10
}
Example 11: DataSchema for Simple JSON Object Payload 
{
    "type": "object",
    "properties": {
        "level": {
            "@type": ["iot:LevelData"],
            "type": "integer",
            "minimum": 0,
            "maximum": 255
        },
        "time": {
            "@type": ["iot:TransitionTimeData"],
            "type": "integer",
            "minimum": 0,
            "maximum": 65535
        }
    }
}

SenML [RFC8428] might use the following construct:

Example 12: SenML Example 
[
    {
    "bn": "/example/light/"
    },
    {
    "n": "level",
    "v": 50
    },
    {
    "n": "time",
    "v": 10
    }
]
Example 13: DataSchema for SenML Payload 
{
    "type": "array",
    "items": [
    {
        "type": "object",
        "properties": {
        "bn": {
            "type": "string",
            "const": "example/light"
        }
        }
    },
    {
        "type": "object",
        "properties": {
        "n": {
            "type": "string",
            "const": "level"
        },
        "v": {
            "@type": ["iot:LevelData"],
            "type": "integer",
            "minimum": 0,
            "maximum": 255
        }
        }
    },
    {
        "type": "object",
        "properties": {
        "n": {
            "type": "string",
            "const": "time"
        },
        "v": {
            "@type": ["iot:TransitionTimeData"],
            "type": "integer",
            "minimum": 0,
            "maximum": 65535
        }
        }
    }
    ]
}

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

Example 14: OCF Batch Example 
[
{
    "href": "/example/light/level",
    "rep": {
    "dimmingSetting": 50
    }
},
{
    "href": "/example/light/time",
    "rep": {
    "rampTime": 10
    }
}
]
Example 15: DataSchema for OCF Batch Payload 
{
"type": "array",
"items": [
    {
    "type": "object",
    "properties": {
        "href": {
        "type": "string",
        "const": "/example/light/level"
        },
        "rep": {
        "type": "object",
        "properties": {
            "dimmingSetting": {
            "@type": ["iot:LevelData"],
            "type": "integer",
            "minimum": 0,
            "maximum": 255
            }
        }
        }
    }
    },
    {
    "type": "object",
    "properties": {
        "href": {
        "type": "string",
        "const": "/example/light/time"
        },
        "rep": {
        "type": "object",
        "properties": {
            "rampTime": {
            "@type": ["iot:TransitionTimeData"],
            "type":"integer",
            "minimum": 0,
            "maximum": 65535
            }
        }
        }
    }
    }
]
}

And an IPSO Smart Object on LWM2M [LWM2M] might look like the following:

Example 16: IPSO/LWM2M Example 
{
"bn": "/3001/0/",
"e": [
    {
    "n": "5044",
    "v": 0.5
    },
    {
    "n": "5002",
    "v": 10.0
    }
]
}
Example 17: DataSchema for IPSO/LWM2M Payload 
{
"type": "object",
"properties": {
    "bn": {
    "type": "string",
    "const": "/3001/0/"
    },
    "e": {
    "type": "array",
    "items": [
        {
        "type": "object",
        "properties": {
            "n": {
            "type": "string",
            "const": "5044"
            },
            "v": {
            "@type": ["iot:LevelData"],
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0
            }
        }
        },
        {
        "type": "object",
        "Properties": {
            "n": {
            "type": "string",
            "const": "5002"
            },
            "v": {
            "@type": ["iot:TransitionTimeData"],
            "type": "number",
            "minimum": 0.0,
            "maximum": 6553.5
            }
        }
        }
    ]
    }
}
}

B.4.2 Data Types and value constraints

Note that in Example 7 above, the values are floating point (double) while the other examples have integer values. 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. This means that a Consumer sending the payload of the Example 7 should use floating points in the payload.

C. References

C.1 Normative references

[eventsource]
Server-Sent Events. Ian Hickson. W3C. 28 January 2021. W3C Recommendation. URL: https://www.w3.org/TR/eventsource/
[IANA-MEDIA-TYPES]
Media Types. IANA. URL: https://www.iana.org/assignments/media-types/
[iana-uri-schemes]
Uniform Resource Identifier (URI) Schemes. IANA. 21 July 2021. URL: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
[iana-web-socket-registry]
IANA Registry for Websocket Subprotocols. IANA. 24 May 2019. URL: https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name
[json-schema]
JSON Schema: A Media Type for Describing JSON Documents. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 8 December 2020. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema
[LWM2M]
Lightweight M2M. Open Mobility Alliance. URL: https://www.omaspecworks.org/what-is-oma-specworks/iot/lightweight-m2m-lwm2m/
[OCF]
OCF Specification. Open Connectivity Foundation. Last accessed: February 2020. URL: https://openconnectivity.org/developer/specifications/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC4180]
Common Format and MIME Type for Comma-Separated Values (CSV) Files. Y. Shafranovich. IETF. October 2005. Informational. URL: https://www.rfc-editor.org/rfc/rfc4180
[RFC5364]
Extensible Markup Language (XML) Format Extension for Representing Copy Control Attributes in Resource Lists. M. Garcia-Martin; G. Camarillo. IETF. October 2008. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5364
[RFC6741]
Identifier-Locator Network Protocol (ILNP) Engineering Considerations. RJ Atkinson; SN Bhatti. IETF. November 2012. Experimental. URL: https://www.rfc-editor.org/rfc/rfc6741
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[RFC8428]
Sensor Measurement Lists (SenML). C. Jennings; Z. Shelby; J. Arkko; A. Keranen; C. Bormann. IETF. August 2018. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8428
[RFC8949]
Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. December 2020. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8949
[WebSub]
WebSub. Julien Genestoux; Aaron Parecki. W3C. 23 January 2018. W3C Recommendation. URL: https://www.w3.org/TR/websub/
[WOT-THING-DESCRIPTION]
Web of Things (WoT) Thing Description. Sebastian Käbisch; Takuki Kamiya; Michael McCool; Victor Charpenay; Matthias Kovatsch. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-thing-description/
[XML]
Extensible Markup Language (XML) 1.0 (Fifth Edition). Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau et al. W3C. 26 November 2008. W3C Recommendation. URL: https://www.w3.org/TR/xml/

C.2 Informative references

[HTTP-in-RDF10]
HTTP Vocabulary in RDF 1.0. Johannes Koch; Carlos A. Velasco; Philip Ackermann. W3C. 2 February 2017. W3C Working Group Note. URL: https://www.w3.org/TR/HTTP-in-RDF10/
[MQTT]
MQTT Version 5.0. Andrew Banks; Ed Briggs; Ken Borgendale; Rahul Gupta. MQTT. 07 March 2019. URL: https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html
[RFC7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC7252]
The Constrained Application Protocol (CoAP). Z. Shelby; K. Hartke; C. Bormann. IETF. June 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7252
[RFC7641]
Observing Resources in the Constrained Application Protocol (CoAP). K. Hartke. IETF. September 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7641
[WOT-ARCHITECTURE]
Web of Things (WoT) Architecture. Matthias Kovatsch; Ryuichi Matsukura; Michael Lagally; Toru Kawaguchi; Kunihiko Toumura; Kazuo Kajimoto. W3C. 9 April 2020. W3C Recommendation. URL: https://www.w3.org/TR/wot-architecture/