WoT-IG/WG - Virtual F2F meeting - Day 5

26 Jun 2020



Kaz_Ashimura, Michael_McCool, Ben_Francis, Daniel_Peintner, Farshid_Tavakolizadeh, Jennifer_Lin, Michael_Lagally, Takuki_Kamiya, Michael_Koster, Sebastian_Kaebisch, Ryuichi_Matsukura
McCool, Sebastian
Ben, Taki, Cristiano


<kaz> Presentations area


<kaz> 2 for TD, 1 for marketing

<kaz> 1. Ben

<kaz> 2. Taki

<kaz> 3. Cristiano


<kaz> scribenick: benfrancis

<inserted> @@@ TD slides tbd

Sebastian: Welcomes the group to Friday session of F2F, Thing Description discussion
... Known TD spec bugs, under-specified features, new features for TD 1.1, Status of Templates, hypermedia, discovery & security
... Discovery & Security will recap discussion from Monday

* Editorial bugs

Sebastian: Want to improve the Thing Description and make it more powerful. We have found bugs, e.g. in Example 17.

Example 17 has a stray comma which prevents parsing as valid JSON

Pull request to remove the comma. Question: Should we update the main Thing Description specification as well?

Kaz: The latest policy is, as long as a fix is editorial, can fix recommendation itself.

McCool: Should create Errata page so people know what has changed.

Kaz: Should file two issues, one for recommendation and one for latest Editor's Draft

McCool: Could label issues that need to be landed in Recommendation.

<kaz> PR 914

Kaz: Can define a simple procedure so we can fix the current draft on GitHub using PRs, but create additional issue for Recommendation. Consolidate editorial issues and ask webmaster to reflect these in the published specification.
... BTW, there was another issue pointed out regarding table syntax. #919

<kaz> https://github.com/w3c/wot-thing-description/issues/919

RESOLUTION: Pull request to remove comma to be merged into latest Editor's Draft. The comma is banished. Should create Errata document to note bugfixes. Daniel will create separate issue to remove comma in Recommendation, with a label to note editorial change.

Sebastian: Issue 915 https://github.com/w3c/wot-thing-description/issues/915

Validates as valid Thing Description, but if using JSON Schema(?) validator does not correctly recognise terms in securityDefinitions collection.

McCool: Schema has definitions for things that have been removed, needs a cleanup

Sebastian: For people who want to use semantic tools, will have issues with security members

McCool: Can we update the file as is or publish a new version?

If it's a bugfix, updating the current version makes sense

Should delete extra schemes that are not in the spec to bring it inline with the specification

How did we miss this? Do our testing tools like include JSON-LD tests?

Sebastian: We are not doing enough semantic testing in our PlugFests

McCool: We did do testing, but treated as optional elements so did not trip the test case. Or similar.

Ege: Should have thrown an error. Perhaps JSON-LD version in playground is old.

McCool: Should fix the testing so it does trip on this, and fix context file. Investigate if fixing in place with bugfix is reasonable.

Sebastian: Context file not directly in the specification. Is it OK to just change it? The specification is correct, but the model file has a mistake.

Kaz: Should think about impact for implementations if we fix the bug in the context file. Will implementations be impacted, what would need to be changed. Should carefully consider.

McCool: Notify people in advance that the context file will change in place, set a date for that change, archive old version with new URL (e.g. v1_obsolete)

Need to consider this a bugfix.

Kaz: Can bring this to project manager and ask if OK to reflect the change.
... If change impacts implementation then need to discuss further.

<McCool> to capture what else I said: I'd like to suggest we establish a minor version, and let "v1" pick up the latest minor version

McCool: Thanks, I lost track of that part.

<McCool> then if people really want older versions, they can use a more specific minor version, eg. v1-0, v1-1, etc.

Sebastian: Implementors may wonder why they do not see securityDefinitions

Kaz: Should assess potential impact

Taki: Can ask bug filer how it impacted their implementation

Sebastian: Bug filer has a workaround.

Dape: Have previously been asked to file issues for Errata items, this seems similar. I think it would be good to not just do change in an issue but list as an Errata item.

Kaz: Already provide a template for Errata entries. This issue might be problematic for implementations should carefully look into this.

McCool: Different to modifying the specification (human readable), this is machine readable and would impact implementations. Bugfix in minor versions.

Figure out how to do bugfix as code, not just editorial change in spec.

Kaz: Should clarify what our intention was. If this was intended specification this is fine, but need to fix bug on specification itself for next version.

<kaz> Errata file

McCool: Not an errata issue in spec, bug in file, spec is fine

Kaz: If implementations are impacted, that would be a problem.

Lagally: Support idea of Errata document. So implementors know what to do to be interoperable, and understand if there is a delta from what has been published.

Sebastian: Is this Errata document linked in the recommendation document?

Kaz: Yes, there is a link in the top section.

Sebastian: Resolution: I will respond to issuer to say we can approve this bug and will fix this in the Errata process.
... These were the two topics we need to address very soon.

<kaz> thinks it's actually a good proof of the fact that people have started to use the TD spec :)

<benfrancis> kaz++

* URI Variables

Sebastian: Specification looks like we should use uriVariables, except action input field. Criticized in some issues. Should clarify when we should use uriVariables.

McCool: So using uri query paramaters is considered bad practice in API design?

Sebastian: Yes and no. Can use uriVariables in properties etc. But for actions we have inputs, so why are we showing an example of uriVariables for actions when we also have input?

uriVariables should probably be avoided if possible for new systems.

McCool: Two issues. Did we introduce uriVariables as a good example.

<kaz> Issue 910

uriVariables are actually bad practice in actions. For actions you do have paramterized actions. The use case that comes up is if input is binary data like an image.

Inconvenient to have to create a body that has some JSON. There are use cases for this, need to explain.

Sebastian: We should be more clear about usage?

Dape: Disagree. Using uriVariables for properties is bad design. In case of actions when you POST something considered good practice if convey data in body. For properties there is no outcome so considered back practice.

McCool: Question is what you use the query data for. Might want to put data parameters in POST query. Binary vs. ASCII data.

Need a best practices document that explains these tradeoffs. The spec just says what the spec can do. Examples should be reasonable and not contradict best practices.

Sebastian: Example 21 uses uriVariables in a property. Passed in URL in form. Looks good to me, should maybe provide clarification.

McCool: I do agree this is a reasonable use. Constraining the type of data you're getting back. More like a query/database query.
... I can see it being justified.

Dape: This is a good example of a running instance that works.

Sebastian: But is it really running?

<sebastian> https://cdn.statically.io/gh/w3c/wot-thing-description/d7c47cfce6df02f162e16164fe9beee1802ebbeb/index.html#example-21

<sebastian> https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=439d4b804bc8187953eb36d2a8c26a02

<sebastian> PR on updating example 21: https://github.com/w3c/wot-thing-description/pull/911

Sebastian: Should we merge this PR? Update example? More reasonable, not as confusing.

<Ege> https://openweathermap.org/current

FarshidT: Root of the problem is really the HTTP method. GET request should not change state.

Sebastian: Action comes from Matthias. Comes from Nabaztag (Wi-Fi rabbit). Has a REST API. Designed a Thing Description for this. Uses GET method with parameters. So it's the rabbit's fault.
... The Thing Description should show best practice.

I may have paraphrased...

RESOLUTION: We will merge this PR.

Sebastian: Should we also close this issue?


Keep open, but clean up later.

* readmultipleproperties

<inserted> Issue 848

Lots of discussion about readmultipleproperties

Very fussy and strange that it was adopted by specification since there is an expectation we have implementations.

Ege: There are no implementations.
... There are TDs produced, but implementation wasn't doing it properly.
... Report says there are two implementations, but I can only find examples from node-wot

<inserted> scribenick: taki

McCool: It was the last minute change.

<McCool> to be clear, implementation report was totally data-driven, but this extra implementation might have been based on a manual assertion rather than a TD

<McCool> we will have to look at the archives in more detail

Sebastian: It cannot disappear now. I should investigate more such as use cases in CoAP PATCH and OPC-UA.
... also it may be common in cloud systems.

Lagally: Network overhead is significant.
... We do read-all in our implementation.
... It is useful in practice.

Koster: Digital twin systems, common interaction through incremental changes.
... It looks like an interaction model issue.
... It is a model issue.

Ege: It is not clear why we need to supply an array.
... It is different in pub/sub case.
... If it is using URI variable, how can we do this?

Sebastian: It is not well explained in spec.

Daniel: We have both methods for retrieving multiple and all.
... From scripting perspective, it is not really necessary to have both.
... I can do real-all. If it is only 2 or three, we can use promise.

Koster: read-all satisfies the requirements.

Zoltan: Are there anyone who absolutely need read-multiple?

Sebastian: CoAP-PATCH? We need to investigate.

Koster: CoAP-PATCH is for patterns. OPC-UA, there is a bulk-load. Cloud systems usually does not need read multiple.

Zoltan: I have never seen use cases that need read multiple.

Koster: Some people may see read-multiple as optimization.

Zoltan: I can group them in an object in TD.

Koster: There are design patterns. But we do not have concrete use cases.

Ben: It is safe to remove read-multiple. We can make it as a feature at risk in the coming version.

Sebastian: One possibility is to remove it in the next version. At the same time, we could investigate more. For now, it seems that removing it makes more sense.

Zoltan: We can add it later.

Daniel: You can mark a feature so if nobody finds it useful, is there procedure in W3C?

Issue #913 Improve text on Action parameters

<inserted> Issue 913

Zoltan: multiple parameter case is not very clear in spec right now.

Sebastian: Those are the issues that I wanted to have discussed today.
... new features next.

<Ege> brb

Sebastian: minLength, maxLength and multipleOf in Data Schema, see PR #896.

<inserted> PR 896

Sebastian: Have not merged yet because there is a problem in rendering script now.
... Victor is not available today. He works on rendering script.

Sebastian shows JSON Schema ontology HTML.

Ben: Mozilla implementation already has multipleOf because there is a use case.

McCool: Are there any JSON schema features that we do NOT want?

Sebastian: the set we have now was all experimented in plugfests.

McCool: developer expectation is that it is JSON-Schema.

Koster: We have not seen many payload examples.
... Let's make a bigger useful subset for common payloads.

McCool: We should talk to people experienced in IoT payloads.

Sebastian: We say in spec that we support all keywords.

McCool: $ref, for example, does it break validation?
... we should base our decision on community experience.

Ben: Mozilla implementation is basically using the set specified in W3C recommendation.

definition and $ref

Sebastian: next, definition and $ref. This is new as well.
... Define data model constructs once, and use it in multiple places by reference.

<benfrancis> The Mozilla implementation so far uses enum, readOnly, minimum, maximum and multipleOf. And unit, but I think that was added for WoT.

Sebastian shows Issue #307.

<kaz> Daniel's example for Issue 307

Sebastian: It was originally suggested by Toru Kawaguchi.

Koster: "definition" is convention in JSON schema.

Ege: Yes

Koster: we can use JSON pointer, and JSON validator work on that.

Sebastian: JSON validator does not understand action, property, etc.

<cris> https://github.com/w3c/wot-thing-description/issues/912

Cristiano: I have issue with Content-type in schema. We can discuss in next TD call.

<Ege> https://github.com/eclipse/thingweb.node-wot/blob/a3999fac20a4616d209fe0c1830a311cef0b86a4/examples/templates/exposed-thing/src/base.ts#L124

Lagally: Design question. Do we need to parse TD once or twice to resolve references?
... This is important for constraint systems.

Ege: I posted a link.

Koster: there are also recursive and circular references.

Lagally: We should discuss to limit references to backward references, for example.
... can you use variable before you declare it?

Daniel: With JSON, object members are shuffled around.
... there is no way to define order in JSON.

Lagally: We have TD serialization, and we can specify.
... This is an issue with small devices.

Sebastian: client may not use all dependencies.
... It is up to the use case.

Koster: constrained devices cannot buffer much in memory, is that the point?
... security thing is the same.

<McCool> sequence is not technically required by the spec... but maybe could be required by the profile

Daniel: complexity raises. You can point anywhere in the document with JSON-schema.

Lagally: We should keep this issue in mind, and specify how to limit if necessary.

Farshid: Default security, for example. We no longer need it.
... If we copy it to elsewhere, the links will break.

Daniel: We do not intend new dependency.

Farshid: It is only for data definition.

Koster: can we reference definitions outside of the document?

Ege: $ref depends on implementation.
... It is underspecified in JSON-schema spec intentionally.
... AJV, for example, does not have TD scope.

<sebastian_> https://github.com/eclipse/thingweb.node-wot/blob/a3999fac20a4616d209fe0c1830a311cef0b86a4/examples/templates/exposed-thing/src/base.ts#L124

Ege: You have to copy definition into actions before handing to AJB.

Daniel: You can copy the entire definition to next to $ref/
... i.e. within the same scope.

Ege: $ref, all depends on implementation.

Sebastian: $ref processing depends on validation tools?

Ege: there is common practice among implementations.
... But it is not specified in JSON schema.

Sebastian: We can specify in TD spec then.
... We can also use JSON pointer.

Kaz: I am skeptical about this proposal.
... for example, there is a possibility of using Verifiable Credentials and DID for user credentials, so we should look into some more use cases to see the actual need for "$ref and definitions".
... We should look at more use cases.

McCool: We can have "processed" version of TD.
... external definition should be disallowed.
... DID is new spec at this point.
... $ref makes more sense to me.

Sebastian: We discussed this in TD call, and we agreed we need this feature.

Kaz: If the main purpose is defining address separately and referring to it once, do we really need this feature?

McCool: We wanted to reduce redundancy.
... We should start describing use cases.
... redundancy invites error.
... We should describe use cases.

Ben: parsing algorithm's point view, it introduces complexity. We can make it preprocesing in the server.

Sebastian: Complexity vs. redundancy is a recurrent issue.

Ben: This is also an issue TDT.

<cris> taki I can take over the notes, or at least I try :)

Sebastian: We have only one hour left.
... We should take a break.

<benfrancis> I also think securityDefinitions should be simplified so that security can be used on its own for simple examples (https://github.com/w3c/wot-thing-description/issues/300)

<benfrancis> https://github.com/mozilla-iot/wiki/wiki/Mozilla-W3C-Differences

Ben: I started to document the difference between Mozilla implementation and W3C specification in the hopes that they will converge.

<cris> ben: starts to document the differences between mozzilla'TD and W3C TD. Trying to convege

Sebastian: Thank you very much, it is a great work.
... People expect the two are the same.

Ben: there are many minor differences. The bigger one is architecture changes including protocol binding.

McCool: Profile can help.

<inserted> scribenick: cris

McCool: 10 minutes break

<kaz> [10min break; resume at 15mins past the hour]

McCool: sharing the agenda

Marketing - Current activities

<inserted> @@@ slides tbd

McCool: sebastian review of activities, discussion of the next steps

Sebastian: quick update, showing a patchwork of different articles where wot were mentioned
... sharing links to these articles
... please add more if have seen other sources mention wot
... showing the new logo
... please use the new one
... we are working with webcastor which already worked for W3C
... we are going to create a video, Siemens will sponsor it
... and Intel
... sponsor positions are open
... a style of video was decided

McCool: two kinds of sponsorship: money or logos

Lagally: is there some of document which explain the content of the video

Sebastian: there are some slides about it, cannot show them now
... topic twitter account
... go to @W3C_WoT

<kaz> @W3C_WoT

Sebastian: there is a draft of a new wot web landing page

<dape> https://github.com/w3c/wot-marketing/issues/65

Sebastian: was made by Studio 24, daniel has more details about it

Daniel: provides a link with next steps
... studio24 will provide updates in that issue

<kaz> timeline

Daniel: studio24 plans to work openly

Kaz: they are working with the basic template HTML+CSS like a CMS so that people can easily maintain the Web pages

Daniel: it might be complicated to handle users

Kaz: mentioned to them the possible difficulty with working on the W3C content which consists of multiple mechanisms

Sebastian: new page on wikipedia about WoT
... it was outdated and not reflected what W3C was doing
... someone made some changes but violated some copyright rules
... we need to discuss how can we improve it
... like describing the different blocks in the W3C WoT architecture

Ege: we need to provide more references

Sebastian: how can we improve it ?

McCool: create a draft were we can work together with other parties
... also can we trigger an re-evaluation of the page content?

Ege: need to explicitly ask for an re-evaluation

McCool: in the marketing repo we have a md page that needs to be kept in sync

Kaz: ege, do you know some external collaborator who can help us with the wiki?

Ege: we can tweet about this

<kaz> WoT welcome page

Lagally: What's the plan with the public WoT landing page?

Daniel: the current one has nothing to do with what studio24 is doing

<McCool> timecheck: now way over the 10m allocated...

Daniel: we mean to substitute it with the new one

Lagally: when is the best time to provide feedback about the new landing page?

Kaz: we can talk about this during the next marketing call

Sebastian: Michael, you can comment anytime

Lagally: it is quite confusing because we have two versions running in parallel

Kaz: the W3C WoT Landing page was made/maintened by the W3C Team, while the new WoT Welcome page is made/maintained by the WoT Marking TF.
... On the other hand, we (=Daniel, etc.) were asked for input from Studio24 who is now working on the redesign of the global W3C pages (except the group pages like the WoT Welcome page)

Lagally: just let us know if something is ready for review

Kaz: Studio24 is working on the global W3C pages except the group pages
... So we have to make a resolution on how/when to review the WoT group pages including the WoT Welcome page

Lagally: so this group page is ready for review?

Sebastian: yes

McCool: time check 18 minutes left
... handle kaz presentation to next slot
... we should now discuss about the next steps

Sebastian: the next steps were already included in the previous slides
... there is a broken link in the global W3C page

Ege: the point is that we do not have access to this page, even if we are the most interested by its content

Kaz: there are two kinds of Web pages, 1. those maintained by the W3C Team and 2. those maintained by the WoT WG ourselves. So I wanted to explain what's ongoing on the W3C Team side, but let's talk about the details during the next Marketing call

<inserted> W3C Project Management Updates

<McCool> at the very least I think we need to streamline change requests, eg with direct access to an issue tracker

Sebastian: topic upcoming conferences
... Ege has applied to a ASC 2020 conference

Ege: if anyone has input about my submission is there still time for editing

McCool: we could also have a session were we review your slides, maybe in the Marketing calls
... the conference it will be a good chance to talk with experts from other technologies (i.e. openAPI)

Sebastian: there is a video about node-wot in action

McCool: there is also a template for slides to keep a consistent look&feel

Ege: include some photos from plugfest as additional material to include in presentations

McCool: we need to get a consent by people on these pictures

Ege: but they are already pubblic

McCool: we still need to get their consent

Ege: another thing in addition to a template we can put material which will be used inside the presentations

McCool: any other comments?
... let's agree on the template and start to use it

Kaz: the template is nice, thank you

Wrap-up and Closing


McCool: topic closing session
... topic followup activities
... profiles in 2 weeks, call for TDT in 2 weeks (TD webex), hypermedia calls in 3 weeks...
... try to cancel as many calls as we can to break after F2F
... let's cancell all the TF meetings but if you have an exception please report it in the mailing list

<kaz> Project management updates for Marketing

Kaz: should we move also the discussion about Marketing tools in the next marketing call?

McCool: yes let's move it in 2 weeks
... when will the minutes be ready?

<inserted> from now, i.e., July 8

McCool: let's put fix a deadline: 2 weeks from now
... if there are any other follow up activities please email me

Lagally: I need to allocate someone to the requirements of manufacturing

Sebastian: you can put me and Christian and also to the smart building requirements

McCool: who's is going to post about F2F on twitter?
... assigns sebastian to this task

Kaz: please take a look at my slides before the next marketing call

<kaz> Project management updates for Marketing

McCool: we should keep an eye on Ege slides for the next conference
... is any followup action that I miss?
... ok none, please if you have any additional items send me an email
... please also update your presentations with a PR
... ok we are done

Kaz: thanks McCool and Sebastian

<kaz> also all the scribes!

Sebastian: thank you also from my side

[vF2F adjourned]

Summary of Action Items

Summary of Resolutions

  1. Pull request to remove comma to be merged into latest Editor's Draft. The comma is banished. Should create Errata document to note bugfixes. Daniel will create separate issue to remove comma in Recommendation, with a label to note editorial change.
  2. We will merge this PR.
[End of minutes]

Minutes manually created (not a transcript), formatted by David Booth's scribe.perl version (CVS log)
$Date: 2020/06/30 07:47:53 $