Abstract

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.

Introduction

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 fit to the purposes of WoT bindings.

This enables a binding to be written by people with a good understanding of the binding, who are not necessarily participants of the WoT Working Group, such as other organizations 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.

Terminology

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. is defined in Section 3 of the WoT Architecture specification [[WOT-ARCHITECTURE]].

In addition, this specification introduces further definitions below. These terms sometimes don't use the term WoT. Please use the "WoT" prefix outside of the context of Web of Things.

Binding
A human-readable document that gives guidance on how to describe a specific IoT protocol, data format or IoT platform in the context of WoT. This is also the registry entry. See registry entry for more information.
Binding Instance
A form element in a TD or TM that contains the concrete mapping of the operation to a binding. Thus it is a machine-readable description of how to activate an affordance.
WoT Binding Registry
A W3C Registry Track document that contains the WoT Binding Registry Table, its requirements and possibly other information. See registry for more information on the definition.
WoT Binding Registry Table
A list of bindings that are usable in the context of WoT. See registry table for more information.
WoT Binding Registry Definition
A set of requirements that explain how the registry table is structured and maintained. See registry definition for more information.
Binding Implementation
One of the codebases that implements the binding to build the correct network messages
Execution of a Binding Instance
The request on the wire that is sent after parsing a TD's binding instance.
Binding Summary
A custodian-owned document that summarizes the binding with an abstract, examples, access/usage rights and possibly more. This is a supporting document for a binding entry.
JSON Schema for a Binding
A JSON Schema that allows validating the elements added by the Binding (registry entry). This is a supporting document for a binding entry.
JSON-LD Context for a Binding
A machine-readable JSON-LD document that defines all the terms to be used in a binding instance, which allows the terms to be dereferenced correctly by a JSON-LD parser. This is a supporting document for a binding entry.
Vocabulary in RDF for a Binding
A machine-readable RDF document that formally defines all the terms of the binding, which allow semantic processing of a TD using those terms. The scope of these documents is not limited to WoT. This is a supporting document for a binding entry.
Vocabulary Document for a Binding
A human-readable version of the vocabulary defined at Vocabulary in RDF for a Binding. This is a supporting document for a binding entry.
Custodian
See custodian.
Reviewer
A person who is an expert in the specification that the binding is targeting.
Dependency
An entry that is used or referenced to from another entry.
Dependent
An entry that uses or references another entry.

Registry Definition

This registry is currently not published as a W3C Registry yet, meaning it is not finalized and stable. Thus, we are 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.

Entry format

Each entry MUST contain the following information. All parts of the entry MUST not conflict with existing bindings.

Entry format information
Information Type Description
Name of the binding string Examples: HTTP Binding, CoAP Binding
Specification that the Binding Targets string followed by an anyURI 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)`
Binding ontology prefix string Examples: htv, modv, cov
Binding Identification in TD any type URI Scheme or other TD terms reserved for this binding.
Examples: "subprotocol":"sse", "href":"http://example.com", "contentType":"application/json"

Until a custodian review, no registration is needed. A full IANA registration is required for the final and stable version of the binding. The submitter SHOULD trigger the registration at IANA. If needed, the custodian MAY trigger the IANA registration. The submitter MAY do a provisional registration to simplify the process on the IANA side.

Supported TD version string or Array of string A binding SHOULD correspond to specific TD specification version(s).
Note: no uniqueness needed
Status enumeration of [Initial, Current, Superseded, Obsolete] One of Initial, Current, Superseded or Obsolete.
Summary Document anyURI Link to the summary document of a Binding.
Version string A string that identifies a specific version of this binding. Example: 1.0-2026-01-15. See Versioning for more information.

W.r.t. "Binding Identification in TD": These terms should be refined based on the additions/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.

Lifecycle

Each entry in the registry goes through a lifecycle managed by the Custodian. The state in the lifecycle can be seen in the registry itself, as well as the GitHub project that is used to track submissions and transition requests.

Technical submission mechanism

The mechanism is as follows:

  • We work with issues only. The information for the entry format is submitted as a list. This way, non-W3C members can submit a binding. Reviews from the custodian happen on the issue. The submitter is expected to answer until the custodian makes a PR to add the binding to the registry or change its status.
  • A purpose built GitHub project for tracking submissions is used. When a submission comes in form an issue, it is automatically added to column "Binding Submitted". When the custodian and reviewers start looking at it, it goes to the "Under Review" column. If the review is in favor, the custodian makes the PR to add it to the registry and the issue goes to column "Accepted". If the review is not in favor, it goes to the column "Rejected". All these changes are reflected as comments in the original issue.
  • If a new entry conflicts with another entry, the reviewer MUST mark the new submission accordingly. As two bindings that do the same are not allowed, either the old one MUST be deprecated or the new one MUST be rejected. See also point 13 under "Requirements on the Submitted Document".

Status

An entry can have the following status values: Initial -> Current -> Superseded or Obsolete

  • Initial: Document is correctly written but no implementation experience has been necessarily documented.
  • Current: Custodian recommends it for new implementations and it has enough implementation experience. While this is also called as stable, given that it can be superseded later, it is recommended to use the term current.
  • Superseded: A previously "current" entry that is now superseded with a newer one
  • Obsolete: Custodian does not recommend the usage of this binding

The diagram below represents the lifecycle sates and the possible transitions between them. Please refer to transitions for the requirements and process for each transitions.

Registry Entry Lifecycle Diagram
Registry Entry Lifecycle States

This is inspired by the TTWG Boilerplate.
Alternatives can be reconsidered if needed. Initial: provisional, draft, in development. Current: Final, Stable. Outdated: Old, Deprecated (not preferred since it is still usable), Previous, Obsolete. Also see https://www.w3.org/policies/process/#RecsObs

Versioning

Different bindings may share the same version string, but each version of a binding MUST be unique within that binding's history. The version string SHOULD contain a UTC-based date in ISO 8601 format in the form of YYYY-MM-DD. The content of a registry entry MAY not be updated for a given version. If anyone wants to submit a newer version of an entry, it MUST be a new submission. As indicated in transition to superseded and transition to obsolete, the newer versions results in state changes. Review of a new version of an existing binding SHOULD take the previous reviews into account.

Deletion and deprecation

No entry is ever deleted. Deprecated entries are moved to another table or are clearly marked deprecated, colored differently, and moved to the bottom.

Ownership

The registry is managed by a Custodian and submissions and transitions are reviewed by Reviewers.

Custodian

A change in the registry MUST be confirmed by the Custodian. The custodian of this registry is the WoT WG in the beginning. If the WoT WG no longer exists, the W3C Team or its delegated entity MUST be the Custodian. 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.

Submission Requirements

What does the binding have to contain to go into the table.

WoT operation

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.

ContentType

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.

TODO: We will need additional mechanisms (including vocabulary terms) to ensure that it is possible to use other media types.

Document Section

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 favored.

Copyright

The WoT binding document MAY follow another copyright than the W3C copyright. The submitter is free to choose based on the process they or their organization follows.

Open to read

The binding document linked in the registry entry SHOULD be open to read, use, and implement, but that is not required for the document to be added to the registry.

Reviewer Access

Reviewers MUST have access to the binding document and to the protocol or media type specification (what the binding specifies).

Summary Document

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:

  • Abstract - It MUST contain an abstract with the following information:
    • What is the content of the binding about, e.g., what is this protocol?
    • Who should use it?
    • For what purpose(s) should it be used, e.g., monitoring, process control? This SHOULD use terminology of the submitter, i.e., the custodian does not provide definitions for this.
  • Examples - It SHOULD contain examples (can be one) TDs or TMs demonstrating the use of the binding
  • It MUST contain Access/Usage restrictions about the binding, protocol, implementation, etc., using the terminology and/or documents of the submitter. A non-exhaustive list of examples of restrictions:
    • Reading the binding document
    • Reading the protocol specification
    • Implementing a non-commercial device/Thing
    • Implementing a non-commercial Consumer application/driver
    • Conditions for commercial use, e.g., building a commercial product with the binding
    • Making a statement about your product's supporting that binding
  • If the entry depends on another one, it MUST specify the exact version of the dependency upon which it depends at the time of submission.
  • The availability of the machine-readable documents MUST be indicated in the summary document using the submission mechanism. Also see Req-Docs.
  • The previous version of the summary document MUST be listed as a link.
  • If the chronological ordering of the entries is not clear from the version string, the summary document MUST explain the ordering mechanism.

Transitions

Every transition including the initial submission is triggered by an issue, which can be made by the submitter, the custodian or anyone who creates an issue using the correct template. For each transition - defined in lifecycle status - the following sections explain the requirements and rules that need to be followed by the submitter, custodian and reviewers.

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.

Transition to Initial

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 and . 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".

The custodian MUST assign at least one reviewer who is a WoT expert for an initial submission.

Transition from Initial to Current

  • The transition to the current state MUST be made using the corresponding issue template and conform to the requirements defined in the template.
  • The transition MUST be reviewed from the protocol specification and WoT point of views and result in two separate review documents.
  • The custodian SHOULD assign at least two reviewers, one of whom is an expert in the binding's target specification and another who is a WoT expert. Thus, it is possible that the same person can be both reviewers if they are experts in both the binding's target specification and WoT. Nevertheless, two separate reviews need to be done as explained in the point above.
  • Starting from the initial submission, each binding MUST demonstrate a certain level of concrete development maturity. This process involves real-world testing, which can take place in Plugfests, independent testing events, or even informal collaboration between developers. These testing events do not have to be organized by W3C and can be conducted remotely, including over VPN. The goal is to demonstrate that the binding correctly maps protocol operations and is well understood by at least two parties.
  • At each testing event, every operation defined in the binding MUST be validated automatically (e.g., scripts, test suites, etc.). The results MUST be published in a dedicated document (README, or other human-readable documents) called Test Report.
  • Test Report
    • A Test Report MUST contain information on the testing environment.
    • A Test Report MUST provide an example of the logical process (not necessarily code) about how a TD can be processed to establish a communication between consumer and exposer.
    • A Test Report MUST contain information about the scenario that was tested, e.g. controlling the room temperature by measuring temperature and adjusting the heater.
    • A Test Report MUST explain where discussions on implementation experience should be collected.
    • A Test Report SHOULD provide the history of all the past testing events (or explain how to retrieve the history of the results gathered during those events).
    • A Test Report SHOULD contain a reference to the implementations of Consumers or Exposers.
  • The Test Report MUST contain at least one implementation of a Consumer (capable of understanding and performing all the operations described in the binding) and one Exposer (capable of handling all the operations and features described in the binding and optionally be able to create a valid TD). Additional implementations can be added even after the transition to the Current.
  • The exact contents of the Test Report is not decided yet. See https://github.com/w3c/wot-binding-registry/issues/3
  • Test Reports and related resources SHOULD be published in a public git repository. The repository containing the test reports and related resources MUST be accessible to the reviewers and the custodian.
  • Collaboration between the custodian, reviewers, and submitters is highly encouraged, ideally through a Plugfest or another structured testing session where different implementations can be evaluated collectively.

Transition from Current to Superseded

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.

Transition from Current to Obsolete

An entry MAY be transitioned to Obsolete from Current if the 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.

Transition from Superseded to Obsolete

An entry MAY be transitioned to Obsolete from Superseded if the 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.

Transition from Initial to Superseded

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.

Transition from Initial to Obsolete

An entry MAY be transitioned to Obsolete from Initial if the 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.

Content

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. Each entry after the first version of the binding MUST contain a changelog in the entry itself.

  • Introduction
  • Binding Content:
  • Examples
  • Changelog

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). Thus, when writing a binding, it must be associated with one or more known TD specification versions.

Documents

The requirements for the machine-readable documents are as follows:

  • There MUST be a JSON Schema (version to be defined) that allows validating the elements added by the entry.
  • There SHOULD be a JSON-LD Context and an ontology for the registry entry. Note that, when converting the TD to an RDF format, the lack of JSON-LD Context will create an RDF representation that will cause issues in RDF triple stores.
  • There MAY be other documents which are helpful to implementers, such as code, diagrams, and/or standalone examples.
  • These documents MUST be available to the reviewer.
  • The reviewer MUST include these documents in their review.
  • All documents associated with the registry entry MUST have the same version string, i.e., the versions of all associated documents MUST be updated when there is a change to any of them.
  • The version MUST be a string that is visible in all the documents.

Conflict

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.

Redefinition

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.

Dependency

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.

Registry

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. It will be deleted once the first real entry is added. You can find the list of bindings that predate the registry mechanism at this Readme file.

Name Version Status Binding Document Link Ontology Prefix Identification in TD Supported TD version Summary Document
MyProtocol 1.0 Initial https://example.com myprot URI Scheme my.prot:// 1.0, 1.1 https://example.com/summary