Orphaned Sections
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.
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.
Operation Types
Form Operation Types describe the intended semantics 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 op attribute of the form
indicates which form is which and allows the Consumer to select the correct
form for the operation required.
"op": "readproperty"
"op": "writeproperty"
The vocabulary in section 4 lists the recommended set of form operations, and the full TD examples in section 5 contain example uses of form operations types.
Content Types
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.
Protocol Methods and Options
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, platforms may use different methods for realizing a particular WoT Interaction Affordance. For example, POST may be used for writing a Property value in one platform, 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 [[HTTP-in-RDF10]] 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.
"htv:methodName": "GET"
"mqv:controlPacketValue": "SUBSCRIBE"
"cov:methodName": "GET"
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.
"htv:headers":
[
{
"htv:fieldName": "Accept",
"htv:fieldValue": "application/json"
},
{
"htv:fieldName": "Transfer-Encoding",
"htv:fieldValue": "chunked"
}
]
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"
}
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]]
Interaction Affordances
This section describes unique aspects of protocol bindings for the three WoT Interaction Affordances.
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.
{
"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.
Bindings for Actions
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.
{
"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."
Bindings for Events
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.
{
"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."
Data Schema
A data schema describes the payload structure and included data items that are passed between the Consumer and the Thing during interactions.
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:
{
"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
}
}
}
]
}
}
}
|
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.
