owned this note
owned this note
Published
Linked with GitHub
# WISHI online meeting
May 15th (Friday), 5:00-7:00 PDT (14:00-16:00 CEST, 12:00-14:00 UTC)
Participants:
1. Ari Keränen
2. Klaus Hartke
3. Carsten Bormann
4. Christer Holmberg
5. Michael McCool
6. Michael Koster
7. Niklas Widell
8. Jonathan Beri
9. Solomon Kembo
10. Sebastian Kaebisch
Draft agenda:
* OpenAPI, AsyncAPI, and WoT/OneDM (Jonathan Beri)
* TD templates: classes, instances, and constructors (Carsten Bormann)
* TD Template SDF examples (Michael Koster)
* W3C WoT / T2TRG workshop plans and preparations (Michael McCool)
* Plugfest activities (Sebastian Käbisch)
* https://www.w3.org/WoT/IG/wiki/F2F_meeting,_1-12_June_2020,_Online
## Agenda bash
MM: few pending topics on discovery xpath vs JSON path, URL formats, in last agenda item
## OpenAPI, AsyncAPI, and WoT/OneDM (Jonathan Beri)
JB: [Slides](https://docs.google.com/presentation/d/1HSkNFfitYBlL496WJnKaT_Gi8njezH60h467tQhfBmg/edit?usp=sharing). Previously with Google/Nest, now with IoT startup. Building new platform with focus on developer experience. Spec-first fashion APIs. Automatically generate rest. Can [OpenAPI](https://www.openapis.org/) and [AsyncAPI](https://www.asyncapi.com/) help doing this? Could do alone or collaborate with others -- prefer latter.
Spec-first derivative of doc first APIs. For both existing and new APIs. Using YAML and JSON. Defines paths; HTTP verbs predefined. Concept of re-use using $ref.
Ecosystem around it makes this interesting. Tons of tooling exists to enable small and big companies to use in production. Syntax highlight for editors, GUIs to automate testing, validation and linting, create documentation -- the first use case usually, testing tools like Postman can generate sample queries with authentication, mock APIs, generate server side code, lots of tools: https://openapi.tools/
On GUI side, stoplight.io/p/studio
Spec very extensible, can add x-dash extensions.
Generic and open ended language. And very neat.
MM: how to do observe? Follow OCF precedence?
JB: no built-in method for that. Could define own, like x-observe. Would be valid OpenAPI. One open question for me too how to do well.
JB: new sister spec: AsyncAPI. Came for response when openAPI was focused on REST. This is for async pub/sub APIs. Event driven microservices, streaming APIs. Protocol agnostic: AMQP, MQTT, Kafka, "WebSockets"... implemented. Has also editors and tools. Same workflow components. Version 2.0 latest relase: multiple schemas, etc. new features.
(Showing visual studio code example with CoAP observe)
Has call-out for protocols, like CoAP.
Questions: is this approach of spec-first somethine we want enable? Should we investigate openapi and asyncapi if they can be applied to CoAP? How well they map needs investigation. The work on WoT and OneDM how relates? Helps to bridge the gap? Anyone interested to work on this topic together?
MM: 0MQ not included yet. Intel has been interested in this. Includes both RESTful and message based interfaces. Would be also nice to have combination of async and req/resp. The WoT TD is trying to address that at slightly higher level. Should probably take a look at that and tell what you think. Trying to fit together WoT TD , openAPI, asyncAPI. OCF has adopted CoAP and OpenAPI that has useful precedents to follow.
JB: also instroduced recently JSON API. Trying to approach with different specs and linking format.
MM: do we want to have multiple formats? Use OpenAPI for HTTP and AsyncAPI for message part and TD for semantic part. TD uses JSON-LD so fits nicely to semantic processing.
JB: asyncAPI also looking at cloud events. https://cloudevents.io/. Not using as requirement but rather enabling to be easily embedded. Interop as opposed to standardization. Not JSON-LD but could be.
MM: AsyncAPI uses JSON schema?
JB: yes, dont' know which variant
MM: need to figure out how to make variants consistent. Seems we're on the same page but things drift a little.
JB: boils down to value of single spec
MM: plan to synch up with JSON schema folks. We should have common set.
CB: reaction to this preso: really interesting ecosystem. Has been round for a while. To see how to use in constrained environment, OCF has been running this experiment for a few years. Have solved problems that generates in number of ways. One way: married themselves to JSON data model. Use CBOR on the wire but JSON data model so can't do easily anything else except JSON features. In various API communitites general direction to move towards schema agnostics. Saw XML and Avro examples already. General direction is to unmarry the early JSONschema.org that go them started. Being able to have flexibility is good. In particular if want to support other than JSON. In big web lots of things can be JSON but in constrained environment good to be able to use something more compact and related capabilities.
MM: pros and cons with multiple schemas. Ran into pushback on TD spec. In any environment want to have finite set of variants to still be able to read TD. May make impossible to make implementation conformant with standard. Implementation point of view good to have one powerful schema lang. That's why added extension like bid-width to it.
CB: will have a meeting of formal descirption formats at IETF in few hours. One example there RIFT format. Single schema nice but not going to happen. We have different data formats; protobuf, cbor, etc. Could push all that to jsonschema.org but would become as unwieldy.
MM: the exact problem: building GW, want to read description of interface of IoT device. Want to know what needs to be supported. Could have a small set of schema selections. If have rep format that allows any schema format to use would become impossible. Limitation of JSON schema that is was built as validation not spec schema. And we spec payloads. Need to have this conversation, maybe in future WS.
CB: just pointing out the drive towards different schemas. In email we converge on SMTP, but not sure can do that here(?)
SK: pointing out on schema defs; what we have in WoT TD: uses JSON schema terms to provide hints of intormation on how the data model looks like. Does not mean everything is in JSON. Have also described how to serialize to JSON and XML formats. Have not use case for Google-path(?). Some CBOR use cases and EXI. The model seems to work well. If using JSON schema as tooling to model data strucutre, does not mean you only go with JSON. Have binding doc that explains how you can put the schema in XML etc.
MM: we need to schedule a session on this
AK: session on this makes sense
MM: different "metadata" models out there; but designed for web services, not IoT devices. Do we extend them / convert them? Will need to convert by default?
JB: exactly the discussion wanted. Longer deeper session on this sounds good.
MM: would be good to have present in WoT group too. Will email.
CB: at WISHI has been quite succesful on these segments and then look for people to prepare slots for next meeting and do the meetings regularly. No need to exhaust one issue in one meeting.
MM: should reach out to JSONschema community.
CB: could reach out to them?
MM: will take action to reach out and see if can get them to join
AK: other preparations needed than above?
MM: the next WISHI call?
AK: plugfest week
MM: could line up speakers in two weeks
AK: could also be a segment in the joint WS
MM: OneDM integration
AK: can discuss in the next segment together with WoT TD part
## TD templates: classes, instances, and constructors (Carsten Bormann)
CB: getting discussion about objectives going forward. How we go from TD to classes of TDs and from models of classes of things to something that can be used to talk to specific instance. No new topic: classes and objects since 1967, well known ways doing this in programming language environment where useful putting interdata and interfaces into classes. The classes then instantiated with constructor. The backdrop of what trying to talk here. Not how to implement things but describing interfaces.
Have tons of interface languages we can learn from. Objective not to parrot these designs -- local programming environments -- but really about loosely coupled things.
Could think of classes of things, but a bit weird. Org that puts out a thing rarely puts out a single one. We need to talk about classes of *thing descriptions*. What can work with many instances of things.
Where does commonality come from? Why should not describe every single thing but classes? Aspects that are intrinsic to a thing. Commonalities. Things may have components coming from open source, using different things and common properties. Makes sense to capture commonalities. May have different sources of commonalities. Intrinsic since describe the thing. Externalities that don't describe the thing but relations to environment. What IP address it has. Also other things in deployment and purpose of the thing that can not be known by manufacturer or open source libraries or even standards. Need to be described by that thing "purpose of life".
Also things like do I need to go via a NAT. Also legal requirements that come at deployment level -- sometimes used via humans othertimes factory floor. Also standards.
MM: developer expectations important here. Write code and want to talk to device. Another reason for externalities in class. Also relates to sources of commonality. Three kinds of classes 1) interfaces, subset of set of functionalities 2) components 3) sets of for example certain class of HVAC. These overlap and confusing is that purposes overlap.
CB: good refinement. Was trying to stay at high level. Most people working with programming know about interfaces etc.
MM: interface not instantiable, describing
CB: in programming world, yes
MM: could be updating capability, but not useful alone. Could steal things from programming models where makes sense.
CB: in IoT instantiating is called manufacturing. Interesting thing here: given sources of commonality, how composability can and should be handled, may no longer work well. In programming never have situation that have class def and mix legal requirement to that. Might need to think a bit on descriptions.
MM: can start with programming lang constructs and see what makes sense
CB: that's the easy part
MM: when explaining to developers makes sense to keep close. Legal requirements interesting.
CB: different perspectives. Two developer perspectives 1) developer that develops a thing 2) one that writes apps to interact with a thing. Both need to be able to take advantage of this. These two might not even meet but need to make sense for new app.
One aspec that is useful to discuss (maybe): when look at prog langs, one important part of class is how you construct objects. Most langs have constructor: recipe for instantiation. Have parameters to instantiate different types. With TDs constructor paradigm not quite right thing since parameters change over life of thing: TD also needs to change. Still may want to have processing model where we have classes contributing to new TD with new parameters. Problem prog lang people have found out: have really problems defining classic object semantics. If two have operation called "activate" does that mean we would combine this from two sources or two different kind of activation to choose from. Multi-inheritance problem that is really hard where classes overlap. One of the challenges to address here.
MM: informative appendix in TD -- need parametrized URLs. We probably need to include parameters for URI templates. Also version control need to handle with TDs. Mandatory/optional items also needed to figure out. On naming and name conflicts, oneDM has objects and namespace mechanism that can be leveraged. Still need to resolve URL conflicts. If templates conflict. Need templates for namespaces? Combining interfaces results in multi-inheritance. Some of the concrete issues we have come accross.
CB: URI templates mechanism to get computed URIs. Client can compute them. Not necessary what people from REST paradigm want to do.
MM: TD template defining class, and has URI templates. When instantiate TDs would make URLs out of those. Templates could still show up in responses. Even with templates could have same URL for events/actions/props. Even after namespaces. Need to figure out how to solve the issue.
CB: server's role of coining URIs is partially delegated to client. If do this in a way that client starts to hard-wire delegations without asking the server, we run into all these problems. In IETF have BCP190 principle: standards can not dictate how servers handle URLs. Some wisdom from there could go into component models. Component should not dictate how server will offer these URIs. Composite model coul do that, but component not.
MM: how to define resuable components and avoiding name conflicts. Can have a look at BCP190.
CB: RFC7320
MM: related use for templates: dynamically generated URLs.
CB: agree but don't like word template.
MM: arguing the name right now. Parked now.
CB: URI template is taken
MM: could be TD classes, partial TDs, etc.
CB: talking about URI templates, not TDs. RFC6570. Interesting but not very well defined mechanism.
MM: There might be other ways to do computed URIs
## TD Template SDF examples (Michael Koster)
MK: were supposed to be converged from OneDM. Have not reached a stage we'd have something to show.
SK: can show what was presented in TD call today. See https://github.com/w3c/wot-thing-description/issues/903
MK: OneDM is class description. Even type description. Trying to tease out where the boundaries are of creating models and turning into instances.
SK: Daniel made comparison: https://danielpeintner.github.io/wot-pages/sdf/
But don't take all this serious. Just started discussion.
First part SDF metadata. In TD have same info. Versioning in our case is container that does not fit what intended with SDF. Would like to describe version of class in WoT TD the thing description instance version. Not really fitting; will have to think if want different terms. We had lots of discussion on copyright and license: makes lots of sense to use web linking. Can use rel terms. Registered by IANA alraedy.
CB: should right column be TD or TD template?
SK: template
CB: TD copyr should say what classes it's composed of
MM: could be additional info on link.
SK: namespace; thinking of using id field for identifying the context of all the stuff defining in the template
CB: some fresh text in the github on the spec that explains how namespaces might work. Reflects this week's discussion. May change but yesterday had impression that might be good first step.
MM: for IDs have been looking into Decentralized IDs, W3C work. Could discuss in the WS. Some interesting properties.
SK: odmObject used for composition of actions, properties. Had lots of discussion on that if needed. Since can have multiple occurrence, that is possible, however, we were thinking how to do this in TD template. Since allow multi occurrence of something run into naming clash. In JSON can't have same name in same level. If have opportunity of multiple options to reuse defs, how to handle name clashes. In RDF concept there is shape approach, also standard from W3C. There can define multiple occurrences. Actions and properties aligned. Forms definitions can be ignored for now. Finding out that enumerate defs. Can define that with JSON schema so can copy all info from left side to JSON schema def.
What is missing in TD template is functionality to point existing defs with Xpointer. But long discussion in the past and in the pipeline that we want to support that. Able to define data schema in global manner.
Welcome to discuss this. If like and interested will discuss in next TD meeting. Can invite there.
MK: with odmData SDF constructs each of these terms we define in OneDM has stable URI that can be used in other defs. Point of namespace is to have stable prefix for the URIs. Same function as in RDF and JSON-LD. Looks the same for the same reason.
CB: URI talking about not about what is going on on the wire but way of structuring the namespaces of description format. Completely different from on-wire stuff.
MK: yes, not going into deep semantics of what on/off means but provide handles where you can hook up ontologiess. Just want to provide semantic anchors. When look at left and right of enum. Terms on/off are semantic anchors. ...
If put class names in the URI can just use On/off since Switch part of the URI in the def.
On the right (TD) would be hard to construct these. Could be oneOff but does not provide semantic anchors. Representation part without the semantic anchor. What did in OneDM have separate classess from instances. Only describe classes. For instances have bindings. TD is more like protocol binding on what we are doing. Can use OneDM to annotate affordances and descriptions. This is how you turn switch on in OpenAPI or AsyncAPI.
What we do with TD templates, provide these classes also in more TD like format so that we can easily create TDs from templates. Have couple of questions: will TD template have stable URIs like in OneDM or is that different place in the workflow.
Discussion on workflow is interesting and important. Who is using this and what are they using for? Do they normalize different models?
MM: two kinds of discovery 1) classes 2) instances. DIDs are forming stable URIs. Interesting avenue to look at. Structuring semantics vs protocol binding. OneDM does good job for semantics. Need to also disscusss the binding. Developer may want to know what protocol used. Now part of URL. Also need to think how to avoid name conflicts in URLs. URL prefix is nice if have multiple bases for component. But base also includes protocol that is bad for objects that use multiple protocols.
Need to think how to make protocol binding modular.
MK: discussing URIs in protocol exchanges, want to make sure we keep distinction to URIs that point to semantic anchors and terms. Not that much similarity there. Modular protocol bindings yes.
MM: lack in back end protocol binding -- need to define partial protocol binding.
MK: ... thing decsriptions could be where parametization happens
MM: need to discover classes
MK: approaching the developer facing aspect: want to explore commonalities of ways to model things. When want to do something new, how do I find something that has already been done.
MM: motivation of easy discovery of classes is to avoid divergence
## W3C WoT / T2TRG workshop plans and preparations (Michael McCool)
* Plugfest activities (Sebastian Käbisch)
SK: have discussed in the TD call what want to test in plugfest. Approach of querying action state. Would like to point to proposal. Look at off-line and to discus in the next meetings.
See https://github.com/w3c/wot-thing-description/issues/899
https://github.com/w3c/wot-thing-description/tree/master/proposals/hypermedia-control
SK: cool if can review that
MM: have discovery, lifecycle, data modeling issues. Discussing schemas, hypermedia actions. Have only about 3 hours. Need to be careful with our time. Have scheduled 90 minutes already. Suggestion here to capture additional topics in particular form IRTF side.
OneDM and schemas might belong to joint topics.
Hypermedia controls in TDs something to talk about. Data schemas.
JSON schema. Formal data schema (CDDL).
Data schemas may need to go to future WS.
CB: bit more time for preps useful too. One or two WISHI calls.
AK: instead of OneDM/TD comparison should be how they work together.
SK: also TD templates
MM: and modularity
MK: working on some topics on that already. More about workflow: how they are going to be used. That would be productive.
MM: seems have full agenda. Logistics?
CB: *AP* will move RG parts to Github
MM: time agreed? And RG will allocate webex.
## Next call 1355Z
AK: going forward Klaus will be taking a lead on organizing WISHI activities. What's good time for next call?
CB: 29th?
1200Z to 1400Z slot, again.
MM: serious conflict wed, zero on Friday 29th and Tuesday 26th.
KH: can setup Doodle