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

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.

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

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

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

When the media type is application/xml (or its binary representation application/exi ) and there is a Data Schema provided for the payload, the payloads are constrained by a XML Schema derived from the Data Schema. See XML Binding for how to derive a XML Schema from a Data Schema definition.

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

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:

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

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

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

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

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

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

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

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

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.