Subprotocols

As defined in [[WOT-ARCHITECTURE]], a subprotocol is an extension mechanism to a protocol. A subprotocol can require a sequence of protocol messages or a specific structure of message payloads, which can have its own semantics within that subprotocol. 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. Correspondingly, subprotocols are linked to the protocol they are extending and should be understood together with the protocol indicated in href of the forms (or the base). For WebSockets, the IANA-registered Websocket Subprotocols [[iana-web-socket-registry]] may be used, for example. Subprotocols can be defined and explained as a part of a protocol or platform binding subspecification.

Terms Specified by Protocol Binding Templates

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). For instructions on how to create a vocabulary, please refer to our Vocabulary Creation Guide.
• 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.

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 [[[#payload-bindings-dataschema]]].

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 [[[#payload-bindings-dataschema]]] 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.

                    {
                        "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-payload-binding]]].

• Structured Content Types without Parametrization
  • application/json: JSON [[RFC8259]]
  • application/xml: XML [[RFC5364]]
  • application/cbor: CBOR [[RFC8949]]
  • text/csv: CSV [[RFC4180]]
• 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

Data Schemas

Data Schema, as explained in [[WOT-THING-DESCRIPTION]], describes 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.

Depending on the case, the structure of the messages can be anything from a simple number to arrays or objects with multiple levels of nesting. Existing IoT Platforms and Standards have certain payload formats with variations on how the data is structured. As explained in [[WOT-THING-DESCRIPTION]], Data Schema can be used in a TD in one of the following places:

• Property Affordances: Each property affordance can contain terms for Data Schema and describe the property values when read, observed or written to.
• Action Affordances: input and output vocabulary terms are used to provide two different schemas when data is exchanged in both directions, such as in the case of invoking an Action Affordance with input parameters and receiving status information.
• Event Affordances: data, dataResponse, subscription and cancellation are used to describe the payload when the event data is delivered by the Exposed Thing, the payload to reply with for event deliveries, the payload needed to subscribe to the event and the payload needed to cancel receiving event data from the Exposed Thing, respectively.
• URI Variables: In the Thing or Affordance level, uriVariables can describe the data that needs to be supplied inside the request URI as a string.

Below is an example of a simple JSON object payload with the corresponding Data Schema. Examples from various IoT Platforms and Standards can be found in [[[#sec-payload-examples]]].

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

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

Terms Specified by Payload Binding Templates

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.

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.