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 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 establishes 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 developers.
The custodian of this registry is the Web of Things Working Group (WoT WG). If the WoT WG no longer exists, the W3C Team or its delegated entity MUST be the Custodian and this paragraph MUST be updated. For example, a dedicated W3C community group can be created to maintain the registry. This way, the registry can be maintained for a long period.
The Web of Things (WoT) has the goal of improving interoperability in IoT and enabling the integration of various IoT ecosystems and communities. While the [[WOT-THING-DESCRIPTION11]] defines the abstract operations and interaction affordances, bindings map these to concrete network messages. Thus, thanks to bindings, the W3C Web of Things support multiple protocols and media types in a descriptive approach by adding further information to Thing Descriptions.
As the number of such protocols and media types is vast and tends to change over time, this document defines a flexible mechanism called a Binding Registry. This document relies on the registry track mechanism of the W3C Process and extends it to be specific and suited to the purposes of WoT bindings.
First, the registry mechanism enables a binding to be written by people and organizations with a good understanding of the specification the binding is based on. These people and organizations do not necessarily need to be participants of the WoT Working Group, such as others developing a standard that can be used with WoT. This also allows the WoT Working Group to focus on the core specifications and engage other communities at the same time.
Second, the registry mechanism allows the bindings to be maintained and evolve over time without going through the publication process of a W3C Recommendation. As long as the rules in the registry definition are followed, the registry can be updated via transition requests and new submissions.
This document serves three purposes. First, it lets implementers find the list of current bindings that they can use to implement their Things and Consumers. Each binding is a row in the Registry Table in Section [[[#registry]]] and is called a registry entry. Second, Section [[[#entry-format]]] helps implementers understand what each column of the registry table means. Third, it defines the rules that govern the registry, which are explained in Section [[[#registry-definition]]]. These define who manages the registry, how to submit new entries, how to update existing entries, and how to review transitions, which are important for the long-term maintenance of the registry and the quality of the entries.
The fundamental WoT terminology such as Thing, Consumer, Thing Description (TD), Interaction Model, Interaction Affordance, Property, Action, Event, Data Schema, Content Type, Protocol Binding, Binding Template, Servient, Vocabulary, WoT Interface, WoT Runtime, IoT Platform, etc. are defined in Section 3 of the WoT Architecture specification [[WOT-ARCHITECTURE]].
In addition, this specification introduces further definitions below. These terms do not always use the term WoT. Please use the "WoT" prefix outside of the context of Web of Things.
This registry is currently not published as a W3C Registry yet, meaning it is not finalized and stable.
Thus, it is currently in a pilot phase where only a small number of bindings written by the WoT Working Group
are included. They are still managed using the rules explained in this section but will not leave the
Initial state of the lifecycle. After the pilot phase, the registry will be opened to external
submissions and the process defined here will be used to manage submissions and entries. This pilot exists to
test the process and the rules defined in this section.
A set of rules extending the Registry Definitions from the W3C Process Document can be found below and is structured as follows.
Additionally, lifecycle of a registry entry and the transitions are explained in the Lifecycle section.
Each registry entry is a row in the registry table, which contains registration-related information about the binding. This section provides the meaning of each row in the registry table and the requirements related to them. Each registry entry MUST contain the information found in [[[#entry-format-definitions]]]. The information in the registry table is not the same as the information in the binding document, but it is related to it. For example, the registry table contains the vocabulary prefix of the binding, but it does not contain all the information in the binding document, such as the vocabulary terms. The requirements on the content of the binding document are defined in the [[[#req-content]]] section.
In general, each registry entry is immutable and unique in the registry, and the information in the registry table is used to identify and differentiate the entries by the readers as well as implementations. Thus, the uniqueness column indicates whether that entry characteristic is required to have a unique value across the registry or not. The entry values of rows in [[[#entry-format-definitions]]] where the uniqueness column has the value "Required" MUST not conflict with the values of other entries in the registry table. For example, the name of the binding is unique for the readers to associate with it, and the vocabulary term prefix is required to be unique so that implementations can use it to dereference the terms in the binding instance. A special case is the version field. Different bindings may share the same version string, but each version of a binding MUST be unique within that binding's history. This is because the version string is used to differentiate different versions of the same binding, but it is not used to differentiate different bindings.
| Characteristic | Type | Uniqueness | Description |
|---|---|---|---|
| Name of the Binding |
string
|
Required | Human-readable name for the binding. Examples: HTTP Binding, CoAP Binding |
| Version |
string
|
Required within one Binding's lifecycle |
A string that identifies a specific version of this binding. Example: 1.0-2026-01-15.
The version string SHOULD contain a UTC-based date in ISO 8601 format in the form of YYYY-MM-DD.
|
| Status |
enumeration of
[Initial, Current, Superseded, Obsolete]
|
Not required | Indicates the lifecycle status of the entry and changes via transitions defined in Lifecycle section. |
| Binding Document Link |
anyURI
|
Required |
Stable link whose content cannot change (e.g., a date, version number, etc.), which can be managed by
another entity than the custodian. Examples: https://www.w3.org/TR/wot/binding-templates/http-20240726/index.html
|
| Target Specification of the Binding |
string followed
by an anyURI
|
Required | The name and link of the specification that the binding is designed to target. Example: `MQTT 3.1.1 (https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html)` |
| Summary Document Link |
anyURI
|
Required | Link to the summary document of the Binding. |
| Vocabulary Term Prefix |
string
|
Required | Prefix used for vocabulary terms such as htv for HTTP and modv for Modbus |
| Binding Identification in TD | any type | Required |
URI Scheme or other TD terms for a Consumer to identify the binding. Examples: "subprotocol":"sse",
"href":"http://example.com",
"contentType":"application/json"
|
| Supported TD Versions |
Array of string
|
Not required |
The versions of TD Recommendations that the binding supports. The allowed values are reflected in the
submission templates. Example: ["1.0", "1.1"].
|
With respect to "Binding Identification in TD": These terms may be refined based on the changes to the TD
2.0 mechanism, e.g., introducing a protocol term or putting restrictions on URI scheme and
subprotocol combination, data mapping, etc. However, for TD 1.0 and 1.1 versions, these terms
are still valid and thus the mechanism must remain flexible enough to support them.
When a new entry is submitted to the registry or needs to transition to other states, it needs to follow certain requirements to be accepted. These requirements are defined in this section and are related to the content of the binding document and its supporting documents, as well as to the administrative aspects of the submission. Each transition also has specific requirements. All these requirements are defined to ensure the quality of the entries in the registry, the long-term maintenance of the registry and the ease of use for developers who want to use the bindings in the registry. The requirements are also defined to ensure that the registry can be maintained by the custodian and that the transitions can be reviewed by the reviewers in a consistent way.
The requirements are categorized based on the different aspects of the submission process.
If the submitter cannot guarantee the immutability of the binding content or the stability of the link
to the binding, they MUST send an email to https://lists.w3.org/Archives/Public/www-archive/
and attach the binding and supporting documents.
This way, if the submitter fails to keep the link stable, an archived version exists for the users.
Such bindings automatically become open to read.
In case a submitter guarantees the stability of the link but the link still becomes unavailable, the custodian MUST inform the submitter about the issue. If the submitter cannot fix the link within 30 days, the custodian SHOULD transition the entry to obsolete state.
Registry entries are expected to contain a human-readable document describing the binding. In order to ensure a certain level of consistency and to make it easier for developers to understand how the binding works and to implement it, the document is expected to contain specific sections. As protocol bindings and media type bindings are expected to have different content, the requirements are different for each of them. While the order of the sections is not strict, the required sections MUST be present in the document with the names defined in the respective types of bindings. This allows readers to easily find the required sections. The submitters are encouraged to look at the existing submissions.
A binding may not fit newer or older versions of a TD specification (e.g., readproperty can
become readprop, or a new operation can arrive).
Therefore, the binding document MUST specify the TD specification version(s) that the binding is designed
for and compatible with.
The required sections for the content of the protocol binding documents are as follows:
To help the readers, it is RECOMMENDED to include an introduction and examples of TDs with the binding. Additionally, the submitter SHOULD use the table template provided in the document for the form vocabulary definition.
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.
Extensions:
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.
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.
The required sections for the content of the media type binding documents are as follows:
This aspect will be defined in a future revision. Additional mechanisms (including vocabulary terms) will be required to support other media types.
The submitter MUST fill in the GitHub form provided by the custodian to generate a summary document, which is hosted by the custodian together with the registry. This form contains the following:
The requirements for the machine-readable supporting documents are as follows:
Each entry in the registry goes through a lifecycle managed by the Custodian, which is reflected in the
Status field of the entry.
Additionally, a GitHub project is used to track
submissions and transition requests.
An entry can have the following status values: Initial -> Current ->
Superseded or Obsolete. These terms are defined below:
Initial: Document is correctly written but no implementation experience has necessarily
been documented.
Current: Custodian recommends it for new implementations and it has enough implementation
experience. While this is also called stable, given that it can be superseded later, it is
recommended to use the term current.
Superseded: An entry that previously had the status "initial" or "current"
is now superseded with a newer one.
Obsolete: An entry that previously had the status "initial", "current"
or "superseded" is now obsolete and the Custodian does not recommend the usage of this binding.
The diagram below represents the lifecycle of an entry and the possible transitions between them. Here, each box represents a status of an entry, and the arrows represent the possible transitions between them. The subsequent sections describe the requirements and process for each transition.
Please note these transitions do not allow an entry to be ever deleted. An entry can become obsolete or superseded by another one. If anyone wants to submit a newer version of an entry, it MUST be a new submission. As indicated in transition from initial to superseded and transition from current to superseded, the newer versions result in transitions.
Every transition including the initial submission is triggered by a GitHub issue, which can be made by the submitter of the initial version, the custodian or anyone who creates an issue using the correct template. All transitions MUST be applied or rejected by the Custodian. The issue submitter is expected to respond while the custodian prepares a Pull Request to apply the transition.
The issues created for transitions are automatically reflected in the GitHub project in their respective columns. When the custodian assigns a reviewer to the transition, it goes to the "Under Review" column. If the review is in favor of the transition, the issue goes to column "Accepted" and the Custodian makes the Pull Request to apply the transition and closes the issue. If the review is not in favor, it goes to the column "Rejected" and the Custodian closes the issue.
The diagram below represents the lifecycle of transitions.
For each transition, the following sections explain the requirements and rules that need to be followed by the submitter, custodian and reviewers. While some aspects of the transition process are common for all transitions, some other aspects are specific to each transition, e.g., the requirements on the test report for the transition to current, or the requirements on the comparison between the old and new versions for the transition to superseded. Thus, there are some common requirements defined in this section, and then there are specific requirements for each transition defined in their respective sections.
As a general rule, a transition MAY be triggered by the submitter, the custodian or anyone who creates an
issue using the correct template.
However, the custodian MUST notify the initial submitter and the organization related to the entry of any
transition request using the contact information provided in the submission issue.
In the case of no replies within 30 days from the initial submitter or the organization related to the
entry, the custodian MUST process the transition, consulting reviewers when necessary for the transition
in question.
The custodian MUST assign reviewers for the submission and transitions who are different from the initial
submitter and the organization related to the entry.
The custodian MUST wait 15 days after the end of the review process before making a decision on the
transition to allow for any further comments or discussions to take place.
The custodian MUST make a decision on the transition within 30 days after the end of the review process.
If there are other entries in the registry with Initial or Current status
targeting the same specification, the reviewers MUST take them into account.
For example, a newer version of the same binding would result in a transition to Superseded for
the older version, which should be used in the review.
While the custodian is tasked with assigning reviewers, the custodian MAY NOT be able to assign
reviewers.
As there are no guarantees that reviewers complete their reviews, the custodian MAY reassign reviewers if
necessary.
The submitter MUST use the correct transition issue template for each transition request and conform to the requirements defined in the template.
As two bindings that do the same thing are not allowed, either the old one MUST transition to superseded or obsolete, or the new initial submission MUST be rejected. 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 Current status.
Dependencies to other Bindings: It could be that a binding uses another binding. For example, a protocol can be built on top of another one, e.g. LWM2M and CoAP, or a binding can define a default content type, e.g., HTTP and JSON. This makes the lifecycle of both entries more complex and creates a dependency between the two entries in the registry. The following rules apply to these dependencies.
current state if the dependent needs to transition to the current
state.
initial state even if the dependency is not
in the registry.
The initial submission MUST be made using the corresponding issue template and conform to the requirements defined in the template. Initial entry MUST be a correct document which complies with the requirements in Binding Content and Supporting Documents. The submitter MAY do a provisional registration of the URI Scheme at IANA.
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 web pages SHOULD be favored.
The custodian MUST assign at least one reviewer who is a WoT expert for an initial submission.
The reviewer does not need to check whether the binding tries to map readproperty to a
non-existent HTTP method. A successful initial document triggers a "Call for Implementation".
If a new initial submission conflicts with another entry with status "initial" or "current", the reviewer MUST mark the new submission accordingly. Review of a new version of an existing binding SHOULD take the previous reviews into account.
The transition MUST be reviewed from the protocol specification point of view and the adherence to the W3C Web of Things Thing Description standard and result in two separate review documents.
Superseding a binding allows the custodian to recommend a newer version of a binding while still keeping
the older version available for reference.
When a new version of a binding is accepted as Current, the previous Current
version MUST be transitioned to Superseded.
No additional reviews are necessary as the reviewers of the new version would have already reviewed the
previous version as part of their review process.
While this transition happens automatically with a new binding transitioning to current,
this transition issue template MAY be used for triggering a transition additionally.
An entry MAY be transitioned to Obsolete from Current if that binding is
not recommended for use.
The transition to
the obsolete state from current MUST be made using
the
corresponding issue template
and conform to the requirements defined in the template.
An entry MAY be transitioned to Obsolete from Superseded if that binding
is not recommended for use anymore.
The transition
to the obsolete state from superseded MUST be made using
the
corresponding issue template
and conform to the requirements defined in the template.
An entry MAY be transitioned to Superseded from Initial if another entry will
continue development and maintenance.
While this transition happens automatically with a new binding transitioning to initial or current,
this transition issue template
MAY be used for triggering a transition additionally.
An entry MAY be transitioned to Obsolete from Initial if that binding is
not recommended for use or testing anymore.
The transition to the
obsolete state from initial MUST be made using
the
corresponding issue template
and conform to the requirements defined in the template.
The following table defines the WoT Binding Registry where each entry is a binding. Entries are ordered alphabetically according to their name.
The first entry is a placeholder example and will be removed upon the addition of the first substantive registry entry. You can find the list of bindings that predate the registry mechanism at this Readme file.
| Name of the Binding | Version | Status | Binding Document Link | Target Specification of the Binding | Summary Document Link | Vocabulary Term Prefix | Binding Identification in TD | Supported TD Versions |
|---|---|---|---|---|---|---|---|---|
| MyProtocol Binding | 1.0-2026-01-15 | Initial | https://example.com | MyProtocol 1.2 | https://example.com/summary | myprotv | URI Scheme my.prot:// |
["1.0", "1.1"] |