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

TODO

Use Case

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.

Terminology

The terms below sometimes use the word X as a placeholder for the concrete binding that is referred to.

WoT X 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 Bindings Registry
A W3C Registry Track document that contains the WoT Bindings Registry Table, its requirements and possibly other information. See registry for more information on the definition.
WoT Bindings Registry Table
A list of bindings that are usable in the context of WoT. See registry table for more information.
WoT Bindings Registry Definition
A set of requirements that explain how the registry table is structured and maintained. See registry definition for more information.
WoT X Binding Implementation
One of the codebases that implements the X 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.
WoT X 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.
WoT X Binding JSON Schema
A JSON Schema that allows validating the elements added by the WoT X Binding (registry entry). This is a supporting document for a binding entry.
WoT X Binding JSON-LD Context
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.
X Vocabulary in RDF
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.
X Vocabulary Document
A human-readable version of the vocabulary defined at X Vocabulary in RDF. 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.

Intro Section of the Document

[DP] I think we should not speak about "document" but rather about "registry". Also in the title.

Int-Exp

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.

  • Reasons Behind the Requirement:
    • Instead of WG learning each new protocol and media type, it is more efficient for people with a good understanding of the protocol or media type to write a binding
    • Engaging other communities
Int-Sep

The binding registry MUST be a separate document but associated with a TD version.

  • Reasons Behind the Requirement: It is easier to update in the long term.
Int-Asso

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.

  • Reasons Behind the Requirement: WoT WG is the manager of the registry.
Int-Oth

The binding document (registry entry) CAN be hosted by another entity than the custodian.

Content of Registry Definition

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.

Entry format

Each entry MUST contain this information, and all parts of the entry MUST not conflict with existing bindings.

Form-Name

Name of the binding

  • Examples: HTTP Binding, CoAP Binding
Form-Link

Link to the binding document: Stable link whose content cannot change (e.g., a date, version number, etc.)

  • Examples: https://www.w3.org/TR/wot/binding-templates/http-20240726/index.html
Form-Pref

Binding ontology prefix

  • Examples: htv, modv, cov
Form-Id

Binding Identification in TD: URI Scheme or other TD terms reserved for this binding.

  • Examples: "subprotocol":"sse", "href":"http://example.com", "contentType":"application/json"
  • In a TD, a binding SHOULD be identifiable by the terms in a form such as href, contentType, subprotocol, or connection information found in the root of the TD.
    • Reasons Behind the Requirement:
      • This avoids conflicts that are mentioned in the previous requirement
    • TODO: 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.
    • 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.
Form-TdVer

Supported TD version (no uniqueness needed):

  • A binding SHOULD correspond to specific TD specification version(s).
    • Reason Behind the Requirement: 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.
Form-Stat

Status: One of Initial, Current, Superseded or Obsolete

Form-Summ

Summary Document: Link to the summary document

Form-Ver

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.

Lifecycle

Life-Subm

Technical submission mechanism. How does a binding get submitted?

  • 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 favour, the custodian makes the PR to add it to the registry and the issue goes to column "Accepted". If the review is not in favour, 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".
Life-Stat

Initial -> Current -> Superseded or Obsolete

  • Definitions:
    • 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
    • Superseded: A previously "current" entry that is now superseded with a newer one
    • Obsolete: Custodian does not recommend the usage of this binding
  • This is inspired by the TTWG Boilerplate
  • Alternatives that can be reconsidered if needed:
Life-Tran

What are the requirements for transitioning from one value to another? See the "Requirements on the Submitted Document" section as well.

Life-Ver

Versioning of registry entries (see https://github.com/w3c/wot/tree/main/registry-analysis#versioning)

  • Ege: We do not allow updates to a registry document's content. A new version of a binding is a resubmission and optional deprecation of the old one. However, new features need new implementations, so it is not a completely new registration.
Life-DelDep

Deletion and deprecation (see https://github.com/w3c/wot/tree/main/registry-analysis#deletion-and-deprecation-of-registry-entries)

  • 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

Own-Cust

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.

  • Reasons Behind the Requirement: Maintaining the registry without the WoT WG should be possible.
Own-Rev

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.

Requirements on the Submitted Document

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

Req-opmap

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

Req-contmap

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.
Req-TranInit

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

Req-Changelog

Each versioned entry MUST contain a changelog in the entry itself.

Req-DocSec

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.

Req-Copy

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.

Req-OpenRead

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.

Req-OpenRev

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

Req-Summ

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:

  • 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.
Req-TranCurr

Transition from "Initial" to "Current"

  • Starting from the initial submission, each binding has to 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.) and the results SHOULD be published in a dedicated document (README, or other human-readable documents) called Test Report.
  • A Test Report
    • MUST contain information on the testing environment
    • 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.
    • MUST contain information about the scenario that was tested, e.g. controlling the room temperature by measuring temperature and adjusting the heater.
    • MUST explain where discussions on implementation experience should be collected
    • SHOULD provide the history of all the past testing events (or explain how to retrieve the history of the results gathered during those events)
    • SHOULD contain a reference to the implementations of Consumers or Exposers.
  • For the binding to transition to the "Current" state, a Test Report MUST exist. 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-bindings-registry/issues/3
  • Submitters MAY call for transition but the custodian can also automatically trigger the process once it is verified that the condition above is reached.
  • Test Reports and related resources SHOULD be published in a git repository. The repository SHOULD be public and it 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.
Req-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.

  • Introduction
  • Binding Content:
    • URL Format
    • Form Vocabulary Definition as Table
    • Default and possible mappings to operations as a Table
  • Examples
Req-Docs

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

  • 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.
Req-Confl

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.

Req-Redef

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.

Req-Deps

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.