<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
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++
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://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?
https://github.com/w3c/wot-thing-description/issues/913
Keep open, but clean up later.
<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?
<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.
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.
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.
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
<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
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]