W3C

– DRAFT –
WoT-WG - TD-TF

04 August 2021

Attendees

Present
Ben_Francis, Cristiano_Aguzzi, Daniel_Peintner, Ege_Korkan, Kaz_Ashimura, Michael_McCool, Sebastian_Kaebisch, Tomoaki_Mizushima
Regrets
-
Chair
Sebastian
Scribe
benfrancis, cris

Meeting minutes

<McCool> https://github.com/w3c/wot-thing-description/issues/1001

Sebastian: Welcome to the call, we will look at some PRs and issues and discuss publication.

<McCool> https://github.com/w3c/wot-thing-description/pull/1155

Minutes from last time

<kaz> July-28

Resolution: minutes approved

Publication Plans

The Working Group Charter has been extended for another six months, until the end of January, by which point we should have released recommendation documents.

Sebastian: CR in November, PR in December, REC in February. Dates provided by W3C calculator.

Sebastian: Should publish candidate recommendation in October so we have more time for updates if needed.

Sebastian: I suggest we should spend all of September to implement missing features for TD 1.1, then work on Candidate Recommendation in October.

Sebastian: Then proposed recommendation, then recommendation next year.

Kaz: Just for clarification, the current Working Group Charter lasts until January next year. If we need to we can ask for an extension.

<kaz> current WoT WG Charter

Sebastian: I understand, so we are not yet in an extension of the Working Group charter.

Sebastian: Suggest implementing all missing features for TD 1.1 in September, then plan for a CR in October.

Kaz: Tough, but would be nice

Sebastian: Yes, we will need time for testing.

Pull Requests

PR 1155

https://github.com/w3c/wot-thing-description/pull/1155

Draft Testing Report for TD 1.1

There were some errors that showed up. Flagged some assertions that weren't right. Need fixing in spec.

Basically a reorganisation, updates the report as a draft.

Sebastian: Why have so many files changed?

McCool: Mostly because this is a re-rendering. New files resurrected from old branch and put in the archive. Technically not needed because they are in branch but people kept worrying where they were.

Sebastian: I propose that we merge to have a rendered version.

Resolution: Will merge PR 1155

Sebastian: Thank you for working on this, not easy.

McCool: Sorry it took so long, still work to do. In particular testing implementations, need descriptions from each implementer to say what they worked on.

McCool: Should add issues about adding organisations, e.g. WebThings

Sebastian: Would be good to have WebThings here.

Ben: Sounds good

Sebastian: Can see gaps.

Ege: Gaps could also be that there is no test.

Ege: How do we know?

McCool: If there are zero failures then there is no test.

McCool: Currently only need one result for optional features, decided we now need two implementations for optional implementations. That may cause more failures. Everything that is currently a 1 will be red.

Ege: There is a TD default observeable. Manual assertion, newly added. Somehow it has 4 implementations which all pass.

McCool: I think right now that's a manual assertion and people have submitted it as true.

Ege: Shouldn't be, I didn't even add this to a template.

McCool: Consumer assumes that it has a value false.

Ege: I added this assertion to the TD spec last week, there is something wrong somewhere.

McCool: Could check ID values, could be duplicates.

McCool: Let's investigate.

McCool: If you look at the output.log it flags a bunch of errors that need fixing.

Sebastian: For the next testfest, concentrate on gaps

Sebastian: Should definitely be discussed in the testing call

McCool: I will try to clean up more if I can, but this is a starting point

Sebastian: Thanks for the effort, first version of 1.1 test report. Will continue to work on it to fill gaps.

Add "precision" to data schema #1001

https://github.com/w3c/wot-thing-description/issues/1001

McCool: Three different terms: Precision, resolution and accuracy.

McCool: Wrote draft for editor's note.

Need to figure out where in the spec to put this

Take a look and let me know if this makes sense

Sebastian: I like the idea of recommending a particular ontology which defines this expression

McCool: I think what we want is a data schema, parallel to multipleOf. Used in a data schema to annotate particular values.

Something like { "ssn:accuracy": 5, "ssn:precision": 10 }

What about units?

{ "type": "number", "multipleOf": 1 }

Have seen examples when precision/accuracy given in different units to main value, e.g. if there's a big difference in size of values.

For now the example doesn't have to mention units, but something to discuss when discussing units

Ege: Should at least be able to have precision and accuracy bigger than...

the value

McCool: Might argue that precision lower than accuracy. Think they should be larger.

Discussing graph in https://github.com/w3c/wot-thing-description/issues/1001#issuecomment-884234374

<sebastian> I have to open the door...

McCool: Issue of probability of being within certain distance. Give default value like 90%

Ege: Does anything limit anyone from putting an object as a value for accuracy

McCool: Why would you want an object for accuracy?

Ege: Just asking if it is valid

McCool: Gets to the issue of how do we validate extensions?

Do we want to define something in our own JSON Schema which validates these terms?

We could include these definitions in our own ontology.

Cristiano: The validation of this extension is quite tricky. Prefixes that could change. JSON Schema for that is hard unless we embed them in our ontology. Should also ask whether plans to add prefix support.

McCool: Ours is JSON-LD so we're allowed to use prefixes, but they may not be consistent so hard to validate. If we put them in our ontology then we can check them.

If it's an object, what if I want to do type object? Think should require separate for each member, more logical.

Makes it more verbose.

McCool: What does multipleOf do? If can be used on objects then would be OK.

Ege: I really meant what if someone makes a mistake by putting an object in the value.

McCool: Ideally the validator would catch that. Can add to validator if part of ontology.

More in line with mlagally's original proposal of having these built in.

Maybe we can ask the SDF people as well.

Ege: Ontologies are growing, when should we say yes and when should we say no? If only benefit is easier validation...

McCool: Putting in our own ontology also helps with consistency.

Cristiano: Importing the entire SSN ontology is a big deal, it's huge.

I was comfortable with the text you wrote, encouraging people to use SSN.

McCool: I like this suggestion of adding a new section. Then can add as a starting point.

Sebastian: Makes sense, chapter about making use of external ontologies, can provide context about precision and show how it can be implemented in SSN.

Makes sense to have examples there and provide a good explanation.

McCool: Create a new section, not an editor's note, change highly recommended to SHOULD, include example. Will create a PR for this shortly.

(McCool leaves)

Security reorder #1201

https://github.com/w3c/wot-thing-description/pull/1201

Sebastian: IIRC McCool suggested merging this PR.

Will merge, mccool will review before.

Resolution: Merge.

Fix definition of multipleOf in TD schema #1204

https://github.com/w3c/wot-thing-description/pull/1204

May need to make Jan an Invited Expert as he is making good contributions

Sebastian: Problem with definition of multipleOf in JSON schemas

Looks OK, Ege can explain what is wrong.

Ege: I think it was more in the TM that there was a problem. In the TD he only re-factors it. In the TM schema...

Sebastian: oneOf -> anyOf. Global definition. Re-use definition in different places in JSON Schema

Ege: I approved it, OK for me.

Sebastian: I am fine to merge this PR, but still have the consideration that Jan is not a member. kaz should decided what to do. Member or Invited Expert? He is a student at university.

Kaz: As usual, if this content is editorial we can simply merge it. If it is normative content we should consider making him an Invited Expert.

Sebastian: I can ask him if he is interested in being an Invited Expert, and suggest that he applies.

Sebastian: Is it OK to merge this since it's just a bugfix?

Kaz: Yes we can mark this as editorial.

(kaz marks the PR as non-substantive for IPR)

Resolution: Merge the PR, invite @JKRhb to be an Invited Expert.

Fix issues in TM schema generation script #1205

https://github.com/w3c/wot-thing-description/pull/1205

Sebastian: Not ready to merge?

Ege: I need to review this, not had time yet

WIP: Updates for TM Chapter #1207

https://github.com/w3c/wot-thing-description/pull/1207

WIP PR removing text about TMs, clarification about overwriting, TM composition with links, unclear assertion on TMS.

Issues

Add "precision" to data schema #1001

https://github.com/w3c/wot-thing-description/issues/1001

Already discussed above

Should it be possible to indicate whether writing a property returns set value? #875

https://github.com/w3c/wot-thing-description/issues/875

Daniel: Questions about response/return types

Daniel: Whether a return value is expected, could be introduced easily without breaking anything

Sebastian: Relates to PUT vs. POST operation

Sebastian: Same expectation as reading a property?

Ege: What if I return something?

Daniel: If write a large blob, in some cases don't want to return the whole blob

Daniel: Need to have a way to indicate whether something comes back

Sebastian: If there's a big payload, would be strange for it to be returned. Could be possible, not mandatory, open to implemtnation

Cristiano: I agree it would be easier to introduce the feature if we say we allow returning the exact type in input. E.g. in Philips Hue case where they return an object, the protocol binding should do the work.

Cristiano: Protocol dependent feature. Some ambiguity.

(Sorry, missed some points)

Ben: We discussed this in WoT Profile, decided not to return the value since it could be very large.

Daniel: in this scripting api currently we return void. The echonet people would expect having a value back, it feels that we are not fully compliant with them
… also I found a possible use case to know from the application side the real floating point value written. For example, I'll try to write 1.3333 and the device actually store 1.33

Kaz: Daniel, maybe you're referring to the old document from Echonet, aren't you?

Daniel: yes

Kaz: Regarding the ECHONET liaison, we got latest updates from Matsuda-san since March, and got a new use case description yesterday. It might take a bit longer than expected, but we should continue further discussion based on their clarification step by step.

Daniel: During discussion about the Core Profile in WoT Profile discussion, the initial proposal was to return a value. It is used out there and currently in the TD we can't describe it.

Kaz: As I mentioned during the Profile calls, we need more use cases for proposed interface. Preferably, we should look at industry use cases, existing devices and standards including Philips Hue, ECHONET, OPC-UA, etc.
… Don't need to work on new profiles for the WoT Profile spec, but should look at existing industry standards and proprietary interfaces.

Ege: I think we are mixing prescriptive and descriptive approaches. Whether we say you should describe one or the other, it doesn't matter. The important thing is that we can describe either scenario.

Ege: Philips Hue is very popular, we should be able to describe its API.
… Currently have to use actions because modelling as properties is complicated.
… The object that you read is different to the object you write, the write returns another type of object which is completely different.

Sebastian: writeResponse tells client/consumer whether you are getting a response. true/false.

Ege: Would work for Philips Hue.
… If default assumptions not true then need to provide a data schema at the forms level.

Ben:

https://w3c.github.io/wot-thing-description/#form

Ben: Form has a response member, is that not what this is for?

Ben: If ExpectedResponse has a schema member, does this not solve the problem?

Ben: schema in ExpectedResponse also needed for actions

Daniel: In case of action separate input and output schemas

Ben: If an ExpectedResponse has schema then could put it there

Cristiano: I think this would cover the three cases that you wrote

Ege: Need defaults, e.g. if detect different data in response.

Cristiano: If we leverage schema term, we cover all sebastian's use cases without writeResponse term.

A little concerned from the implementation point of view.

What if we have forms with differnet schemas

E.g. in actions, should always use the schema inside the form

Ben: with schemaDefinitions proposal, possible to describe complex APIs, but not clear a Consumer would actually be able to communicate with a device.

Cristiano: Yes, exactly my point.

Ben: Important point is that the schema term needs adding to the ExpectedResponse object to make the three cases possible.

Ben: Whether a consumer can interpret this is another matter, would be interested to see how implementations cope with this.

Daniel: The runtime can choose. Need to detect whether anything comes back. In the simple case maybe there's one return value that's always the same. If there are variations between forms then it becomes hacky.

Cristiano: Just started working on validation of inputs and outputs. So far fine, but once need to merge schemas and deal with schemas at different levels it will get messy. Just a feeling.

Sebastian: Homework for you to describe in Scripting API and evaluate what this looks like. Then make a decision based on that.

Daniel: In the current case don't expect a response, and can still do so.

If interested in the result then have a more complex use case and the implementation becomes more complex.

Ege: Not just an API problem, also hard for a human to do.
… Should they put details in each Form? Decide whether the value being returned is valuable for business logic?
… Generally feels like a bad design that means I have to look into this stuff. Need to push it up to the application level in some cases because not clear what to do with the schema, not clear what is important for application logic.

Cristiano: Maybe I can describe the flow if this was introduced to Scripting API. If developer writing application wants these values, first need to search for the forms that provide this value. Need to look for a form with conforms with criteria looking for. After choosing form, tells the runtime to use the form. The runtime could choose not to use
… that form index. Runtime could choose another form.

Daniel: If the form index is provided, it's not just a hint. If the form doesn't work then you provide an error.

Sebastian: Don't know how to proceed here.

Ben: Could resolve to add schema member to ExpectedResponse and then see how well it works in practice in implementations.

Cristiano: Yes I think implementations will be the decider.

Daniel: Could add the feature but mark it as at risk.

Sebastian: Introducing schema in ExpectedResponse also motivated by the queryaction issue. Should introduce it. A bit of a contradition that it's in AdditionalExpectedResponse but not ExpectedResponse.

Ben: In case of actions about separating schema of output of action from the schema of the response to the request.

Kaz: OK with adding this, but as usual would be nice to have more concrete code and to let people know how to use this feature, with what kind of device and device transfer.

Sebastian: This is also a nice feature for ECHONET since we can describe how it works today

Kaz: agree it would be useful for ECHONET as well, but we need some more clarification about ECHONET interface. So let's continue discussion with them based on Matsuda-san's use case and their expected contribution to the Plugfest at TPAC 2021.

Ben: Core Profile is a potential use case

Kaz: Yeah, my point is that we should clarify how to use these features/binding somewhere. For the moment putting it in the WoT Profile document is fine, but would be nice to have description within the implementation guideline document separately in the future. That's why I proposed to add the implementation guideline document to the new IG Charter.

Kaz: We can think about Philips Hue/OPC-UA as industry examples. Should clarify how to use features in actual use cases and document it somewhere.

Resolution: Introduce schema term in ExpectedResponse. Declare it as "at risk" and ask for implementations.

Sebastian: Who can introduce this feature? cris?

Cristiano: I will look into this. I also need to check with node-wot.

Ege: MindSphere API provides another example.

Sebastian: Please provide feedback on How do you cancel or query the state of an action request? #302 https://github.com/w3c/wot-thing-description/issues/302

Encourage Ege to discuss this issue next week and take a decision

AOB?

Ege: Raises topic of asynchronous decision making, from Ben's email

Sebastian: A chair has to be present to merge a PR

Kaz: This is up to group, chairs can delegate

Ben: Current decision policy favours asynchronous decision making

Sebastian: I can leave comments on issues that I think are ready to land before I leave

<kaz> [adjourned]

Summary of resolutions

  1. minutes approved
  2. Will merge PR 1155
  3. Merge.
  4. Merge the PR, invite @JKRhb to be an Invited Expert.
  5. Introduce schema term in ExpectedResponse. Declare it as "at risk" and ask for implementations.
Minutes manually created (not a transcript), formatted by scribe.perl version 136 (Thu May 27 13:50:24 2021 UTC).