W3C Web of Things (WoT) 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. Through WoT Bindings, the abstract interactions can be bound to various network-level protocols, standards, and platforms for connected Things, which already have have millions of devices deployed in the field today. This is done through protocol-specific URI schemes, additional descriptive vocabularies, and examples that guide the implementors of WoT Things and Consumers alike.
This document defines a registry of WoT bindings that make it possible to have a record of the different bindings. Additionally, it sets the rules that govern this registry to guarantee a quality standard, long lifecycle and ease of use for the developers.
From the charter:
Support WoT Interoperability: The WG will improve out-of-the-box interoperability and enable the integration of WoT into other ecosystems and communities. Thus, the WG will define core binding and profiling mechanisms, and define additional profiles and bindings, as appropriate.
Our Story and Use Case:
The goal of the W3C Web of Things is to support multiple protocols via the bindings mechanism. There are domains like smart cities and infrastructure where multiple stakeholders bring different devices and systems with different protocols. This means existing systems should be made interoperable with a descriptive approach via Thing Descriptions.
It is unrealistic to incorporate a complete list of bindings into a REC document before its publication; thus, we need a more flexible mechanism.
The terms below sometimes use the word X as a placeholder for the concrete binding that is referred to.
[DP] I think we should not speak about "document" but rather about "registry". Also in the title.
A binding SHOULD be written by people with a good understanding of the protocol and media type (or similar), who are not necessarily the TD Editors. This includes people and organizations inside and outside of the WoT WG.
The binding registry MUST be a separate document but associated with a TD version.
Association of a binding with the TD specification (registry entry) SHOULD be confirmed by the WoT Working Group or its custodian. In other words, a person needs some permission and/or confirmation to authoritatively say that a given binding can be used with TD version X. The custodian of this registry is the WoT WG in the beginning.
The binding document (registry entry) CAN be hosted by another entity than the custodian.
A preliminary list of rules that is extending https://www.w3.org/2023/Process-20230612/#reg-def (needs more iteration):
[DP] I think we want to extend the list above with the additional sections below and point/link to it.
Each entry MUST contain this information, and all parts of the entry MUST not conflict with existing bindings.
Name of the binding
HTTP Binding
, CoAP Binding
Link to the binding document: Stable link whose content cannot change (e.g., a date, version number, etc.)
https://www.w3.org/TR/wot/binding-templates/http-20240726/index.html
Binding ontology prefix
htv
, modv
, cov
Binding Identification in TD: URI Scheme or other TD terms reserved for this binding.
"subprotocol":"sse"
, "href":"http://example.com"
, "contentType":"application/json"
href
, contentType
, subprotocol
, or connection information found in the root of the TD.protocol
term or putting restrictions on URI scheme and subprotocol
combination, data mapping, etc.Supported TD version (no uniqueness needed):
readproperty
can become readprop
, or a new operation can arrive). Thus, when writing a binding, it must be associated with one or more known TD specification versions.Status: One of Initial, Current, Superseded or Obsolete
Summary Document: Link to the summary document
Version: A unique string for that entry's history that denotes the version of the entry that is linked. The version string SHOULD contain a UTC-based date in ISO 8601 format in the form of YYYY-MM-DD
.
Technical submission mechanism. How does a binding get submitted?
Initial -> Current -> Superseded or Obsolete
What are the requirements for transitioning from one value to another? See the "Requirements on the Submitted Document" section as well.
Versioning of registry entries (see https://github.com/w3c/wot/tree/main/registry-analysis#versioning)
Deletion and deprecation (see https://github.com/w3c/wot/tree/main/registry-analysis#deletion-and-deprecation-of-registry-entries)
If the WoT WG no longer exists, the W3C Team or their delegated entity becomes the custodian. For example, a dedicated W3C community group can be created to maintain the registry.
Reviewer: If there is an expert of the binding entry's specification and a WoT expert within the custodian entity, they CAN do the review independently. If not, the custodian MUST choose an expert for that specification and a WoT expert who can be the same person.
What does the binding have to contain to go into the table
A binding that uses a protocol MUST map at least one WoT operation (op
keyword value such as readproperty
) to a protocol message and vice versa
A binding that uses a serialization format via the contentType
keyword MUST mention how the Data Schema terms should be used to describe the messages. This avoids submission of a binding like "XML Binding" that says "Use contentType:application/xml
and nothing more. That alone would not be enough to serialize correct messages based on the data schema.
Initial entry MUST be a correct document which complies with Req-content. The reviewer MUST NOT check whether the binding tries to map readproperty
to a non-existent HTTP method. A successful initial document triggers a "Call for Implementation".
Each versioned entry MUST contain a changelog in the entry itself.
The WoT binding MAY be just one section of the document. In that case, the "Link to the binding document" in the registry entry MUST point to the specific location. PDF or similar document types MAY be submitted if the "Link to the binding document" in the registry entry contains a text pointing to the section. However, HTML and Webpages SHOULD be favoured.
The WoT binding document DOES NOT have to follow the W3C copyright. The submitter is free to choose based on the process they or their organization follows.
The binding document linked in the registry entry SHOULD be open to read, use, and implement, but that is not required for the document be added to the registry.
Reviewer MUST have access to the binding document and to the protocol or media type specification (what the binding specifies)
The submitter MUST fill the GitHub form provided by the custodian to generate the summary document, which is hosted by the custodian together with the registry. This form contains the following:
Transition from "Initial" to "Current"
The binding MUST contain the following sections in the order presented below. The binding CAN contain other sections anywhere, including between the required ones. The submitters are encouraged to look at the existing submissions. There MUST be at least one operation mapped to a protocol message/vocabulary term. The submitter SHOULD use the table template provided in the document for the vocabulary.
The requirements for the machine-readable documents are as follows:
There SHOULD be a JSON-LD Context and an ontology for the entry. Note that the lack of JSON-LD Context creates an RDF representation that will probably cause issues in RDF databases.
There MAY be other documents which are helpful to implementers, such as code, diagrams, and/or standalone examples.
The binding entry SHOULD NOT conflict with other entries in the registry, such as its other versions or its dependents, by redefining the same concepts, such as redefining the URI Scheme, the vocabulary terms, or the default assignments. If a previously stable binding is being improved upon by the same organization, that previous binding MUST be deprecated once the new one reaches the stable status.
The namespace (prefix and its values) defined in a binding SHALL NOT be redefined or extended in any other binding, e.g., cov:method
values shall not be extended in LWM2M and cov:newTerm
shall not be added in LWM2M binding.
If parts of the entry require the existence of another binding, i.e., has dependencies, the dependency MUST first be submitted as a separate entry. For example, before LWM2M can be submitted, the CoAP Binding must exist.