Restructure WoT Core Profile section #78

benfrancis · 2021-04-22T14:35:18Z

In #73 we have discussed reducing the scope of the Core Profile (name TBD #21) to focus on interoperability and no longer try to meet requirements around human readability and constrained devices (which often conflict with each other).

This PR therefore proposes modifying the WoT Core Profile to:

Remove the WoT Core Data Model section for the reasons described in Refine Goals and Scope #73 (comment) and Reduce or remove the constraints in section 7.2 Baseline Information Model #10
Remove the External TD representations section since JSON serialisation, optional JSON-LD semantic annotations and canonicalization will be defined in the Thing Desciption specification
Add new sub-sections to the WoT Core Profile:
1. Identifier - an identifier to denote that a given Thing Description conforms to the Core Profile
2. Links - link relation types which conformant Web Things MAY use and conformant Consumers MUST support
3. Security - security schemes which conformant Web Things MAY support and conformant Consumers MUST support
4. Discovery - discovery mechanisms which conformant Web Things MAY support and conformant Consumers MUST support

A follow-up PR would be required to update the Introduction, Conformance and Profiling Mechanism sections to reflect these changes.

Note: This is a companion to #77 which proposes a new Protocol Binding section

Preview | Diff

sebastiankb · 2021-04-23T14:24:44Z

index.html

+    <!-- Identifier -->
+    <section id="identifier">
+      <h3>Identifier</h3>
+      <p class="ednote">


should be in sync with w3c/wot-thing-description#806

If profile is defined in the Thing Description specification, do you think this section is still needed in the Profile specification? Or should the Profile specification just refer to the relevant section of the Thing Description specification in its introduction for example?

~~Is anyone working on a PR for w3c/wot-thing-description#806 yet?~~

Edit: Comment moved to #79 (comment)

This section would just define a URI like https://www.w3.org/2021/wot/profile/common, which presumably doesn't need to be included in the Thing Description specification.

egekorkan · 2021-04-26T11:02:58Z

A question about links, what does it mean to support a link relation type? Any Consumer can go to that link just by following it. Does it mean that if there is a link that means a user interface, the Consumer MUST have a rendering engine to display it?

benfrancis · 2021-04-28T12:25:05Z

A question about links, what does it mean to support a link relation type? Any Consumer can go to that link just by following it. Does it mean that if there is a link that means a user interface, the Consumer MUST have a rendering engine to display it?

That's a good question. Perhaps in that case support should not be mandatory.

In the web interface of WebThings Gateway these types of links are just rendered as an icon with a hyperlink which when clicked opens the custom HTML user interface of a Thing in a new tab, but it's possible some Consumers may not have a user interface at all.

I've updated that text (which is so far just an editor's note) to say MAY instead of MUST.

mmccool · 2021-04-29T13:25:16Z

We probably need to look at links on a case-by-case basis. Note also that actually following links is a potential privacy risk, so generally we should try to make TDs self-contained. Note that some links may also point back to the same source as the TD, eg for icons. These "same-source" links would be safer wrt to privacy. An alternative would be to embed such resources in the TD somehow, and maybe allow links to use a local json-pointer (of course binary data would need to be base-64 encoded or something).

Hmm. Maybe directories should cache resources like icons? I'll have to think about that.

benfrancis · 2021-07-22T10:24:00Z

I have rebased this pull request to resolve merge conflicts and modified it to keep the list of required security schemes from the Core Data Model in the Core Profile security section.

@mlagally This pull request is 3 months old today, it would be great to discuss it in today's WoT Architecture call if possible.

mlagally · 2021-07-26T14:47:59Z

@benfrancis
I already commented on the datamodel section that you deleted in the last architecture call and explained why we need it.

We agreed to prioritize interoperability over human readability, so the normative requirements of that section, that relate to human readability should be moved to the "recommended practice" sections of the corresponding subchapters.
This could be handled in a separate PR.

The additional text you created should be moved into a stand-alone pull request to make sure we can handle it separately and include it into the document in due course.

benfrancis · 2021-07-26T16:54:00Z

@mlagally wrote:

I already commented on the datamodel section that you deleted in the last architecture call and explained why we need it.

We agreed to prioritize interoperability over human readability, so the normative requirements of that section, that relate to human readability should be moved to the "recommended practice" sections of the corresponding subchapters.
This could be handled in a separate PR.

As discussed in the Architecture call on 22nd July, we agreed in #73 to reduce the scope of the Core Profile from its previous goals of:

Interoperability
Human readability
Supporting constrained devices

to focus only on the goal of interoperability.

I am arguing that none of the constraints proposed in the current Core Profile Data Model section are needed for interoperability and only contribute to human readability and supporting constrained devices, and therefore the whole section should be removed. If there are any constraints or recommendations which we agree should apply to all web things, then I am suggesting they should be added to the Thing Description specification rather than the Core Profile.

I previously asked you for specific examples of constraints you felt needed to be kept and I responded to those specific points in #73 (comment), explaining why I don't think they help interoperability and in some cases may even harm interoperability. If you still believe there are specific constraints that should be kept because they contribute to interoperability, can you please either explain that here or by responding in #73.

benfrancis · 2021-07-26T17:08:53Z

The additional text you created should be moved into a stand-alone pull request to make sure we can handle it separately and include it into the document in due course.

I also explained on the call that it doesn't really make sense for the proposed new sections to be added in a separate PR, because they don't make sense without the other changes. E.g.:

The Links section contradicts current text in the Data Model section
The Security section replaces current text in the Data Model section

mlagally · 2021-11-04T11:22:09Z

index.html

-        </section>
-      </section>
-
+    This section defines the <a>Core Profile</a> by describing:


The new language should be added, however removing the core data model is not appropriate, since it will break profile use cases.

We discussed the use cases and motivation for the common data model in the October vF2F. Please see presentation slides: https://github.com/w3c/wot/blob/main/PRESENTATIONS/2021-10-online-f2f/2021-10-27-WoT-F2F-Architecture%2BProfiles-Lagally.pdf

@mlagally I apologise for not being able to attend that meeting due to illness, but I see nothing in that presentation which convinces me that the data model constraints proposed in the current WoT Core Data Model section are necessary, or helpful. Please see my extensive comments in #93 (review) from July in which I reiterate why I think they are undesirable and in some cases conflict with the agreed goal of the specification. Ege has said he agrees with those comments, and I note that you haven't yet responded to them.

I get the impression that you are the only member of the group who thinks that including these data model constraints in the Core Profile is a good idea, and that the majority of members of the group actually think that the majority of the proposed constraints aren't necessary. I am happy to continue to discuss this further to try to reach a consensus, but if we can't reach a consensus then according to the Working Group's decision policy, I understand the Chairs may call for a group vote.

mlagally · 2021-11-04T11:22:21Z

index.html

@@ -416,60 +402,6 @@ <h4 id="additional-definitions-">Additional Definitions:</h4>
      <dd>
        The Web of Things Thing Description as defined in [[wot-thing-description]].
      </dd>


Agree to remove.

mlagally · 2021-11-04T11:22:45Z

index.html

@@ -386,18 +384,6 @@ <h4 id="additional-definitions-">Additional Definitions:</h4>
      <dd>
        Synonym for <a>WoT Core Profile</a>.
      </dd>


agree to remove

mlagally · 2021-11-04T11:23:20Z

index.html

@@ -198,8 +198,6 @@ <h3>Motivation for a Profile</h3>
  <section id='sotd'></section>

  <section id="intro">


Why do you want to remove a h1 heading?

It's already commented out, this is just cleanup :)

(Same with the previous two removals)

mlagally · 2021-11-04T11:26:33Z

index.html

+    <section id="identifier">
+      <h3>Identifier</h3>
+      <p class="ednote">
+        This section will define an identifier which can be included in a


text should be added

mlagally · 2021-11-04T11:27:19Z

index.html


-        <section id="canonical-representation">


We need the section on canonical representation, since this may be removed from the TD.

What is the canonical representation used for in the WoT Profile specification, and why do you think it may be removed from the Thing Description specification?

mlagally · 2021-11-04T11:29:16Z

index.html

-
-
+    <!-- Security -->
+    <section id="security">


We need a security section, however need to discuss the supported mechanisms under implementation constraints for plugfest members.

I suggest to exclude "no sec" and require basic auth as the minimum.
The other mechanisms need input from plugfest members.

I agree this requires some discussion, but I strongly object to excluding the nosec security scheme. This is currently used by all 16 web thing libraries in the WebThings Framework and there can be good reasons for a web thing not providing its own authentication.

mlagally · 2021-11-04T11:30:12Z

index.html

-      <li>define subscription mechanism</li>
-      <li>Examples</li>
-    </ul>
+    <!-- Discovery -->


I don't think we will be able to define a discovery mechanism in the first profile release.

I've been thinking about this and I agree that might be the outcome.

Of the introduction mechanisms defined by the WoT Discovery specification, I think DNS-based Service Discovery could be a candidate for a mandatory discovery mechanism in the Core Profile, but that may be asking too much.

My current thinking is that Direct discovery could be made the mandatory discovery mechanism by simply requiring that a Thing Description conforming to the Core Profile must be resolvable through an HTTP URL which can be manually typed or copy & pasted in order to locate the Thing Description.

mlagally · 2021-11-04T11:32:09Z

I reviewed this MR again, which has a lot of valuable parts.
However merging it as a whole does not work, since it contains too many contentious sections.

To move forward I recommend to split it as described in the individual comments.

benfrancis · 2021-11-04T14:10:14Z

OK, I will split this PR out into smaller ones and close this one once that's done.

benfrancis · 2021-11-09T15:51:45Z

As requested, I have split this PR out into separate smaller PRs:

Whether or not we need a Links section is being discussed in #114.

sebastiankb reviewed Apr 23, 2021

View reviewed changes

benfrancis force-pushed the data-model branch from 228236a to d73579f Compare June 23, 2021 13:15

benfrancis mentioned this pull request Jul 15, 2021

Placeholder section on transport security #87

Merged

benfrancis added 2 commits July 22, 2021 11:19

Restructure WoT Core Profile section

0b834fd

Make link relation support optional

329dcc5

benfrancis force-pushed the data-model branch from d73579f to 329dcc5 Compare July 22, 2021 10:20

benfrancis changed the title ~~Remove WoT Core Data Model section~~ Restructure WoT Core Profile section Jul 22, 2021

benfrancis requested review from sebastiankb, mlagally, mmccool, mryuichi and chachamimm July 26, 2021 13:37

mlagally requested changes Nov 4, 2021

View reviewed changes

benfrancis closed this Nov 9, 2021

benfrancis mentioned this pull request Jan 26, 2022

Clarify concerns on Human readability #160

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure WoT Core Profile section #78

Restructure WoT Core Profile section #78

benfrancis commented Apr 22, 2021 •

edited by pr-preview bot

Loading

sebastiankb Apr 23, 2021

benfrancis Apr 28, 2021 •

edited

Loading

egekorkan commented Apr 26, 2021

benfrancis commented Apr 28, 2021

mmccool commented Apr 29, 2021

benfrancis commented Jul 22, 2021 •

edited

Loading

mlagally commented Jul 26, 2021

benfrancis commented Jul 26, 2021 •

edited

Loading

benfrancis commented Jul 26, 2021

mlagally Nov 4, 2021

mlagally Nov 4, 2021

benfrancis Nov 4, 2021

mlagally Nov 4, 2021

benfrancis Nov 5, 2021

mlagally Nov 4, 2021

benfrancis Nov 5, 2021

mlagally Nov 4, 2021

benfrancis Nov 4, 2021

benfrancis Nov 4, 2021

benfrancis Nov 5, 2021

mlagally Nov 4, 2021

benfrancis Nov 5, 2021

mlagally Nov 4, 2021

benfrancis Nov 4, 2021

mlagally Nov 4, 2021

benfrancis Nov 4, 2021

mlagally Nov 4, 2021

benfrancis Nov 4, 2021

mlagally commented Nov 4, 2021

benfrancis commented Nov 4, 2021

benfrancis commented Nov 9, 2021

		@@ -198,8 +198,6 @@ <h3>Motivation for a Profile</h3>
		<section id='sotd'></section>

		<section id="intro">

Restructure WoT Core Profile section #78

Restructure WoT Core Profile section #78

Conversation

benfrancis commented Apr 22, 2021 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

benfrancis Apr 28, 2021 • edited Loading

Choose a reason for hiding this comment

egekorkan commented Apr 26, 2021

benfrancis commented Apr 28, 2021

mmccool commented Apr 29, 2021

benfrancis commented Jul 22, 2021 • edited Loading

mlagally commented Jul 26, 2021

benfrancis commented Jul 26, 2021 • edited Loading

benfrancis commented Jul 26, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mlagally commented Nov 4, 2021

benfrancis commented Nov 4, 2021

benfrancis commented Nov 9, 2021

benfrancis commented Apr 22, 2021 •

edited by pr-preview bot

Loading

benfrancis Apr 28, 2021 •

edited

Loading

benfrancis commented Jul 22, 2021 •

edited

Loading

benfrancis commented Jul 26, 2021 •

edited

Loading