From c32deab22504538d3c08bd37f8ff9271a04accf8 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Fri, 2 Aug 2024 22:26:28 +0200 Subject: [PATCH 1/3] copy folder from wot main repo --- planning/README.md | 91 + planning/work-items/README.md | 4 + .../analysis-historical-data-work-item.md | 64 + planning/work-items/binding-templates.md | 46 + .../images/.$initial-connection.drawio.bkp | 1560 +++++++++++++++++ .../initial-connection-Broker-entities.svg | 3 + ...connection-Broker-lifecycle-connection.svg | 3 + ...nnection-Broker-lifecycle-subscription.svg | 3 + .../initial-connection-Broker-sequence.svg | 3 + .../initial-connection-HTTP-entities.svg | 3 + .../initial-connection-HTTP-lifecycle.svg | 3 + .../initial-connection-HTTP-sequence.svg | 3 + .../initial-connection-OAuth2-entities.svg | 3 + .../initial-connection-OAuth2-lifecycle.svg | 3 + .../initial-connection-OAuth2-sequence.svg | 3 + .../initial-connection-Proxy-entities.svg | 3 + .../initial-connection-Proxy-lifecycle.svg | 4 + .../initial-connection-Proxy-sequence.svg | 4 + .../initial-connection-Websocket-entities.svg | 3 + ...initial-connection-Websocket-lifecycle.svg | 3 + .../initial-connection-Websocket-sequence.svg | 3 + .../images/initial-connection.drawio | 1560 +++++++++++++++++ planning/work-items/new-features.md | 92 + planning/work-items/testing-and-tooling.md | 37 + planning/work-items/usability-and-design.md | 293 ++++ 25 files changed, 3797 insertions(+) create mode 100644 planning/README.md create mode 100644 planning/work-items/README.md create mode 100644 planning/work-items/analysis/analysis-historical-data-work-item.md create mode 100644 planning/work-items/binding-templates.md create mode 100644 planning/work-items/images/.$initial-connection.drawio.bkp create mode 100644 planning/work-items/images/initial-connection-Broker-entities.svg create mode 100644 planning/work-items/images/initial-connection-Broker-lifecycle-connection.svg create mode 100644 planning/work-items/images/initial-connection-Broker-lifecycle-subscription.svg create mode 100644 planning/work-items/images/initial-connection-Broker-sequence.svg create mode 100644 planning/work-items/images/initial-connection-HTTP-entities.svg create mode 100644 planning/work-items/images/initial-connection-HTTP-lifecycle.svg create mode 100644 planning/work-items/images/initial-connection-HTTP-sequence.svg create mode 100644 planning/work-items/images/initial-connection-OAuth2-entities.svg create mode 100644 planning/work-items/images/initial-connection-OAuth2-lifecycle.svg create mode 100644 planning/work-items/images/initial-connection-OAuth2-sequence.svg create mode 100644 planning/work-items/images/initial-connection-Proxy-entities.svg create mode 100644 planning/work-items/images/initial-connection-Proxy-lifecycle.svg create mode 100644 planning/work-items/images/initial-connection-Proxy-sequence.svg create mode 100644 planning/work-items/images/initial-connection-Websocket-entities.svg create mode 100644 planning/work-items/images/initial-connection-Websocket-lifecycle.svg create mode 100644 planning/work-items/images/initial-connection-Websocket-sequence.svg create mode 100644 planning/work-items/images/initial-connection.drawio create mode 100644 planning/work-items/new-features.md create mode 100644 planning/work-items/testing-and-tooling.md create mode 100644 planning/work-items/usability-and-design.md diff --git a/planning/README.md b/planning/README.md new file mode 100644 index 00000000..b2d25032 --- /dev/null +++ b/planning/README.md @@ -0,0 +1,91 @@ +# Thing Description Planning + +In this folder, you can find resources to help with understanding how the next version of the Thing Description deliverable is planned. +First, work items are listed and then a roadmap with priorities is provided per category. + +## Work Items + +### Categories + +The work items are split into four categories. + +1. [Binding Templates](./td-next-work-items/binding-templates.md): The first category is Binding Templates, which involves specifying the mechanism but also the submission mechanism. +2. [Usability and Design](./td-next-work-items/usability-and-design.md): The second category focuses on work items that are more about restructuring, redesigning, and improving the usability of the specification. These could pave the way for new features. +3. [New Features](./td-next-work-items/new-features.md): The third category is about work items that are directly linked to new features. +4. [Testing and Tooling](./td-next-work-items/testing-and-tooling.md): The fourth category is comprised of items that help the specification management and maintain consistency. + +Such categories can be reflected with labels and different views in the GitHub project management panel. +The task force will go through existing issues, pull requests, and discussions, and categorize them accordingly. + +- **Priorities:** The items in each markdown under [td-next-work-items](./td-next-work-items) are a flat list with no priorities set for now. Ideally, items that are dependencies to other items and those with concrete industry use cases will be prioritized. + +- **Details:** The details of different work items can be found at . We will consolidate such details and link them appropriately. + +#### Related Resources + +In addition to GitHub issues and Use Cases, there are various documents that should be read before starting the work + +- Long Running Actions Proposals: +- Registry Analysis: +- Historical Data Landscape: +- Charter Details: + +### Notes + +- The points below are still open to discussion: + - What to do with the existing issues and PRs that are postponed? + - Option 1: If there are no use cases identified, they can be closed after some time. + - What about the work items in the charter or details that are not linked to use cases? + +## Roadmap + +We should have a roadmap for the TD specification that is aligned with the charter start and end dates. +Concrete roadmaps with the order of items are below at [Individual Roadmaps](#individual-roadmaps). + +### Charter-Related Information + +#### WoT WG Charter Details + +- Charter End Date: 2 October 2025 +- CR Transition (feature freeze): July 10, 2025 (worst estimate) +- Charter Start: October 2023 + +#### Schedule for TD Deliverable + +- We will stop work big features 6 months prior to the CR Transition. That means January 10, 2025. In other words, we should be done with big features by the end of 2024. Please see https://github.com/w3c/wot/blob/main/planning/schedule.md +- As a result, we should indicate whether a feature is considered a big feature. Some notes on this: + - The bigger the implementation impact, the more time to implement. + - We can give something like "Story Points" to give a rough idea of the effort. + +### Category-based Roadmaps + +Each section contains a list of work items to be done in an order. + +#### Specification Refactoring + +1. [Incorporating Binding Mechanism](./td-next-work-items/binding-templates.md#binding-templates-integration) +2. [Synchronization with other documents](./td-next-work-items/usability-and-design.md#synchronization-with-other-documents) (might be a long process, so it should happen asynchronously or in the background with syncs in the calls) +3. [Common definitions section](./td-next-work-items/usability-and-design.md#common-definition-section) +4. [Grouping of normative requirements](./td-next-work-items/usability-and-design.md#grouping-of-normative-requirements) +5. [Better Integration of Thing Model](./td-next-work-items/usability-and-design.md#better-integration-of-thing-model) +6. [Security Schemes Refactoring](./td-next-work-items/usability-and-design.md#security-schemes-refactoring) + +#### Specification Tooling + +1. [Specification Generation Tooling](./td-next-work-items/testing-and-tooling.md#spec-generation) +2. [Example reorganization](./td-next-work-items/testing-and-tooling.md#examples-reorganization) + +#### Implementation Report Testing + +1. [Testing Pipeline](./td-next-work-items/testing-and-tooling.md#testing-procedure) (less priority since we are not close to the testing phase at all) + +#### Usability and Design + +An example list of usability and design items with an order: + +- Initial connection +- Data mapping + +#### New Features + +They are not ordered yet. See [here](./td-next-work-items/new-features.md) for more information. diff --git a/planning/work-items/README.md b/planning/work-items/README.md new file mode 100644 index 00000000..65b8f998 --- /dev/null +++ b/planning/work-items/README.md @@ -0,0 +1,4 @@ +# Categorized Work Items + +The documents here detail the work items per category. +The filename is the category name. diff --git a/planning/work-items/analysis/analysis-historical-data-work-item.md b/planning/work-items/analysis/analysis-historical-data-work-item.md new file mode 100644 index 00000000..fcfa0c7e --- /dev/null +++ b/planning/work-items/analysis/analysis-historical-data-work-item.md @@ -0,0 +1,64 @@ +# [DRAFT] Analysis of Historical Data Work Item + +This document gathers all information related to time series or historical data-related topics. +These include issues, use cases, and discussions in other forms. +This document will be worked on before extending the TD specification. + +## Overall Description of the Topic + +Some edge and cloud services can collect property value changes or event emissions for a certain time. +This data, called time series, can be collected by Consumers to display (or use in any other way) the evolution of the affordance data over time. + +This topic is also known as: + +- Time series +- Data Trend + +## Use Cases + +To find the related use cases, the [coverage document](https://github.com/w3c/wot-usecases/blob/main/USE-CASES/coverage.csv) has been used and another pass through the [use cases document](https://w3c.github.io/wot-usecases) has been made. + +- [Smart Agriculture - Greenhouse Horticulture](https://w3c.github.io/wot-usecases/#smart-agriculture) +- [Smart Agriculture - Open-field Agriculture](https://w3c.github.io/wot-usecases/#smart-agriculture-openfield) +- [Smart City - Geolocation](https://w3c.github.io/wot-usecases/#smartcity-geolocation) +- [Smart City - Dashboard](https://w3c.github.io/wot-usecases/#smartcity-dashboard) +- [Smart City - Connected Building Energy Efficiency](https://w3c.github.io/wot-usecases/#connected-building-energy-efficiency) +- [Digital Twin - Digital Twin 2](https://w3c.github.io/wot-usecases/#digital-twin-2) +- [VR/AR - AR Virtual Guide](https://w3c.github.io/wot-usecases/#ar-guide) + +## Issues + +- [Historical Events](https://github.com/w3c/wot-thing-description/issues/892) +- [Historical Property Updates](https://github.com/w3c/wot-thing-description/issues/302#issuecomment-441235444) + +## Other Discussions + +These can be artifacts like presentations, meeting minutes. + +## Identified Requirements + +From the use cases, requirements should be identified. + +## Feature Proposals + +Ideally, the feature can exist only after the requirements are identified. However, if there are proposals already, they can be put here to drive discussions. + +## Existing Solutions + +- [Timeseries Data Submodel Specification at IDTA](https://industrialdigitaltwin.org/wp-content/uploads/2023/03/IDTA-02008-1-1_Submodel_TimeSeriesData.pdf) + - Timepoint (A UTC time) and Duration (time after the start and last measurement) are possible. In Duration, start time is necessary + - TAI and UTC are basic formats. Unix Time, Ephemeris Time (ET) or Barycentric Dynamical Time (TBD) are possible + - Sampling Interval or Rate can be provided as metadata + - Start and End Time can be provided since it also takes past values into account. Accordingly, you can also provide whether it is an ongoing timeseries or a completed one. (Ege: This is probably not relevant for us) + - Last Update can be provided. This is probably a data and not metadata for WoT. We can give guidelines/defaults on this. Normally, it should be equal to the timestamp of the last value. + - Each data blob is called a record. + - First the metadata is defined and then each data point needs to respect to that. Basically, it is like providing a data schema and then the values. +- [InfluxDB Timeseries Data oriented Database](https://www.influxdata.com/) +- [WebThings.io REST API](https://webthings.io/api/#event-resource) +- ECHONET Lite Web API has an extension of the current TD specification on this direction + - WebAPI Specs: https://echonet.jp/wp/wp-content/uploads/pdf/General/Standard/web_api/ECHONET_Lite_Web_API_Specs_v1.1.4_e.pdf + - WebAPI Device Specification: https://echonet.jp/wp/wp-content/uploads/pdf/General/Standard/web_api/ECHONET_Lite_Web_API_Dev_Specs_v1.4.1_e.pdf + +## Reading Resources + +- Overview on Wikipedia: https://en.wikipedia.org/wiki/Time_series diff --git a/planning/work-items/binding-templates.md b/planning/work-items/binding-templates.md new file mode 100644 index 00000000..cfbb07bf --- /dev/null +++ b/planning/work-items/binding-templates.md @@ -0,0 +1,46 @@ +# TD.Next Binding Templates Work Items +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) + +## Binding Submission Mechanism + +We need to specify how a new binding should be submitted. E.g. Registry or a similar approach. +Registry analysis is happening at a separate document. See [Registry Analysis](../../../registry-analysis/). + +Our approach should clarify the following points: + +- Rule-based validation process of the binding document submission (what checks should a submission pass) +- Review process (do we organize special meetings, invite submitters to explain, how do we document it all etc.) +- To be continued + +## Binding Mechanism +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) + +### Binding Templates Integration +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20reorganization) + +Binding Templates core mechanism will be incorporated into the TD document. + +### Payload Driven Protocols +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/data%20mapping) + +Some protocols are built on top of the application layer protocols. Some examples are: + +- RPC protocols on top of HTTP such as JSON-RPC. +- Protocols using MQTT topics together with payloads to identify affordances. +- Websocket sub-protocols. +- SSE usage across implementations. +- Webhook usage across implementations. + +The Thing Description should be updated with mechanisms that make it possible to describe such protocols while optimizing the TD instances to be human and machine readable. +The Binding Templates should be updated with concrete cases where this mechanism is already used. +The Profiles can use this mechanism to reduce the size of TDs while making them easier to understand. +The working group will also document in which cases this method does not work due to making the TDs too complicated to understand, thus requiring a binding document. + +Note: This is dependent on *Reusable TD Elements* of [Usability and Design](./usability-and-design.md) work item list. + +### External Security Ontologies +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) + +Currently security schemes are "baked into" the TD specification but it would be more manageable and consistent to break them out as separate ontologies so that all security schemes would be done via extensions. For protocol-specific security schemes in particular, these should be moved to the Protocol Bindings and ontologies supporting them. The TD 2.0 spec would be updated to only include general-purpose "structural" security schemes and "generic" schemes that apply to all protocols. + +See https://github.com/w3c/wot-charter-drafts/issues/57 , https://github.com/w3c/wot-thing-description/issues/1880 diff --git a/planning/work-items/images/.$initial-connection.drawio.bkp b/planning/work-items/images/.$initial-connection.drawio.bkp new file mode 100644 index 00000000..598f035d --- /dev/null +++ b/planning/work-items/images/.$initial-connection.drawio.bkp @@ -0,0 +1,1560 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/planning/work-items/images/initial-connection-Broker-entities.svg b/planning/work-items/images/initial-connection-Broker-entities.svg new file mode 100644 index 00000000..d6c45747 --- /dev/null +++ b/planning/work-items/images/initial-connection-Broker-entities.svg @@ -0,0 +1,3 @@ + + +
Consumer 1
(MQTT Client)
Consumer 2
(MQTT Client)
Consumer 3
(MQTT Client)
Broker
Thing 1
(MQTT Client)
Thing 2
(MQTT Client)
Thing 3
(MQTT Client)
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Broker-lifecycle-connection.svg b/planning/work-items/images/initial-connection-Broker-lifecycle-connection.svg new file mode 100644 index 00000000..48fda2e1 --- /dev/null +++ b/planning/work-items/images/initial-connection-Broker-lifecycle-connection.svg @@ -0,0 +1,3 @@ + + +
closed
open
1. connect to broker
3. disconnect from broker
2. Topic Subscriptions,
Message Publications
4. turn off device
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Broker-lifecycle-subscription.svg b/planning/work-items/images/initial-connection-Broker-lifecycle-subscription.svg new file mode 100644 index 00000000..cdcde887 --- /dev/null +++ b/planning/work-items/images/initial-connection-Broker-lifecycle-subscription.svg @@ -0,0 +1,3 @@ + + +
inactive
active
1. subscribe to topic
3. unsubscribe from topic
2. Message Receivals
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Broker-sequence.svg b/planning/work-items/images/initial-connection-Broker-sequence.svg new file mode 100644 index 00000000..3d26f469 --- /dev/null +++ b/planning/work-items/images/initial-connection-Broker-sequence.svg @@ -0,0 +1,3 @@ + + +
Consumer
Broker
Thing
Connect
Publish sensorVal
to myTopic 
ACK
no subscribers
Connect
Subscribe to myTopic 
ACK
Measure Sensor
Publish sensorVal
to myTopic 
ACK
send sensorVal 
Unsubscribe from myTopic 
Measure Sensor
Publish sensorVal
to myTopic 
ACK
send sensorVal 
Start Consumer
Program
Use Value
Use Value
a.f[0].op(subscribeevent)
?
Measure Sensor
wait 5 Minutes
Disconnect
a.f[0].op(unsubscribeevent)
?
Measure Sensor
Publish sensorVal
to myTopic 
ACK
no subscribers
Disconnect
Start Thing Program
Start Broker
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-HTTP-entities.svg b/planning/work-items/images/initial-connection-HTTP-entities.svg new file mode 100644 index 00000000..b18ed54a --- /dev/null +++ b/planning/work-items/images/initial-connection-HTTP-entities.svg @@ -0,0 +1,3 @@ + + +
Consumer 1
(HTTP Client)
Thing
(HTTP Server)
Consumer 2
(HTTP Client)
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-HTTP-lifecycle.svg b/planning/work-items/images/initial-connection-HTTP-lifecycle.svg new file mode 100644 index 00000000..53b735da --- /dev/null +++ b/planning/work-items/images/initial-connection-HTTP-lifecycle.svg @@ -0,0 +1,3 @@ + + +
open
5. response
closed
open
1. request
2. response
3. timeout
Connection Lifecycle
4. request
with keep alive
6. max requests
7. timeout
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-HTTP-sequence.svg b/planning/work-items/images/initial-connection-HTTP-sequence.svg new file mode 100644 index 00000000..00154c42 --- /dev/null +++ b/planning/work-items/images/initial-connection-HTTP-sequence.svg @@ -0,0 +1,3 @@ + + +
Consumer
Thing
Handle HTTP Request
readproperty Temperature
(e.g. HTTP GET request)
Get Sensor Reading
Temperature property value
(HTTP response)
Use Sensor Value
Start Consumer
Program
a.f[0].op()
Start HTTP Server
wait 5 Minutes
Handle HTTP Request
readproperty Temperature
(e.g. HTTP GET request)
Get Sensor Reading
Temperature property value
(HTTP response)
Use Sensor Value
a.f[0].op()
End Consumer
Program
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-OAuth2-entities.svg b/planning/work-items/images/initial-connection-OAuth2-entities.svg new file mode 100644 index 00000000..30216897 --- /dev/null +++ b/planning/work-items/images/initial-connection-OAuth2-entities.svg @@ -0,0 +1,3 @@ + + +
Consumer 1
(HTTP client)
Consumer 2
(HTTP client)
Consumer 3
(HTTP client)
Thing 1
(HTTP server)
Thing 2
(HTTP server)
Thing 3
(HTTP server)
Authorization Server
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-OAuth2-lifecycle.svg b/planning/work-items/images/initial-connection-OAuth2-lifecycle.svg new file mode 100644 index 00000000..d22ad9a0 --- /dev/null +++ b/planning/work-items/images/initial-connection-OAuth2-lifecycle.svg @@ -0,0 +1,3 @@ + + +
closed
Token
Obtained
1. ask for authorization
2. Use token inside requests
Expired
3. Logout
5. Request new token with the refresh token
4. Token expires
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-OAuth2-sequence.svg b/planning/work-items/images/initial-connection-OAuth2-sequence.svg new file mode 100644 index 00000000..12c20667 --- /dev/null +++ b/planning/work-items/images/initial-connection-OAuth2-sequence.svg @@ -0,0 +1,3 @@ + + +
Consumer
WoT operation (Token)
Logout Callback
Authorization
Server
Thing
Auth protocol initial call
Token
WoT operation (Token)
introspect
return
return
return
introspect
return
Logout
Start Thing
Initialize interaction
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Proxy-entities.svg b/planning/work-items/images/initial-connection-Proxy-entities.svg new file mode 100644 index 00000000..e6a82c8c --- /dev/null +++ b/planning/work-items/images/initial-connection-Proxy-entities.svg @@ -0,0 +1,3 @@ + + +
Consumer 1
Consumer 2
Consumer 3
Servient(Proxy)
Servient(Thing)
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Proxy-lifecycle.svg b/planning/work-items/images/initial-connection-Proxy-lifecycle.svg new file mode 100644 index 00000000..2c3ecf82 --- /dev/null +++ b/planning/work-items/images/initial-connection-Proxy-lifecycle.svg @@ -0,0 +1,4 @@ + + + +
Proxy-Servient Connection Lifecycle
Proxy-Servient Connection L...
closed
closed
open
open
1. connect to Servient
1. connect...
3. No new requests within the timeout
3. No new requests with...
2. Proxy messages
2. Proxy messagesText is not SVG - cannot display \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Proxy-sequence.svg b/planning/work-items/images/initial-connection-Proxy-sequence.svg new file mode 100644 index 00000000..83f7aee3 --- /dev/null +++ b/planning/work-items/images/initial-connection-Proxy-sequence.svg @@ -0,0 +1,4 @@ + + + +
Consumer
Consumer
a.op.f[0]()
a.op.f[0]()
b.op.f[0]()
b.op.f[0]()
Servient(Proxy)
Servient(Proxy)
Message
Message
return
return
Servient(Thing)
Servient(Thing)
Message (over connection)
Message (over connection)
return (over connection)
return (over connection)
Message
Message
Message (over connection)
Message (over connection)
return (over connection)
return (over connection)
return
return
Persistent Connection
Persistent Connection
within timeout
within timeoutText is not SVG - cannot display \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Websocket-entities.svg b/planning/work-items/images/initial-connection-Websocket-entities.svg new file mode 100644 index 00000000..e6ea2c32 --- /dev/null +++ b/planning/work-items/images/initial-connection-Websocket-entities.svg @@ -0,0 +1,3 @@ + + +
Consumer
(WS client)
Thing
(WS server)
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Websocket-lifecycle.svg b/planning/work-items/images/initial-connection-Websocket-lifecycle.svg new file mode 100644 index 00000000..a2e8249d --- /dev/null +++ b/planning/work-items/images/initial-connection-Websocket-lifecycle.svg @@ -0,0 +1,3 @@ + + +
closed
open
1. connect to remote endpont
3. close
2. Bidirectional communication 
between the endpoints
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection-Websocket-sequence.svg b/planning/work-items/images/initial-connection-Websocket-sequence.svg new file mode 100644 index 00000000..dcd1d982 --- /dev/null +++ b/planning/work-items/images/initial-connection-Websocket-sequence.svg @@ -0,0 +1,3 @@ + + +
Consumer
Thing
WoT operation (Token)
return
Close
Start Thing
Initialize interaction
Close application
return
WoT operation (Token)
wait 5 Minutes
 \ No newline at end of file diff --git a/planning/work-items/images/initial-connection.drawio b/planning/work-items/images/initial-connection.drawio new file mode 100644 index 00000000..e86661f0 --- /dev/null +++ b/planning/work-items/images/initial-connection.drawio @@ -0,0 +1,1560 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/planning/work-items/new-features.md b/planning/work-items/new-features.md new file mode 100644 index 00000000..bbd05c74 --- /dev/null +++ b/planning/work-items/new-features.md @@ -0,0 +1,92 @@ +# TD.Next Feature Aiming Work Items + +For new features (keywords or behavior), a use case (or user story) should exist in the first place. +While the refactoring topics are being worked on, new features should not be incorporated into the specification. +Instead, the TF will analyze current solutions, gather existing use cases and discussions, and write the requirements to shape the feature. +These are contained in this folder with the `analysis-` prefix. + +## Historical Data +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/historical%20data) + +Also known as time series. + +Please refer to [Analysis Document](./../analysis-historical-data-work-item.md) + +## Manageable Affordances +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/manageable%20affordances) + +Note: This should be moved to an analysis document. + +Various use cases require the implementation of more complex actions that span multiple protocol transactions. Such actions are not simply invoked but need to managed over time by the Thing and the Consumer. +These are covered in the WoT Thing Description 1.1 via the initiation (invokeaction), monitoring (`queryaction`), and cancellation (`cancelaction`) of ongoing actions. +However, the following points are not supported: + +- Sent and received payloads associated to the operations +- Management of dynamically generated identification +- Describing queues of actions + +These limitations are also influencing the Profiles. + +Additionally, there have been proposals by the WG members that need to taken into account and evaluated: + +- +- +- + +Related Issues: + +- +- +- + +## Streaming +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/streaming) + +Note: This should be moved to an analysis document. + +A streaming protocol establishes an ongoing connection supporting delivery of time-sensitive information such as audio or video. +Note that this connection in general may be over either reliable (TCP) or unreliable (UDP) transports, or over a combination, and may also support encryption or content management. +Streaming may also be used to support other kinds of ongoing time-sensitive data delivery. + +While related to event notification mechanisms, streaming in practice is supported by a specific set of protocols such as RTSP, HLS, DASH, MSE, WebRTC, etc. +This work item would add any infrastructure needed to TDs in order to support streaming protocol bindings generally, for example, by adding additional subprotocols supporting stream publication and subscription management (if needed). + +In order to clearly define what infrastructure is actually needed, if any, one or more concrete streaming protocol bindings should also be attempted, such as [RTSP](https://w3c.github.io/wot-charter-drafts/wot-wg-2023-details.html#rtsp-binding-workitem). + +## Signing and Canonicalization + +Note: This should be moved to an analysis document. + +### Signing +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/signing) + +Mechanisms for signing TDs documents were under discussion in the last charter but were not mature enough to include. +Adding support for TD canonicalization and signing would be helpful to ensure that TDs are not intercepted and modified by third parties. +Verifying a signature requires identity management, i.e. the verifier needs to know or have trusted access to the public key of the signer. +Directories need to be extended to verify signatures and generate new chained signatures as needed. + +### Canonicalization +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/canonicaliziation) + +Thing Descriptions can contain the same information but serialized differently even in the same serialization format, due to structures such as maps which do not impose an order. +This is problematic for comparing TDs or more importantly, for signing them where every byte difference results in a different signature. +Thus, the WG will develop a canonicalization algorithm based on JSON-LD. + +Related Issues: + +- +- + +Some work has been done in the previous charter but has been postponed due to lack of features in JSON-LD. Related PRs: + +- +- +- +- + +### TD Versioning +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/versioning) + +Note: This should be moved to an analysis document. + +Explain the semantics on how to version Thing Descriptions. diff --git a/planning/work-items/testing-and-tooling.md b/planning/work-items/testing-and-tooling.md new file mode 100644 index 00000000..00ac3253 --- /dev/null +++ b/planning/work-items/testing-and-tooling.md @@ -0,0 +1,37 @@ +# TD.Next Testing and Tooling Work Items + +## Linting +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/linting) + +Linting rules exist for programming languages or for API specifications in order to establish custom rules within projects. +How these rules can be defined for TDs is not specified in any way, making it difficult to constrain flexibility of TDs in a standardized manner. +The WG will define the mechanism for linting TDs together with optional rules that can be used by different projects. + +Related Issues: + +- +- +- + +## Testing Procedure +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Testing) + +Currently it is at Eclipse Thingweb Playground at but we should move it here. + +## Bugfixes +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/bug) + +Small updates for the TD next. Actual bugs for 1.1 should be handled as errata + +## Examples Reorganization + +It would be better to have complete TD examples that can be validated but at the same time we can show a part of it for specific features. +Also, see . + +## Spec Generation +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Tooling) + +Single source of truth for specification generation. + +- Reducing the amount of documents that we need to maintain. +- Make sure there are no gaps in the tooling and process for building index.html diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md new file mode 100644 index 00000000..6cf1ae62 --- /dev/null +++ b/planning/work-items/usability-and-design.md @@ -0,0 +1,293 @@ +# TD.Next Usability and Design Work Items + +Changes that improve readability, the usability of the specification OR development, spec generation, bug fixes, and testing of the specification do not need use cases. +These have more priority since they can impact how new features look like in a TD instance. + +## Design Document + +We should start a TD (re)design document that explains the idea behind the design of different features. See [issue 1889](https://github.com/w3c/wot-thing-description/issues/1889). + +## Document reorganization +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20reorganization) + +Changes that should be done while keeping the current content + +### Common Definition Section + +Usability and readability improvements for not needing to "jump around" while reading + +### Grouping of Normative Requirements + +Making sure that important normative text is not scattered around too much. + +### Assertion id Alignment + +Adding `td`, checking naming scheme + +### Better Integration of Thing Model + +There were questions about how much a TM is related to the TD. +Some discussion might be needed. + +## Synchronization with Other Documents +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20synchronisation) + +### Discovery Sync + +Moving discovery-related text from TD to Discovery + +### Architecture Sync + +Checking overlaps with architecture. + +## Reusable TD Elements +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable+elements) + +### Reusable Connections +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20connections) + +**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 + +Related Issues: + +- Umbrella Issue: +- Media Type and Security Override: : Sharing a media type and security (already possible) among forms +- Single base with multiple protocols: : Having the same feature as the `security` term in form protocols +- Reused Connection: : Implying a first connection that is not dropped but actually reused later +- Out-of-band IP address: : Sort of related. Deducing the IP address from an out-of-band way +- Reused Connection in WS: : Similar issue to 878 but giving more details on WebSocket +- Linking to Initial Connection: : Similar issue to 803. +- Reused Connection in WS 2: : Similar issue to 878 abd 1070 +- Linking to Initial Connection 2: : Similar issue to 803 and 1242 + +**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, but we need to make sure not to include privacy or security risks + - The initial connection must not be mandatory to establish upon TD consumption and should left to the implementation when to establish and close it. + +**Notes:** + +- When to close the connection needs to be discussed. +- Complex security mechanisms exchange should be handled at the same time + +#### Examples of Message Sequences + +##### Simple HTTP Connection + +###### Participating Entities + +![Participating Entities](./images/initial-connection-HTTP-entities.svg) + +In this case, the Thing has enough resources and contains its own HTTP server. + +###### Lifecycle of a Connection + +![Lifecycle of a Connection](./images/initial-connection-HTTP-lifecycle.svg) + +1. A request from the client opens the connection to the server. +2. A response from the server back to the client closes the connection. +3. If the server provides no response in a given time interval, a timeout occurs and the connection is closed. +4. Alternatively, a request can be sent with Keep Alive parameters (timeout and max requests parameters). +5. In this case, the responses back to the client will not close the connection. +6. If a certain amount of requests have been sent, the connection will be closed. +7. If a certain time is reached, the connection will be closed. + +###### Message Sequence + +![Message Sequence](./images/initial-connection-HTTP-sequence.svg) + +We note that even with Keep Alive option set, the interaction pattern do not change in the application level. +Thus, keep alive can be seen as an optimization and not a different way to interact. + +##### Broker Connections without Security + +###### Participating Entities + +![Participating Entities](./images/initial-connection-Broker-entities.svg) + +Typically, the broker is a separate entity than the Thing. + +###### Lifecycle of a Connection + +![Lifecycle of a Connection](./images/initial-connection-Broker-lifecycle-connection.svg) + +1. A client connects to the broker and opens a consistent connection. +2. Client can subscribe or publish to topics as long as the connection is active. +3. Client can disconnect from the broker and close the connection. +4. If the device turns off or has an error, the connection can be closed. + +###### Lifecycle of a Subscription + +![Lifecycle of a Subscription](./images/initial-connection-Broker-lifecycle-subscription.svg) + +1. A Client already connected to the broker (open connection), can subscribe to a topic where that subscription becomes active. +2. Multiple messages can be received while the subscription is active. +3. Once the client unsubscribes from the topic, the subscription becomes inactive. + +###### Message Sequence + +![Message Sequence](./images/initial-connection-Broker-sequence.svg) + +We note that, even after a time has passed, the connection stays open and the subscription stays active. +The client id is used in a connection but is typically not exposed to the application layer. + +##### Basic WebSocket Connections + +###### Participating Entities + +![Participating Entities](./images/initial-connection-Websocket-entities.svg) + +In this case, the Thing has enough resources and contains its own WebSocket server. + +###### Lifecycle of a Connection + +![Lifecycle of a Websocket connection](./images/initial-connection-Websocket-lifecycle.svg) + +The lifecycle of a WebSocket connection in the Web of Things typically includes the following stages: + +1. **Connection Establishment**: The client initiates a handshake request to the server, which responds with a handshake response, establishing a persistent connection. +2. **Data Transmission**: Once connected, the client and server can exchange data bi-directionally in real-time, with messages sent as frames. This may include ping/pong frames to keep understand connection "liveness" between the parties. +3. **Connection Closure**: Either party can initiate the closing handshake by sending a close frame, after which the connection is terminated, and resources are released. + + +###### Message Sequence + +![Message Sequence](./images/initial-connection-Websocket-sequence.svg) + +##### OAuth2-based Interaction + +###### Participating Entities + +![Participating Entities](./images/initial-connection-OAuth2-entities.svg) + +In this case, the Thing has enough resources and contains its own HTTP server. + +###### Lifecycle of a Session + +![Lifecycle of a Oauth Session](./images/initial-connection-OAuth2-lifecycle.svg) + +The lifecycle of an OAuth token in a session involves the following stages: + +1. **Token Request and authorization**: The client requests an access token from the authorization server, typically after authenticating and obtaining user consent. +2. **Token Use**: The client uses the access token to access protected resources on the resource server by including it in API requests. +3. **Logout**: The client or authorization server can revoke tokens to terminate the session, preventing further access. +4. **Token Expiry and Refresh**: Access tokens are time-limited. If a refresh token is available, the client can request a new access token without user reauthorization. + +###### Message Sequence + +![Message Sequence](./images/initial-connection-OAuth2-sequence.svg) + +##### Proxy-based Communication + +###### Participating Entities + +![Participating Entities](./images/initial-connection-Proxy-entities.svg) + +In this case, the Thing has enough resources and contains its own HTTP server. + +###### Lifecycle of a Connection + +![Lifecycle of a Proxy](./images/initial-connection-Proxy-lifecycle.svg) + +###### Message Sequence + +![Message Sequence](./images/initial-connection-Proxy-sequence.svg) + +### Data Schema Mapping + +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/data%20mapping) + +Also known as: Mapping TD elements to messages + +- Some protocols have a main channel and auxiliary/ancillary/side channels to exchange information, e.g HTTP has Headers, URI-Variables, Payload/Body. +- Some protocols may have a default/unique `contentType` for at least one of the channels, others are fixed or flexible. e.g. HTTP Headers are key-value strings, Modbus uses only boolean and 16bit quantities. +- Some protocols do not have the concept of `contentType` at all. +- Some `contentType` may be more expressive than our DataSchema, e.g. CBOR [Maps with integer keys](https://www.rfc-editor.org/rfc/rfc8949.html#map-keys). + +#### Open questions +- How can we describe how the logical information (state for property, input/output messages for actions, messages for event) is mapped to each channel? +- Do we need to reconsider how we express `contentType` and `contentCoding` in the case more than a channel allows flexible data formats? +- Do we want to provide a way to express a serialization scheme for protocols that have only inflexible (e.g. binary-only) channels, without going through the route of declaring a `contentType`? +- Do we want to provide a way to express a serialization scheme between our DataSchema and richer contentTypes (e.g XML, CBOR)? + +#### Related Issues: +- [BACnet URI Variables discussion](https://github.com/w3c/wot-binding-templates/issues/302) +- [Complex data types in simple protocols](https://github.com/w3c/wot-thing-description/issues/1936) +- [jsonrpc-over-websocket](https://github.com/w3c/wot-binding-templates/issues/125) +- [xml binding discussion](https://github.com/w3c/wot-binding-templates/issues/139) +- [cbor analysis](https://github.com/w3c/wot-binding-templates/issues/8) +- [initial issue with this](https://github.com/w3c/wot-binding-templates/issues/219) +- [aka payload pattern](https://github.com/w3c/wot-thing-description/issues/1217) +- [HTTP Headers in directory exploration (Problem 2)](https://github.com/eclipse-thingweb/node-wot/issues/1221) + +### Security Schemes Refactoring +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) + +The need to be refactored and use the same pattern as other reusable elements + +Relevant discussions: + +- https://github.com/w3c/wot-thing-description/issues/1394 + +### Inline Security +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20elements) + +Simplifying the way to describe security when there is only one mechanism needed to be described (in contrast to needing two terms at the moment) + +Relevant discussions: + +- https://github.com/w3c/wot-thing-description/pull/945 + +### Reusable Element Design +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) + +Scenarios, requirements, and use the same pattern for all reusable elements. +This will influence the items above. + +Related discussions: + +- https://github.com/w3c/wot-thing-description/pull/1341 (but many are linked here as well) + +## Affordance Uniformity +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/affordance%20uniformity) + +Uniform pattern/state machines between Actions, Events, and Properties. + +- Avoid doing the same thing in a different way, for example how to express observability and cancellation +- Relationships across affordances, for example when an Action changes the state of a Property +- Property vs. Action (also URI Variables redesign question) + +## Normative Parsing, Validation, Consumption +![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Validation) + +Currently, the TD specification defines an abstract information model and a default JSON serialization for TDs. +However, parsing, consuming and validating TDs are not normatively defined. +A validation process is defined but is not normative, which leads to certain ambiguities for a Consumer parsing a TD. +Additionally, no method is proposed for validation of the extensions that are used via the prefixes and the @context. +The WG will specify normative algorithms for parsing, consuming and validating TDs to ensure interoperability of Consumers. + +### TD Validation + +What is a valid TD, are there any levels of validness? + +- A TD validator can do only JSON Schema validation but that is not enough to test everything. +- A TD may be not completely valid but usable by a "degraded consumer" (see below) or a TD can be completely valid according to all the assertions and protocol bindings but not be usable by some consumers. + +Additionally, we need better validation of protocols and associated security in the TD. + +### Consumption Rules + +Do we want to prescribe how TDs are processed and consumed beyond the text level? + +### Degraded Consumption + +- Rule for uniform degradation across consumers, e.g. TD too big, protocol or protocol options unknown, contentType unknown, etc. From 287e1e03788f180cd42b1f828135c8ddf1109919 Mon Sep 17 00:00:00 2001 From: egekorkan Date: Fri, 2 Aug 2024 20:27:21 +0000 Subject: [PATCH 2/3] Prettified Code! --- .../analysis/analysis-historical-data-work-item.md | 2 +- planning/work-items/binding-templates.md | 9 +++++++-- planning/work-items/new-features.md | 10 ++++++++-- planning/work-items/testing-and-tooling.md | 8 ++++++-- planning/work-items/usability-and-design.md | 12 +++++++++++- 5 files changed, 33 insertions(+), 8 deletions(-) diff --git a/planning/work-items/analysis/analysis-historical-data-work-item.md b/planning/work-items/analysis/analysis-historical-data-work-item.md index fcfa0c7e..b59c6874 100644 --- a/planning/work-items/analysis/analysis-historical-data-work-item.md +++ b/planning/work-items/analysis/analysis-historical-data-work-item.md @@ -52,7 +52,7 @@ Ideally, the feature can exist only after the requirements are identified. Howev - Start and End Time can be provided since it also takes past values into account. Accordingly, you can also provide whether it is an ongoing timeseries or a completed one. (Ege: This is probably not relevant for us) - Last Update can be provided. This is probably a data and not metadata for WoT. We can give guidelines/defaults on this. Normally, it should be equal to the timestamp of the last value. - Each data blob is called a record. - - First the metadata is defined and then each data point needs to respect to that. Basically, it is like providing a data schema and then the values. + - First the metadata is defined and then each data point needs to respect to that. Basically, it is like providing a data schema and then the values. - [InfluxDB Timeseries Data oriented Database](https://www.influxdata.com/) - [WebThings.io REST API](https://webthings.io/api/#event-resource) - ECHONET Lite Web API has an extension of the current TD specification on this direction diff --git a/planning/work-items/binding-templates.md b/planning/work-items/binding-templates.md index cfbb07bf..0be6257a 100644 --- a/planning/work-items/binding-templates.md +++ b/planning/work-items/binding-templates.md @@ -1,4 +1,5 @@ # TD.Next Binding Templates Work Items + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ## Binding Submission Mechanism @@ -13,14 +14,17 @@ Our approach should clarify the following points: - To be continued ## Binding Mechanism + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ### Binding Templates Integration + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20reorganization) Binding Templates core mechanism will be incorporated into the TD document. ### Payload Driven Protocols + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/data%20mapping) Some protocols are built on top of the application layer protocols. Some examples are: @@ -31,14 +35,15 @@ Some protocols are built on top of the application layer protocols. Some example - SSE usage across implementations. - Webhook usage across implementations. -The Thing Description should be updated with mechanisms that make it possible to describe such protocols while optimizing the TD instances to be human and machine readable. +The Thing Description should be updated with mechanisms that make it possible to describe such protocols while optimizing the TD instances to be human and machine readable. The Binding Templates should be updated with concrete cases where this mechanism is already used. The Profiles can use this mechanism to reduce the size of TDs while making them easier to understand. The working group will also document in which cases this method does not work due to making the TDs too complicated to understand, thus requiring a binding document. -Note: This is dependent on *Reusable TD Elements* of [Usability and Design](./usability-and-design.md) work item list. +Note: This is dependent on _Reusable TD Elements_ of [Usability and Design](./usability-and-design.md) work item list. ### External Security Ontologies + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) Currently security schemes are "baked into" the TD specification but it would be more manageable and consistent to break them out as separate ontologies so that all security schemes would be done via extensions. For protocol-specific security schemes in particular, these should be moved to the Protocol Bindings and ontologies supporting them. The TD 2.0 spec would be updated to only include general-purpose "structural" security schemes and "generic" schemes that apply to all protocols. diff --git a/planning/work-items/new-features.md b/planning/work-items/new-features.md index bbd05c74..b0e2dfdf 100644 --- a/planning/work-items/new-features.md +++ b/planning/work-items/new-features.md @@ -6,6 +6,7 @@ Instead, the TF will analyze current solutions, gather existing use cases and di These are contained in this folder with the `analysis-` prefix. ## Historical Data + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/historical%20data) Also known as time series. @@ -13,11 +14,12 @@ Also known as time series. Please refer to [Analysis Document](./../analysis-historical-data-work-item.md) ## Manageable Affordances + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/manageable%20affordances) Note: This should be moved to an analysis document. -Various use cases require the implementation of more complex actions that span multiple protocol transactions. Such actions are not simply invoked but need to managed over time by the Thing and the Consumer. +Various use cases require the implementation of more complex actions that span multiple protocol transactions. Such actions are not simply invoked but need to managed over time by the Thing and the Consumer. These are covered in the WoT Thing Description 1.1 via the initiation (invokeaction), monitoring (`queryaction`), and cancellation (`cancelaction`) of ongoing actions. However, the following points are not supported: @@ -40,11 +42,12 @@ Related Issues: - ## Streaming + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/streaming) Note: This should be moved to an analysis document. -A streaming protocol establishes an ongoing connection supporting delivery of time-sensitive information such as audio or video. +A streaming protocol establishes an ongoing connection supporting delivery of time-sensitive information such as audio or video. Note that this connection in general may be over either reliable (TCP) or unreliable (UDP) transports, or over a combination, and may also support encryption or content management. Streaming may also be used to support other kinds of ongoing time-sensitive data delivery. @@ -58,6 +61,7 @@ In order to clearly define what infrastructure is actually needed, if any, one o Note: This should be moved to an analysis document. ### Signing + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/signing) Mechanisms for signing TDs documents were under discussion in the last charter but were not mature enough to include. @@ -66,6 +70,7 @@ Verifying a signature requires identity management, i.e. the verifier needs to k Directories need to be extended to verify signatures and generate new chained signatures as needed. ### Canonicalization + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/canonicaliziation) Thing Descriptions can contain the same information but serialized differently even in the same serialization format, due to structures such as maps which do not impose an order. @@ -85,6 +90,7 @@ Some work has been done in the previous charter but has been postponed due to la - ### TD Versioning + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/versioning) Note: This should be moved to an analysis document. diff --git a/planning/work-items/testing-and-tooling.md b/planning/work-items/testing-and-tooling.md index 00ac3253..6958e959 100644 --- a/planning/work-items/testing-and-tooling.md +++ b/planning/work-items/testing-and-tooling.md @@ -1,10 +1,11 @@ # TD.Next Testing and Tooling Work Items ## Linting + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/linting) -Linting rules exist for programming languages or for API specifications in order to establish custom rules within projects. -How these rules can be defined for TDs is not specified in any way, making it difficult to constrain flexibility of TDs in a standardized manner. +Linting rules exist for programming languages or for API specifications in order to establish custom rules within projects. +How these rules can be defined for TDs is not specified in any way, making it difficult to constrain flexibility of TDs in a standardized manner. The WG will define the mechanism for linting TDs together with optional rules that can be used by different projects. Related Issues: @@ -14,11 +15,13 @@ Related Issues: - ## Testing Procedure + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Testing) Currently it is at Eclipse Thingweb Playground at but we should move it here. ## Bugfixes + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/bug) Small updates for the TD next. Actual bugs for 1.1 should be handled as errata @@ -29,6 +32,7 @@ It would be better to have complete TD examples that can be validated but at the Also, see . ## Spec Generation + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Tooling) Single source of truth for specification generation. diff --git a/planning/work-items/usability-and-design.md b/planning/work-items/usability-and-design.md index 6cf1ae62..2badfe55 100644 --- a/planning/work-items/usability-and-design.md +++ b/planning/work-items/usability-and-design.md @@ -8,6 +8,7 @@ These have more priority since they can impact how new features look like in a T We should start a TD (re)design document that explains the idea behind the design of different features. See [issue 1889](https://github.com/w3c/wot-thing-description/issues/1889). ## Document reorganization + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20reorganization) Changes that should be done while keeping the current content @@ -30,6 +31,7 @@ There were questions about how much a TM is related to the TD. Some discussion might be needed. ## Synchronization with Other Documents + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/document%20synchronisation) ### Discovery Sync @@ -41,9 +43,11 @@ Moving discovery-related text from TD to Discovery Checking overlaps with architecture. ## Reusable TD Elements + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable+elements) ### Reusable Connections + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20connections) **Problem:** @@ -158,7 +162,6 @@ The lifecycle of a WebSocket connection in the Web of Things typically includes 2. **Data Transmission**: Once connected, the client and server can exchange data bi-directionally in real-time, with messages sent as frames. This may include ping/pong frames to keep understand connection "liveness" between the parties. 3. **Connection Closure**: Either party can initiate the closing handshake by sending a close frame, after which the connection is terminated, and resources are released. - ###### Message Sequence ![Message Sequence](./images/initial-connection-Websocket-sequence.svg) @@ -214,12 +217,14 @@ Also known as: Mapping TD elements to messages - Some `contentType` may be more expressive than our DataSchema, e.g. CBOR [Maps with integer keys](https://www.rfc-editor.org/rfc/rfc8949.html#map-keys). #### Open questions + - How can we describe how the logical information (state for property, input/output messages for actions, messages for event) is mapped to each channel? - Do we need to reconsider how we express `contentType` and `contentCoding` in the case more than a channel allows flexible data formats? - Do we want to provide a way to express a serialization scheme for protocols that have only inflexible (e.g. binary-only) channels, without going through the route of declaring a `contentType`? - Do we want to provide a way to express a serialization scheme between our DataSchema and richer contentTypes (e.g XML, CBOR)? #### Related Issues: + - [BACnet URI Variables discussion](https://github.com/w3c/wot-binding-templates/issues/302) - [Complex data types in simple protocols](https://github.com/w3c/wot-thing-description/issues/1936) - [jsonrpc-over-websocket](https://github.com/w3c/wot-binding-templates/issues/125) @@ -230,6 +235,7 @@ Also known as: Mapping TD elements to messages - [HTTP Headers in directory exploration (Problem 2)](https://github.com/eclipse-thingweb/node-wot/issues/1221) ### Security Schemes Refactoring + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Binding) The need to be refactored and use the same pattern as other reusable elements @@ -239,6 +245,7 @@ Relevant discussions: - https://github.com/w3c/wot-thing-description/issues/1394 ### Inline Security + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/reusable%20elements) Simplifying the way to describe security when there is only one mechanism needed to be described (in contrast to needing two terms at the moment) @@ -248,6 +255,7 @@ Relevant discussions: - https://github.com/w3c/wot-thing-description/pull/945 ### Reusable Element Design + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Security) Scenarios, requirements, and use the same pattern for all reusable elements. @@ -258,6 +266,7 @@ Related discussions: - https://github.com/w3c/wot-thing-description/pull/1341 (but many are linked here as well) ## Affordance Uniformity + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/affordance%20uniformity) Uniform pattern/state machines between Actions, Events, and Properties. @@ -267,6 +276,7 @@ Uniform pattern/state machines between Actions, Events, and Properties. - Property vs. Action (also URI Variables redesign question) ## Normative Parsing, Validation, Consumption + ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/Validation) Currently, the TD specification defines an abstract information model and a default JSON serialization for TDs. From a975b0fcca540b31afc914e0013a567eabd20e7b Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Tue, 6 Aug 2024 11:47:02 +0200 Subject: [PATCH 3/3] ignore bkp files from drawio --- .gitignore | 3 +- .../images/.$initial-connection.drawio.bkp | 1560 ----------------- 2 files changed, 2 insertions(+), 1561 deletions(-) delete mode 100644 planning/work-items/images/.$initial-connection.drawio.bkp diff --git a/.gitignore b/.gitignore index a61e0bbe..ffcd24bc 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ node_modules .install visualization/*.dot -visualization/json-schema.svg \ No newline at end of file +visualization/json-schema.svg +*.drawio.bkp diff --git a/planning/work-items/images/.$initial-connection.drawio.bkp b/planning/work-items/images/.$initial-connection.drawio.bkp deleted file mode 100644 index 598f035d..00000000 --- a/planning/work-items/images/.$initial-connection.drawio.bkp +++ /dev/null @@ -1,1560 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -