Merge branch 'main' into decisions-policy

MARKETING/PressReleaseDrafts/2023/draft.md

@@ -10,6 +10,10 @@ are now official W3C Recommendations.
 Without breaking compatibility with the [first release in 2020](https://www.w3.org/press-releases/2020/wot-rec/),
 these new W3C Recommendations improve and expand the scope of the Web of Things,
 and add significant new functionality.
+In addition, two supporting W3C Notes have been updated, the
+[Web of Things (WoT) Binding Templates](https://www.w3.org/TR/wot-binding-templates/) 
+and the
+[Web of Things (WoT) Scripting API](https://www.w3.org/TR/wot-scripting-api/).
 
 <!-- Why is it important? -->
 ## WoT addresses the IoT fragmentation problem

PRESENTATIONS/2023-09-tpac/2023-09-11-WoT-TPAC-JSONLD-WoT-RCH-Discussion.md

@@ -0,0 +1,90 @@
+# JSON-LD WG, WoT WG, RCH WG Joint Meeting
+
+**Draft** summary of main points from the discussion. A further PR is needed to distill the text to a more concise form.
+
+## [Sept 11 Minutes](https://www.w3.org/2023/09/11-wot-minutes.html)
+
+- Introduced WoT
+- Slides https://github.com/w3c/wot/blob/main/PRESENTATIONS/2023-09-tpac/2023-09-11-WoT-TPAC-JSONLD_RCH_JointSession-Korkan_Noura_Barbato.pdf
+
+### Canonicalization and Signing
+
+#### Selective Disclosure
+
+Question from WoT WG: To verify a digital signature the entire document needs to be shared. How to validate a selective disclosure of information rather than an entire credential
+
+- New selective disclosure mechanism in JSON-LD:  https://www.w3.org/TR/vc-di-ecdsa/#ecdsa-sd-2023
+- Another mechanism if need to handle multiple versions: https://docs.google.com/presentation/d/1d-04kIWhPuNscsAyUuRH3pduqrNerhigCWahKe6SNos/edit#
+  - Note from Ege: It is not clear what the difference between the two methods is at this point
+
+- Also see https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/
+
+#### Integrity of Linked Data
+
+Question from WoT WG: How to ensure the integrity of linked data that lies outside of the protection of the proof, e.g. LD @context content and links section in TDs
+
+- Verifiable Credentials WG deals with it in two ways, all fairly new:
+  1. digest: the downside -> if the remote resource allows different media types you need a way to describe digest for multiple content-type
+  2. related resources: in property-related resources, adding that link information and the digest
+  - with something like TD links you would probably add the digest property
+- Default Values in TD:
+  - depends on when the default values are applied: if you do it before signing, it requires pre-processing. The other approach is just not signing them at all
+  - We have to think about the attack model to understand which one is the best
+  - It seems that what we are looking for is a semantic signing, which is challenging. Gut feeling (Pierre-Antoine) is to go with option 2
+
+#### Signature Schemes
+
+Question from WoT WG: Which signature schemes are appropriate for TD?
+
+Useful Links:
+
+- https://www.w3.org/TR/vc-data-integrity/
+- https://www.w3.org/TR/vc-di-eddsa/
+- https://www.w3.org/TR/vc-di-ecdsa/
+
+- Two schemes above would work. For signature working in YAML too, go with eddsa.
+-  bbs provides unlinkability but is experimental
+
+#### Actors in VC and WoT
+
+Question from WoT WG: Mapping of the actors in the VC to the WoT Ecosystems. Subject, Issuer, Holder, & Verifier. Who is the trustable entity in this ecosystem?  What is this verified data registry in the context of the Web of Things?
+
+- WoT can issue TDs and VCs
+- data integrity is not connected with VC
+- By putting a TD inside a VC, it is possible to have trust lists that can be used to identify who is allowed to issue TDs in a specific system
+
+Note from Ege: This section is not minuted thoroughly or was short.
+
+### Degraded Consumption
+
+Slides contain the motivation
+
+- Section in VC about processing JSON-LD in a degraded fashion and JSON-LD is built to be used only when needed
+  - In the VC data model, some processors do not do the JSON-LD processing which uses well-known context URLs, freezes the context, and cryptographically signs it
+  - There is a slimmer profile of JSON-LD to do just JSON-only processor
+- Fixing the order of the contexts is important to avoid redefinition and security attacks (do not let redefine terms of the standard)
+- It is also possible to remove `:` and call terms in camel case. Like cov:methodName -> covMethodName
+  - as long as the prefixes are fixed that is good.
+
+### Other serialization formats
+
+Question from WoT WG: Currently we just support JSON and JSON-LD. Having more format is good. YAML-LD allows comments, and CBOR-LD has size benefits. What is the current state of these special formats?
+
+- JSON-LD wg is working consistently on the YAML-LD with plans to create a CG by the end of the year
+- CBOR-LD has been deployed to production systems. However, the spec is not in its best shape
+- Developers like YAML
+
+### Linting
+
+Question from WoT WG: Lately there has been an emergence of tools to lint Open API or other descriptions. What can we do for the TD? Is there any mechanism within JSON-LD?
+
+- From the spec perspective the best way is to look at SHACL It is powerful and there are tools that compare a graph to the idial end result.
+- JSON-LD processors have safe mode. if it finds something that is undefined, it stops processing.
+- other well-known tool for linting is JSON schema
+- JSON-LD playground has warnings but more can be added,  like a warning for the default vocabulary
+- linting tends to be application-specific. If WoT WG finds something that is generic, we can contact JSON-LD WG
+- VC uses a property to define a schema for defining linting rules
+
+## Action Items
+
+To be further worked on

PRESENTATIONS/2023-09-tpac/2023-09-14-WoT-TPAC-Discovery-Discussion.md

@@ -0,0 +1,20 @@
+# Discovery
+Summary of main points from discussion.
+
+- Multiprotocol support
+    - Directory API for CoAP
+    - Note: currently have TD Server supported with CoAP
+    - Issue with CoAP-only devices with multiple TDs wanting to self-describe, right now that needs HTTP (read-only directory)
+        - Could use CoRE-RD for this case
+    - Discovery should be generic enough to handle different protocols
+        - Follow-up comment:
+              - We have a TD for a Directory service.  Can we make this generic enough that it can bind to any protocol?   Should bindings specify how to do discovery for that protocol?  Need to cover things not in the TD, such as security bootstrapping.
+- New Introductions
+    - MQTT
+    - OPC UA
+- MQTT Discovery
+    - No OASIS standard (but we should talk to them)
+    - Home Assistant has one specific way of doing it... but not following a standard?
+    - Follow-up comment:
+        - Sparkplug B is an Eclipse specification includes discovery - https://sparkplug.eclipse.org/specification; HiveMQ has some interest
+        - Can we actually deliver TDs with MQTT links? e.g. a TD server, well-known topic, even if only for self-describing things?

policies/README.md

@@ -5,4 +5,7 @@ To propose a new policy, prepare a draft first in [wot/proposals/policies](https
 call for a group resolution to adopt it.  If the group resolution passes, it can be moved here and added to the index below.
 
 ## Index
-[Group Decisions](decisions.md)
+
+* [Group Decisions](decisions.md)
+* [Asynchronous Decisions for Deliverables](async-decision.md)
+

proposals/policies/async-decision.md → policies/async-decision.md

@@ -1,37 +1,50 @@
-# Web of Things (WoT) Policy (Draft)
+# Web of Things (WoT) Policy
 This is a policy to make the review process for specification changes more efficient by using asynchronous tools, rather than following the current unwritten rule that pull requests can only be merged following a resolution in a synchronous weekly conference call.
-The scope of this policy is limited to individual documents or deliverables where the editors are the editors of the document or deliverable in scope.
+The scope of this policy is limited to individual deliverables where the editors are the editors of the deliverable in scope.
 
 This policy was originally [submitted](https://lists.w3.org/Archives/Public/public-wot-wg/2021Aug/0006.html) to the public-wot-wg mailing list on 3rd August 2021 and followed up by @benfrancis at https://github.com/w3c/wot/pull/1005/files.
 This version extends it by taking the reviews into account, while moving the problem and notes into an Appendix section.
 
-## Asynchronous Decisions
+## Asynchronous Decisions for Deliverables
 
 ### Overall Idea
 
 We use GitHub's built-in [code review tools](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) to formally review pull requests without having to wait for a decision in a synchronous weekly call.
 This form of asynchronous decision process specifies how to conduct asynchronous decisions that are already written in the Working Group's existing [Decision Policy](https://www.w3.org/2020/01/wot-wg-charter.html#decisions).
 
-### Non-normative Changes
+### Issues and Pull Requests
 
-- For non-normative or editorial changes to the wording of a specification or its supporting documents, a code review approval from a single Editor of the specification is sufficient to merge a pull request.
+The rules below apply to the two subsequent sections:
+
+- An Issue should be created before a Pull Request that links to it is created.  This Issue should be used to reach a consensus before creating a Pull Request if possible.  This discussion can include whether the change needs to be normative or not.
+    - Note: A template for Issues should be created that prompts for useful information, e.g. a link to a Use Case and/or Requirement; to be discussed.
+    - Note: A template for PRs should be created that prompts for a link to the related issue and a proposed category: Editorial or Normative
+- Editors should label Pull Requests as being either "Editorial" (non-normative) or "Normative" as soon as possible.
+- At least one week should be allowed for discussion after the label has been applied before merging a Pull Request.
+- If any Working Group member disagrees with an "Editorial" classification, a Pull Request should be reclassified as "Normative"
+
+### Editorial (Non-normative) Changes
+
+- For changes labeled as Editorial (which make non-normative changes to the wording of a specification or its supporting documents), a code review approval from a single Editor of the specification is sufficient to merge a Pull Request, if there are no objections or calls for discussion from any Working Group member (including other Editors) on the Pull Request.
 
 ### Normative Changes
 
-- For normative or breaking changes to a specification, approval is required by at least two Editors of a specification who are not from the same organization or who are Invited Experts. Editors should use GitHub's code review tool to either:
-  - Approve the pull request. The approval should be clear and if there any further changes needed, they should be requested to the pull request (see below) or a separate issue should be opened.
-  - Request changes to the pull request, explained in a comment
-  - Comment to say that they have no strong opinion or that they abstain, deferring to the opinion of other editors
-- A pull request can be landed once two editors have either provided their approval.
+- In the following, the Editor's decisions should reflect their understanding of the consensus of the group.
+- For Normative (breaking changes or new features to a specification), approval is required by at least two Editors of a specification who are not from the same organization or who are Invited Experts. Editors should use GitHub's code review tool to either:
+  - Approve the Pull Request. The approval should be clear and if there are any further changes needed, they should be requested to the pull request (see below) or a separate issue should be opened.
+  - Request changes to the Pull Request, explained in a comment.
+  - Comment to say that they have no strong opinion or that they abstain, deferring to the opinion of other editors.
+- A pull request can be landed once two editors have provided their approval.  However, if any editor objects then the Pull Request should be rejected.
 - Editors are expected to provide formal reviews, but all members (and non-members) may contribute to the public discussion on GitHub and Editors are responsible for determining consensus. Reviews may be requested from other interested members in order to ascertain consensus.
-- If there are request for changes from other members, they should be taken into account.
-- If a consensus can not be reached by the editors asynchronously where the Pull Request discussion thread goes long (see appendix) without making progress, then a synchronous discussion in a web conference is needed to arrive at a consensus. The need for a synchronous discussion should be indicated in the discussion and the results should be reflected as a GitHub comment. If a unanimous decision can not be reached, then Chairs may call for a group decision to resolve a deadlock in line with the Working Group's existing [Decision Policy](https://www.w3.org/2020/01/wot-wg-charter.html#decisions).
+- If there are requests for changes from other Working Group members, they should be taken into account.
+- If a consensus can not be reached by the editors asynchronously where the Pull Request discussion thread goes long (see appendix) without making progress, then a synchronous discussion in a web conference is needed to arrive at a consensus. The need for a synchronous discussion should be indicated in the discussion and the results should be reflected as a GitHub comment. If a unanimous decision can not be reached by the members of the Working Group involved in the discussion, then Chairs may call for a group decision to resolve a deadlock in line with the Working Group's existing [Decision Policy](https://www.w3.org/2020/01/wot-wg-charter.html#decisions).
+- For all changes, those who start a Pull Request or Discussion/Issue implicitly agree beforehand to join a synchronous meeting in case the TF moderator identifies a long and inconclusive discussion and calls for a meeting.
 
 ## Appendix
 
 ### How to identify long and inconclusive discussion
 
-One-size-fits-all solution to identify a long and inconclusive is not realistic. In the end, it is the editors' responsability to identify such cases. 
+A one-size-fits-all solution to identify a long and inconclusive is not realistic. In the end, it is the editors' responsibility to identify such cases. 
 Some metrics that the editors can use are listed below:
 
 1. **Number of Comments**: A long and complex discussion often involves multiple participants sharing their thoughts and opinions. Look for a high number of comments on the PR. You can see the comment count on the Pull Request page.
@@ -49,7 +62,7 @@ Some metrics that the editors can use are listed below:
 ### Problem
 
 Currently:
-1. It is common to get to the end of a two hour meeting without having managed to review all of the open pull requests in a given repository
+1. It is common to get to the end of a two-hour meeting without having managed to review all of the open pull requests in a given repository
 2. If anyone is missing from the call who may have feedback, the discussion is often deferred for a week or more until they are available to join a call
 3. When pull requests are reviewed there isn't always a clear resolution about whether or not to merge and discussion can end up being paused until the following week
 4. Sometimes only small changes are needed to a pull request before landing it, but it has to wait another week for a chance for another review