From 23873d39254e02145824711ac4214caaa71a6c0c Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Thu, 31 Oct 2024 14:58:53 +0100 Subject: [PATCH 01/14] incorporate user story usage --- planning/work-items/usability-and-design.md | 23 +++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 2badfe55..e3d5b997 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -50,14 +50,29 @@ Checking overlaps with architecture. ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20connections) +**User Stories:** + +1. Connection Oriented Protocols + - Who: As a deployer of devices with connection oriented protocols + - What: Reusable Connection descriptions in a TD + - Why: better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) +2. Reusable Defaults per TD + - Who: Designer/Developer of TDs + - What: Reusable Connection descriptions in a TD + - Why: simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) + +TODOs: +- These can be turned into single sentences to "force" submitters to be concise. +- The use case should be linked to the user stories above. + **Problem:** Currently, each form of an affordance has information on the endpoint, media type and other protocol related information. It is possible to use the base term for simplifying the endpoint but it has limitations such as: -- If the media type is common across forms but is not `application/json`, it is repeated in each form. -- If there are common protocol stack configurations such as different default verbs, baud rates, and endianness, they are repeated in each form -- Multiple bases are not possible. Thus, each form repeats multiple bases. This is relevant when a TD has local and public IP addresses -- For protocols that are based on an initial connection and then subsequent messages, the semantics are not clear. Thus, a Consumer can establish multiple connections instead of reusing the initial connection. See the Example of the Message Flow section below +1. If the media type is common across forms but is not `application/json`, it is repeated in each form. +2. If there are common protocol stack configurations such as different default verbs, baud rates, and endianness, they are repeated in each form +3. Multiple bases are not possible. Thus, each form repeats multiple bases. This is relevant when a TD has local and public IP addresses +4. For protocols that are based on an initial connection and then subsequent messages, the semantics are not clear. Thus, a Consumer can establish multiple connections instead of reusing the initial connection. See the Example of the Message Flow section below Related Issues: From e3a6105e067ed1eb25580aa6882f0989903589d7 Mon Sep 17 00:00:00 2001 From: egekorkan Date: Thu, 31 Oct 2024 14:00:04 +0000 Subject: [PATCH 02/14] Prettified Code! --- planning/work-items/usability-and-design.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index e3d5b997..4415b421 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -53,15 +53,19 @@ Checking overlaps with architecture. **User Stories:** 1. Connection Oriented Protocols - - Who: As a deployer of devices with connection oriented protocols - - What: Reusable Connection descriptions in a TD - - Why: better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) + +- Who: As a deployer of devices with connection oriented protocols +- What: Reusable Connection descriptions in a TD +- Why: better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) + 2. Reusable Defaults per TD - - Who: Designer/Developer of TDs - - What: Reusable Connection descriptions in a TD - - Why: simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) -TODOs: +- Who: Designer/Developer of TDs +- What: Reusable Connection descriptions in a TD +- Why: simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) + +TODOs: + - These can be turned into single sentences to "force" submitters to be concise. - The use case should be linked to the user stories above. From b2cc136a79a850e41a4636b8275baa82543dd6c0 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 5 Nov 2024 13:36:38 +0100 Subject: [PATCH 03/14] Update usability-and-design.md --- planning/work-items/usability-and-design.md | 29 +++++++++++++-------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 4415b421..297079b8 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -50,26 +50,31 @@ Checking overlaps with architecture. ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20connections) +TODOs: + +- The use case should be linked to the user stories above. +- Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and + **User Stories:** 1. Connection Oriented Protocols -- Who: As a deployer of devices with connection oriented protocols -- What: Reusable Connection descriptions in a TD -- Why: better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) +- **Who:** Deployer of devices with connection oriented protocols +- **What:** Reusable Connection descriptions in a TD +- **Why:** Better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) -2. Reusable Defaults per TD +- Sentence: **As a** deployer of devices with connection oriented protocols, **I need** reusable Connection descriptions in a TD, **so that I can** better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) -- Who: Designer/Developer of TDs -- What: Reusable Connection descriptions in a TD -- Why: simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) +2. Reusable Defaults per TD -TODOs: +- **Who:** Designer/Developer of TDs +- **What:** Reusable Connection descriptions in a TD +- **Why:** Simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) -- These can be turned into single sentences to "force" submitters to be concise. -- The use case should be linked to the user stories above. +- Sentence: **As a** designer/developer of TDs, **I need** reusable connection descriptions in a TD, **so that I can** simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below). **Problem:** + Currently, each form of an affordance has information on the endpoint, media type and other protocol related information. It is possible to use the base term for simplifying the endpoint but it has limitations such as: @@ -94,8 +99,10 @@ Related Issues: - Basic Requirement: A mechanism to describe connection and protocol information that other forms can use is needed. In protocols with initial connection, this can also be used to indicate what needs to be done by the Consumer before executing any operation. - Detailed Requirements: - - Each connection needs to be identifiable, but we need to make sure not to include privacy or security risks + - Each connection needs to be identifiable + - Each connection needs to be linkable from affordances or forms - The initial connection must not be mandatory to establish upon TD consumption and should left to the implementation when to establish and close it. +- Requirements are available at **Notes:** From 5ac8d2ee6405a7798bba08ba4fff75d69b8c4db2 Mon Sep 17 00:00:00 2001 From: egekorkan Date: Tue, 5 Nov 2024 12:37:04 +0000 Subject: [PATCH 04/14] Prettified Code! --- planning/work-items/usability-and-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 297079b8..8df847c9 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -53,7 +53,7 @@ Checking overlaps with architecture. TODOs: - The use case should be linked to the user stories above. -- Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and +- Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and **User Stories:** From c6467a0e8802eb52ccec6481c129dbbdc29aa308 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 5 Nov 2024 13:49:20 +0100 Subject: [PATCH 05/14] Update usability-and-design.md --- planning/work-items/usability-and-design.md | 1 + 1 file changed, 1 insertion(+) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 8df847c9..567e3754 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,6 +54,7 @@ TODOs: - The use case should be linked to the user stories above. - Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and +- Collect Stakeholders: People who submitted issues/UCs, spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. Impact needs to be defined as well, i.e. what kind of impact (implementation, security, privacy). **User Stories:** From fdc3a361675aaaa2a8bc6c5e4dcd4f4ee681ebbd Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 5 Nov 2024 17:37:42 +0100 Subject: [PATCH 06/14] Update planning/work-items/usability-and-design.md Co-authored-by: Ted Thibodeau Jr --- planning/work-items/usability-and-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 567e3754..85a970be 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,7 +54,7 @@ TODOs: - The use case should be linked to the user stories above. - Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and -- Collect Stakeholders: People who submitted issues/UCs, spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. Impact needs to be defined as well, i.e. what kind of impact (implementation, security, privacy). +- Collect Stakeholders: People who submitted issues/UCs, spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. **User Stories:** From 085f57afb43a23c0e930f5a6efabffcb8082acff Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 6 Nov 2024 13:30:28 +0100 Subject: [PATCH 07/14] Update usability-and-design.md --- planning/work-items/usability-and-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 85a970be..7c5a741b 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,7 +54,7 @@ TODOs: - The use case should be linked to the user stories above. - Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and -- Collect Stakeholders: People who submitted issues/UCs, spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. +- Collect Stakeholders: People who submitted issues/UCs (who wants it first), spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. **User Stories:** From 6a19f7a037e23a8aa683fe4aaba8ce91a2e47e6c Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 6 Nov 2024 19:52:29 +0100 Subject: [PATCH 08/14] Update planning/work-items/usability-and-design.md Co-authored-by: Ted Thibodeau Jr --- planning/work-items/usability-and-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 7c5a741b..cc76c4a3 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,7 +54,7 @@ TODOs: - The use case should be linked to the user stories above. - Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and -- Collect Stakeholders: People who submitted issues/UCs (who wants it first), spec writers (people from the TF who want to help writing the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. +- Collect Stakeholders: People who submitted issues/UCs (people who want it first), spec writers (people from the TF who want to help write the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. **User Stories:** From 85a8a915659f04e569e0ca754eaab77aff9c4e3a Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Thu, 7 Nov 2024 14:48:25 +0100 Subject: [PATCH 09/14] add stakeholders --- planning/work-items/usability-and-design.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index cc76c4a3..2355dd63 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,7 +54,11 @@ TODOs: - The use case should be linked to the user stories above. - Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and -- Collect Stakeholders: People who submitted issues/UCs (people who want it first), spec writers (people from the TF who want to help write the spec on this feature), people who want to implement the feature in their implementation, people who will be impacted by the change (this is probably the whole community). These stakeholders each need a clear definition and example. The kind of impact (implementation, security, privacy, etc.) needs to be defined as well. +- Move these definitions somewhere: + - Submitter: People who have submitted the user story and thus wants this story to be succesful. + - Specification Writers: People from the TF who want to (or can) work on writing the specification text and corresponding resources. + - Implementation Volunteers: People who want to implement this and contribute the results to the implementation report. The submitter is strongly encouraged to provide an implementation result. + - Impacted: Entities that will be impacted by this. Impact type can be "implementation overhead", "security", "privacy", "accesibility" etc. **User Stories:** @@ -65,6 +69,11 @@ TODOs: - **Why:** Better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) - Sentence: **As a** deployer of devices with connection oriented protocols, **I need** reusable Connection descriptions in a TD, **so that I can** better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) +- Stakeholders: + - Submitter: Multiple + - Specification Writers: Ege Korkan + - Implementation Volunteers: Ege Korkan + - Impacted: TD Designers and Consumers. Type: Implementation Overhead 2. Reusable Defaults per TD @@ -73,6 +82,11 @@ TODOs: - **Why:** Simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) - Sentence: **As a** designer/developer of TDs, **I need** reusable connection descriptions in a TD, **so that I can** simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below). +- Stakeholders: + - Submitter: Multiple + - Specification Writers: Ege Korkan + - Implementation Volunteers: Ege Korkan + - Impacted: TD Designers and Consumers. Type: Implementation Overhead **Problem:** From 84904567b97259b20a9dfc3c2e4f4c652b3d46b2 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Thu, 7 Nov 2024 14:57:44 +0100 Subject: [PATCH 10/14] add issue comment from ege --- planning/work-items/usability-and-design.md | 34 ++++++++++++++++----- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 2355dd63..cea780c1 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -88,7 +88,7 @@ TODOs: - Implementation Volunteers: Ege Korkan - Impacted: TD Designers and Consumers. Type: Implementation Overhead -**Problem:** +**Summarized Problem:** Currently, each form of an affordance has information on the endpoint, media type and other protocol related information. It is possible to use the base term for simplifying the endpoint but it has limitations such as: @@ -112,12 +112,32 @@ Related Issues: **Requirements** -- Basic Requirement: A mechanism to describe connection and protocol information that other forms can use is needed. In protocols with initial connection, this can also be used to indicate what needs to be done by the Consumer before executing any operation. -- Detailed Requirements: - - Each connection needs to be identifiable - - Each connection needs to be linkable from affordances or forms - - The initial connection must not be mandatory to establish upon TD consumption and should left to the implementation when to establish and close it. -- Requirements are available at +- There are 3 main points. Point 2 is about a keyword (more or less), whereas point 3 is more about the underlying mechanism. + 1. Having a place to put common connection information + 2. Linking to a common connection information. + 3. Signaling that a form in an affordance can reuse the connection established before so that the Consumer does not open a new connection per operation execution +- We want a global media type that behaves the same way as `security` in the root level, i.e. each form that does not have a `contentType` key, uses the one defined globally, somewhere in the root level of the TD. Relevant issues: https://github.com/w3c/wot-thing-description/issues/204 , https://github.com/w3c/wot-binding-templates/issues/357 . Points to pay attention: + - In case of affordances that are incompatible with the global media type, overriding must be mandated. An unstructured data at root level, e.g. jpeg, must be overridden by an affordance that has data schema. + - Negative: Message serialization from TD consumption will be more complex as a preprocessing of the TD is now needed. If there are multiple global media types, referring to them and resolving those will increase the complexity of the preprocessing step. + - Positive: It is easier check for the Consumer, which media types (their decoder/encoder) are needed to be supported to talk to the Thing. Furthermore, as can be understood in the BACnet issue, it is currently not clear that a form requires a media type. This addition can help with this. + - These negative and positive aspects will be visible in other points and can be named "tradeoffs". As mentioned in https://github.com/w3c/wot-thing-description/issues/803#issuecomment-526386771, any optimization of TD instances create more processing need while making them easier to understand and write by humans, at least in simpler cases. + - Linking aspect is common to single connection and single base points + +- We want to support multiple base URIs that behaves the same way as `securityDefinitions` in the root level, where each form can contain a relative URI and refer to a base, like we do now with `security`. Relevant issues: https://github.com/w3c/wot-thing-description/issues/803, https://github.com/w3c/wot-thing-description/issues/878 (starting at https://github.com/w3c/wot-thing-description/issues/878#issuecomment-598714052) + - Proposals are available in #878: on the container structure called `connections`, `endpoints`: https://github.com/w3c/wot-thing-description/issues/878#issuecomment-924158987 + - Proposal about the container at https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825 + - Mention that canonical TDs can contain the expanded forms with everything doubled. This is applicable to global media type mentioned above. + +- An initial connection to the Thing should be expressed somehow. This avoids misinterpretation of reopening a connection twice, when there is no need and gives correct semantics for some protocols. Relevant Issues: #878, #977, #1070, #1242, #1664 + - Proposals are available in #878 to: + - have an `op` value called `open` or a signifier to establish a connection. Consensus from Sept15, 2021 is to not have an op. https://github.com/w3c/wot-thing-description/issues/878#issuecomment-920148181 + - `dependsOn` keyword in non-base forms + - A proposal in #977 shows URL templating to refer to the base connection: https://github.com/w3c/wot-thing-description/issues/977#issuecomment-702397973 + - Proposal in https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825 for linking via pointers and has two proposals + - The Consumer should be smart to not open new connections, even without this. This only makes it clearer for humans and simpler implementations. + - There needs to be a way to signal a connection shared for multiple Things. See #1664. + +- Wrapper Schemas comes into question if all communication over that initial connection follows the same message structure. Related issues https://github.com/w3c/wot-thing-description/issues/878#issuecomment-888433789. This is relevant to global media type and security in a way. Also relates to data mapping. **Notes:** From 1deeeaeb5668aea1fe8517b0ccffb09812bc434d Mon Sep 17 00:00:00 2001 From: egekorkan Date: Thu, 7 Nov 2024 13:58:06 +0000 Subject: [PATCH 11/14] Prettified Code! --- planning/work-items/usability-and-design.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index cea780c1..57334991 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -112,23 +112,26 @@ Related Issues: **Requirements** -- There are 3 main points. Point 2 is about a keyword (more or less), whereas point 3 is more about the underlying mechanism. +- There are 3 main points. Point 2 is about a keyword (more or less), whereas point 3 is more about the underlying mechanism. 1. Having a place to put common connection information 2. Linking to a common connection information. 3. Signaling that a form in an affordance can reuse the connection established before so that the Consumer does not open a new connection per operation execution - We want a global media type that behaves the same way as `security` in the root level, i.e. each form that does not have a `contentType` key, uses the one defined globally, somewhere in the root level of the TD. Relevant issues: https://github.com/w3c/wot-thing-description/issues/204 , https://github.com/w3c/wot-binding-templates/issues/357 . Points to pay attention: + - In case of affordances that are incompatible with the global media type, overriding must be mandated. An unstructured data at root level, e.g. jpeg, must be overridden by an affordance that has data schema. - - Negative: Message serialization from TD consumption will be more complex as a preprocessing of the TD is now needed. If there are multiple global media types, referring to them and resolving those will increase the complexity of the preprocessing step. + - Negative: Message serialization from TD consumption will be more complex as a preprocessing of the TD is now needed. If there are multiple global media types, referring to them and resolving those will increase the complexity of the preprocessing step. - Positive: It is easier check for the Consumer, which media types (their decoder/encoder) are needed to be supported to talk to the Thing. Furthermore, as can be understood in the BACnet issue, it is currently not clear that a form requires a media type. This addition can help with this. - These negative and positive aspects will be visible in other points and can be named "tradeoffs". As mentioned in https://github.com/w3c/wot-thing-description/issues/803#issuecomment-526386771, any optimization of TD instances create more processing need while making them easier to understand and write by humans, at least in simpler cases. - Linking aspect is common to single connection and single base points - We want to support multiple base URIs that behaves the same way as `securityDefinitions` in the root level, where each form can contain a relative URI and refer to a base, like we do now with `security`. Relevant issues: https://github.com/w3c/wot-thing-description/issues/803, https://github.com/w3c/wot-thing-description/issues/878 (starting at https://github.com/w3c/wot-thing-description/issues/878#issuecomment-598714052) + - Proposals are available in #878: on the container structure called `connections`, `endpoints`: https://github.com/w3c/wot-thing-description/issues/878#issuecomment-924158987 - Proposal about the container at https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825 - Mention that canonical TDs can contain the expanded forms with everything doubled. This is applicable to global media type mentioned above. - An initial connection to the Thing should be expressed somehow. This avoids misinterpretation of reopening a connection twice, when there is no need and gives correct semantics for some protocols. Relevant Issues: #878, #977, #1070, #1242, #1664 + - Proposals are available in #878 to: - have an `op` value called `open` or a signifier to establish a connection. Consensus from Sept15, 2021 is to not have an op. https://github.com/w3c/wot-thing-description/issues/878#issuecomment-920148181 - `dependsOn` keyword in non-base forms From 4a3a9e6bd59216da939f580bdc52f1bf971b6dc8 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Thu, 7 Nov 2024 15:44:09 +0100 Subject: [PATCH 12/14] incorporate td call comments --- planning/work-items/usability-and-design.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 57334991..2bd7181f 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -53,12 +53,11 @@ Checking overlaps with architecture. TODOs: - The use case should be linked to the user stories above. -- Bring the text from the issues comments such as https://github.com/w3c/wot-thing-description/issues/1248#issuecomment-2247656558 and -- Move these definitions somewhere: - - Submitter: People who have submitted the user story and thus wants this story to be succesful. +- Move the "Process Stakeholder" definitions somewhere: + - Submitter: People who have submitted the user story, is interested in it and thus wants this story to be succesful. - Specification Writers: People from the TF who want to (or can) work on writing the specification text and corresponding resources. - Implementation Volunteers: People who want to implement this and contribute the results to the implementation report. The submitter is strongly encouraged to provide an implementation result. - - Impacted: Entities that will be impacted by this. Impact type can be "implementation overhead", "security", "privacy", "accesibility" etc. + - Impacted: Entities that will be impacted by this. Impact type can be "implementation overhead", "security", "privacy", "accesibility" etc. and should be prefixed with `-` if it is a negative change, e.g. there is less implementation overhead but privacy issues arise. Some lists to look at: https://w3c.github.io/wot-usecases/#stakeholders , https://w3c.github.io/wot-security/#wot-threat-model-stakeholders **User Stories:** @@ -68,12 +67,14 @@ TODOs: - **What:** Reusable Connection descriptions in a TD - **Why:** Better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) -- Sentence: **As a** deployer of devices with connection oriented protocols, **I need** reusable Connection descriptions in a TD, **so that I can** better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) -- Stakeholders: +- Sentence: **As a** deployer of devices with connection oriented protocols, **I need** reusable connection descriptions in a TD, **so that I can** better describe connection oriented protocols such as MQTT and WebSockets (Problem nb. 4 below) +- Process Stakeholders: - Submitter: Multiple - Specification Writers: Ege Korkan - Implementation Volunteers: Ege Korkan - - Impacted: TD Designers and Consumers. Type: Implementation Overhead + - Impacted People: TD Designers and Consumer application developers. + - Impact Type: Less implementation overhead for TD Designers. More implementation overhead for Consumer application developers for building the request. Less implementation overhead when identifying protocol driver parameters. +- Linked Use Cases or Categories: https://w3c.github.io/wot-usecases/#UC-open-field-agriculture-1 2. Reusable Defaults per TD @@ -81,12 +82,13 @@ TODOs: - **What:** Reusable Connection descriptions in a TD - **Why:** Simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below) -- Sentence: **As a** designer/developer of TDs, **I need** reusable connection descriptions in a TD, **so that I can** simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below). +- Process Sentence: **As a** designer/developer of TDs, **I need** reusable connection descriptions in a TD, **so that I can** simplify TDs in cases without usage of default terms or to avoid redundancy (Problem nb. 1, 2 and 3 below). - Stakeholders: - Submitter: Multiple - Specification Writers: Ege Korkan - Implementation Volunteers: Ege Korkan - Impacted: TD Designers and Consumers. Type: Implementation Overhead +- Linked Use Cases or Categories: Category "Ease of TD writing" to be created **Summarized Problem:** From 9bc888f27db955a76c14dab253a7487b87099d4e Mon Sep 17 00:00:00 2001 From: egekorkan Date: Thu, 7 Nov 2024 14:44:32 +0000 Subject: [PATCH 13/14] Prettified Code! --- planning/work-items/usability-and-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 2bd7181f..10811fc2 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -54,7 +54,7 @@ TODOs: - The use case should be linked to the user stories above. - Move the "Process Stakeholder" definitions somewhere: - - Submitter: People who have submitted the user story, is interested in it and thus wants this story to be succesful. + - Submitter: People who have submitted the user story, is interested in it and thus wants this story to be succesful. - Specification Writers: People from the TF who want to (or can) work on writing the specification text and corresponding resources. - Implementation Volunteers: People who want to implement this and contribute the results to the implementation report. The submitter is strongly encouraged to provide an implementation result. - Impacted: Entities that will be impacted by this. Impact type can be "implementation overhead", "security", "privacy", "accesibility" etc. and should be prefixed with `-` if it is a negative change, e.g. there is less implementation overhead but privacy issues arise. Some lists to look at: https://w3c.github.io/wot-usecases/#stakeholders , https://w3c.github.io/wot-security/#wot-threat-model-stakeholders From 9c4187260a85c99684e7aa3246ba90420e66f563 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Thu, 7 Nov 2024 15:47:49 +0100 Subject: [PATCH 14/14] remove todo item --- planning/work-items/usability-and-design.md | 1 - 1 file changed, 1 deletion(-) diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 10811fc2..3c4f71cf 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -52,7 +52,6 @@ Checking overlaps with architecture. TODOs: -- The use case should be linked to the user stories above. - Move the "Process Stakeholder" definitions somewhere: - Submitter: People who have submitted the user story, is interested in it and thus wants this story to be succesful. - Specification Writers: People from the TF who want to (or can) work on writing the specification text and corresponding resources.