From ac7c4620cf933aa8d6ffbb8b4fa3307d168e71b7 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 5 Aug 2025 17:56:57 +0200 Subject: [PATCH 01/24] refactor: reformat first section --- index.html | 85 ++++++++++++++++++++++-------------------------------- 1 file changed, 35 insertions(+), 50 deletions(-) diff --git a/index.html b/index.html index 06fdc0f..83377b6 100644 --- a/index.html +++ b/index.html @@ -209,56 +209,41 @@

Terminology

-
-

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.

-
-
+ +
+

WoT Binding Document

+

A binding document should meet the following requirements.

+
    +
    • +
    • +
    • +
    • +
+
+

Expert Knowledge

+

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.

+

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

+
+
+

Separate Document

+

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

+

+ It is easier to update in the long term. +

+
+
+

Association

+

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.

+

+ WoT WG is the manager of the registry. +

+
+
+

Other Entity

+

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

+
From 5243ef327d69acd0aaeb031e048ac5a46511e430 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 8 Aug 2025 11:31:22 +0200 Subject: [PATCH 02/24] revert previous commit https://github.com/w3c/wot-bindings-registry/pull/17/commits/ac7c4620cf933aa8d6ffbb8b4fa3307d168e71b7 --- index.html | 85 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 35 deletions(-) diff --git a/index.html b/index.html index 83377b6..06fdc0f 100644 --- a/index.html +++ b/index.html @@ -209,41 +209,56 @@

Terminology

- -
-

WoT Binding Document

-

A binding document should meet the following requirements.

-
    -
    • -
    • -
    • -
    • -
-
-

Expert Knowledge

-

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.

-

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

-
-
-

Separate Document

-

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

-

- It is easier to update in the long term. -

-
-
-

Association

-

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.

-

- WoT WG is the manager of the registry. -

-
-
-

Other Entity

-

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

-
+
+

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.

+
+
From b693188deaeebeae82014e2e105071e220eea0a0 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 8 Aug 2025 12:20:25 +0200 Subject: [PATCH 03/24] reformat: section 6 and add table in 6.1 entry format --- index.html | 173 +++++++++++++++++++++++++---------------------------- 1 file changed, 83 insertions(+), 90 deletions(-) diff --git a/index.html b/index.html index 06fdc0f..3b0f005 100644 --- a/index.html +++ b/index.html @@ -264,103 +264,96 @@

Intro Section of the Document

Content of Registry Definition

-

A preliminary list of rules that is extending https://www.w3.org/2023/Process-20230612/#reg-def (needs more iteration):

+

A set of rules extending the Registry Definitions from the W3C Process Document can be found below and is structures as follows.

    -
  • Entry format: what is put into the table and not what the binding should contain.
    • -
  • Lifecycle of entries: how are they submitted, updated, deprecated etc.
    • -
  • Submission Requirements: What the binding has to contain to go into the table
    • +
  • + +
    • +
  • + +
    • +
    • +
  • + +
-

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

-
-
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Entry format information +
InformationAdditional Notes
Name of the bindingExamples: HTTP Binding, CoAP Binding
Binding ontology prefixExamples: htv, modv, cov
Binding Identification in TDURI 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.
      • +
    +
    • +
+
Supported TD versionA binding SHOULD correspond to specific TD specification version(s).
+ Note: no uniqueness needed +
    +
  • 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.
    • +
+ +
StatusOne of "Initial", "Current", "Superseded" or "Obsolete".
Summary DocumentLink to the summary document.
VersionVersion: 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

@@ -425,7 +418,7 @@

Lifecycle

-
+

Ownership

@@ -448,8 +441,8 @@

Ownership

-
-

Requirements on the Submitted Document

+
+

Submission Requirements

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

From c005dc00b8d4aff42b8fec5dec835eab757628e2 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 8 Aug 2025 12:26:08 +0200 Subject: [PATCH 04/24] style: one of list --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 3b0f005..75bac29 100644 --- a/index.html +++ b/index.html @@ -338,7 +338,7 @@

Entry format

Status - One of "Initial", "Current", "Superseded" or "Obsolete". + One of Initial, Current, Superseded or Obsolete. Summary Document From 05df8228710619d204d619f780be2269d537e48f Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Fri, 8 Aug 2025 12:27:39 +0200 Subject: [PATCH 05/24] fix: minor typo --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 75bac29..c236fdd 100644 --- a/index.html +++ b/index.html @@ -264,7 +264,7 @@

Intro Section of the Document

Content of Registry Definition

-

A set of rules extending the Registry Definitions from the W3C Process Document can be found below and is structures as follows.

+

A set of rules extending the Registry Definitions from the W3C Process Document can be found below and is structured as follows.

  • From a280e9880cf626ec839d25e1277b7e0f535db879 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 15:09:18 +0200 Subject: [PATCH 06/24] Add table column "Type" fixes https://github.com/w3c/wot-bindings-registry/pull/17#pullrequestreview-3106328393 --- index.html | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index c236fdd..b924e05 100644 --- a/index.html +++ b/index.html @@ -290,26 +290,31 @@

    Entry format

    Information - Additional Notes + Type + Description Name of the binding + string Examples: HTTP Binding, CoAP Binding Link to the binding document + anyURI 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 Binding ontology prefix + string Examples: htv, modv, cov Binding Identification in TD + ??? URI Scheme or other TD terms reserved for this binding.
    Examples: "subprotocol":"sse", "href":"http://example.com", "contentType":"application/json"
      @@ -328,6 +333,10 @@

      Entry format

      Supported TD version + + string or + Array of + string A binding SHOULD correspond to specific TD specification version(s).
      Note: no uniqueness needed
        @@ -338,15 +347,18 @@

        Entry format

        Status + enumeration of [Initial, Current, Superseded, Obsolete] One of Initial, Current, Superseded or Obsolete. Summary Document + anyURI Link to the summary document. Version - 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. + string + 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. From d77100cf6f3b19cbfa0b061c21ab668a0de47732 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 15:21:48 +0200 Subject: [PATCH 07/24] refactor: remove some parts and create (ed)notes --- index.html | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index b924e05..17625c0 100644 --- a/index.html +++ b/index.html @@ -317,8 +317,12 @@

        Entry format

        ??? URI Scheme or other TD terms reserved for this binding.
        Examples: "subprotocol":"sse", "href":"http://example.com", "contentType":"application/json" -
          - + + + +

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

          @@ -339,9 +349,9 @@

          Entry format

          string A binding SHOULD correspond to specific TD specification version(s).
          Note: no uniqueness needed -
            -
          • 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.
            • -
          +

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

          From 31cade8e9bf00fcc5266adf8249eb075ca9da444 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 16:19:51 +0200 Subject: [PATCH 08/24] reformat other sections --- index.html | 446 ++++++++++++++++++++++++++--------------------------- 1 file changed, 217 insertions(+), 229 deletions(-) diff --git a/index.html b/index.html index 17625c0..830ddc7 100644 --- a/index.html +++ b/index.html @@ -378,251 +378,239 @@

          Entry format

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

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

          Status

          +

          We distinguish between the following statuses: 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
            • +
          • 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 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 +

          +
          + +
          +

          Transitioning

          +

          What are the requirements for transitioning from one value to another? See section as well.

          +
          + +
          +

          Versioning

          +

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

          +

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

          +
          + +
          +

          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.

          -
          -
          +
          +

          Custodian

          +

          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.

          +

          Maintaining the registry without the WoT WG should be possible.

          +
          + +
          +

          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.

          +

          Submission Requirements

          -

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

          +

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

            [DP] Should we create a table instead of the (sub-)sections?

            + + +
            +

            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.

            +
            + +
            +

            Initial entry

            +

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

            +
            + +
            +

            Changelog

            +

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

            +
            + +
            +

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

            +
            + +
            +

            Copyright

            +

            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.

            +
            + +
            +

            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 be added to the registry.

            +
            + +
            +

            Reviewer Access

            +

            Reviewer 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 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.
              -
          -
          - 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
            • + +
          • 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.
            • +
          +
          + +
          +

          Transition

          +

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

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

            -
            - +
            • +
          • Examples
            • +
          +
          + +
          +

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

          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.

          +
From a6a4fdc36db04ba62d7cf3c4dd780cca9c8371ff Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 16:23:11 +0200 Subject: [PATCH 09/24] add ednote --- index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 830ddc7..f201cb5 100644 --- a/index.html +++ b/index.html @@ -529,7 +529,9 @@

Summary Document

  • 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:
    • +
  • 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: +

    [DP] the list is not correctly nested but was already that way in the original MD dcoument.

    +
  • Reading the binding document
  • Reading the protocol specification
  • Implementing a non-commercial device/Thing
    • From c5f55f291fc4995e672ee6595cf1f1d6fc4495a7 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 16:25:17 +0200 Subject: [PATCH 10/24] American English --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index f201cb5..7fc92b6 100644 --- a/index.html +++ b/index.html @@ -392,7 +392,7 @@

    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 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.
      • +
    • 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".
    @@ -500,7 +500,7 @@

    Changelog

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

    +

    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.

    From 3107d1ea0348af54e49f69c7fb18f3fc2bda240e Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 13 Aug 2025 16:28:47 +0200 Subject: [PATCH 11/24] minor typos --- index.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 7fc92b6..f1c91fc 100644 --- a/index.html +++ b/index.html @@ -510,17 +510,17 @@

    Copyright

    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 be added to the registry.

    +

    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

    -

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

    +

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

    +

    The submitter MUST fill in 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?
        • @@ -530,7 +530,7 @@

        Summary Document

      • 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: -

        [DP] the list is not correctly nested but was already that way in the original MD dcoument.

        +

        [DP] the list is not correctly nested but was already that way in the original MD document.

      • Reading the binding document
      • Reading the protocol specification
        • From 6951c34c48c05bcc46dba2dde982af47e99d7f0f Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 18 Aug 2025 15:21:59 +0200 Subject: [PATCH 12/24] reformat: Moving an editorial note that is in a table cell to below the table see github.com/w3c/wot-bindings-registry/pull/17#issuecomment-3194686439 --- index.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index f1c91fc..b84ec8b 100644 --- a/index.html +++ b/index.html @@ -333,9 +333,6 @@

        Entry format

    --> -

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

    @@ -373,6 +370,10 @@

    Entry format

    +

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

    +
    From 0944586367efcd385633425448aaf14c866ae016 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 18 Aug 2025 16:09:33 +0200 Subject: [PATCH 13/24] add assertion tag and split sentences see assertion --- index.html | 100 +++++++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 46 deletions(-) diff --git a/index.html b/index.html index b84ec8b..2a743e3 100644 --- a/index.html +++ b/index.html @@ -54,6 +54,16 @@ ] }; + + + @@ -282,7 +292,7 @@

    Content of Registry Definition

    Entry format

    -

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

    +

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

    - +
    Entry format information @@ -344,7 +354,7 @@

    Entry format

    string or Array of string -
    A binding SHOULD correspond to specific TD specification version(s).
    +     		A binding SHOULD correspond to specific TD specification version(s).
    Note: no uniqueness needed

    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. @@ -365,7 +375,7 @@

    Entry format

    Version stringA 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.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.
    @@ -394,7 +404,7 @@

    Technical submission mechanism

    • 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".
      • +
    • 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".
    @@ -447,7 +457,7 @@

    Custodian

    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.

    +

    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.

    @@ -480,57 +490,57 @@

    Submission Requirements

    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

    +

    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.

    +

    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.

    Initial entry

    -

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

    +

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

    Changelog

    -

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

    +

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

    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.

    +

    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 DOES NOT have to follow the W3C copyright. The submitter is free to choose based on the process they or their organization follows.

    +

    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.

    -

    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.

    +

    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)

    +

    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 the summary document, which is hosted by the custodian together with the registry. This form contains the following:

    +

    The submitter MUST fill in 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:
        +
      • 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: +
      • 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:

        [DP] the list is not correctly nested but was already that way in the original MD document.

      • Reading the binding document
        • @@ -539,10 +549,10 @@

        Summary Document

      • 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.
        • +
      • 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.
    @@ -551,27 +561,27 @@

    Transition

    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.
        • +
      • At each testing event, every operation defined in the binding MUST be validated automatically (e.g., scripts, test suites, etc.). The results SHOULD 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 ReportSHOULD 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.
        • +
      • 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.
        • +
      • 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.

    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.

    +

    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:
        @@ -588,31 +598,29 @@

        Content

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

    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.

    +

    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.

    +

    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.

    +

    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.

    From a40ebd48ffd98e4b20b1309d601ffcf9f34839ad Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 18 Aug 2025 16:11:54 +0200 Subject: [PATCH 14/24] fix: HTML syntax --- index.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.html b/index.html index 2a743e3..fffa35a 100644 --- a/index.html +++ b/index.html @@ -359,7 +359,6 @@

    Entry format

    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.

    - @@ -600,7 +599,7 @@

    Documents

    • 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.
      • +
    • 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.
      • From 49c995d1c3ce52bd73bb361843b9bc77e09499ad Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Tue, 19 Aug 2025 16:43:37 +0200 Subject: [PATCH 15/24] Update index.html Co-authored-by: Ege Korkan --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index fffa35a..c6733af 100644 --- a/index.html +++ b/index.html @@ -515,7 +515,7 @@

      Document Section

      Copyright

      -

      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 WoT binding document MAY NOT follow the W3C copyright. The submitter is free to choose based on the process they or their organization follows.

      From cdeb21435c496630e9344701c4698c75ae413617 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 11:58:08 +0200 Subject: [PATCH 16/24] refactor: use "any type" for Binding Identification in TD --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index fffa35a..c4a2e02 100644 --- a/index.html +++ b/index.html @@ -324,7 +324,7 @@

      Entry format

      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" From beb5c446e9c8b333b3e93eee4de737475defc241 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 12:02:25 +0200 Subject: [PATCH 17/24] refactor: remove commented code that is a editor's note already --- index.html | 1 - 1 file changed, 1 deletion(-) diff --git a/index.html b/index.html index 7d95e84..dc2c78b 100644 --- a/index.html +++ b/index.html @@ -338,7 +338,6 @@

      Entry format

    • 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.
    • From 1c154db1971a2d4f678bf18474ed5117ba93a647 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 12:05:55 +0200 Subject: [PATCH 18/24] refactor: remove unnecessary ednote --- index.html | 3 --- 1 file changed, 3 deletions(-) diff --git a/index.html b/index.html index dc2c78b..00e5867 100644 --- a/index.html +++ b/index.html @@ -483,9 +483,6 @@

    Submission Requirements

    -

    [DP] Should we create a table instead of the (sub-)sections?

    - -

    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.

    From ad9072d52cf0e3c1854a2f309cb93e72bac48a63 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:06:04 +0200 Subject: [PATCH 19/24] Update index.html Co-authored-by: Ege Korkan --- index.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.html b/index.html index 00e5867..2411113 100644 --- a/index.html +++ b/index.html @@ -449,8 +449,7 @@

    Ownership

    Custodian

    -

    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.

    -

    Maintaining the registry without the WoT WG should be possible.

    +

    If the WoT WG no longer exists, the W3C Team or its delegated entity becomes 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.

    From d9360c2b5a16fd22a348bfb9ee9054fac7540766 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:09:22 +0200 Subject: [PATCH 20/24] refactor: remove reference and use note text see https://github.com/w3c/wot-bindings-registry/pull/17#discussion_r2285369489 --- index.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.html b/index.html index 2411113..251c3d7 100644 --- a/index.html +++ b/index.html @@ -436,8 +436,7 @@

    Versioning

    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.

    From 8d799eee2a85f63ef85bb6fb0b366811cb944335 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:15:44 +0200 Subject: [PATCH 21/24] refactor: reformulate to void assertive language see https://github.com/w3c/wot-bindings-registry/pull/17#discussion_r2285465174 --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 251c3d7..784c2d9 100644 --- a/index.html +++ b/index.html @@ -494,7 +494,7 @@

    ContentType

    Initial entry

    -

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

    +

    Initial entry MUST be a correct document which complies with . 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".

    From 339393d1106730c909899bc30f7bfcbf9861d036 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:19:26 +0200 Subject: [PATCH 22/24] fix nesting list items --- index.html | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 784c2d9..3d65e6d 100644 --- a/index.html +++ b/index.html @@ -534,14 +534,15 @@

    Summary Document

  • 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: -

    [DP] the list is not correctly nested but was already that way in the original MD document.

    +
      +
    • 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
      • +
    • -
  • 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.
    • From 12a04f8d694e77865e763fbc5e1a1e29ee711214 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:23:14 +0200 Subject: [PATCH 23/24] refactor: made assertion https://github.com/w3c/wot-bindings-registry/pull/17#discussion_r2285479742 --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 3d65e6d..7cdfbd8 100644 --- a/index.html +++ b/index.html @@ -554,7 +554,7 @@

    Summary Document

    Transition

    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.
      • +
    • 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 SHOULD 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.
        • From 2782392f16dc6f31f34aff5eb7eea2f8f4360090 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Wed, 20 Aug 2025 17:32:59 +0200 Subject: [PATCH 24/24] refactor: move note to submission requirements --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 7cdfbd8..1ba1c15 100644 --- a/index.html +++ b/index.html @@ -355,9 +355,6 @@

        Entry format

        string A binding SHOULD correspond to specific TD specification version(s).
        Note: no uniqueness needed -

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

        @@ -586,6 +583,9 @@

        Content

      • Examples
      +

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