# WISHI online meeting (24.4.2020)

April 24th (Friday), 6:00-8:00 PDT (15:00-17:00 CEST, 13:00-15:00 UTC)

Draft agenda:
* June "Helsinki" meeting
* Recent work in W3C WoT: Thing Description (TD) templates
* OneDM and WoT TD templates

Attending:
1. Ari Keränen (AK)
2. Andrea Fresa
3. Christer Holmberg
4. Andrea Pinto
5. Ege Korkan
6. Hendrik Walzel
7. Klaus Hartke
8. Michael Koster
9. Michael McCool (MM)
10. Sebastian Kaebisch(SK)
11. Niklas Widell
12. Gustavo Mercado (Tech University Mendoza Argentina)
13. Jonathan Beri (JB)
14. Carsten Bormann, TZI (CB)
15. Wouter van der Beek

Ari quickly introduces the WISHI meetings.
Agenda is bashed.

## June "Helsinki" meeting (McCool)
https://www.w3.org/WoT/IG/wiki/F2F_meeting,_1-12_June_2020,_Online
Tentative: June 8, 7/8am-11am Eastern
https://www.timeanddate.com/worldclock/fixedtime.html?msg=June+8+WoT%2FT2TRG+Workshop&iso=20200608T12&p1=1440
WebEx provided by W3C, collab with Web of Things

MM: WoT planning for a meeting in early June. Planned joint WS on the 8th. Tricky to have time that works for all. 9AM to 12 AM Atlantic (15-18 in Finland) time seems best. For 4-hour slot should start hour earlier. Probably want to check agenda is still up to date.

AK: sounds reasonable

MM: let's put up for review the time, abstract and detailed topics.

CB: would agree we need agenda with defined slots and program committee. To treat as a workshop. Next steps: setup the PC and send out announcements.

MM: propose to take WoT and T2TRG chairs and ask for volunteers

CB: four should be enough too

MM: let's setup meeting to discuss details

## TD templates intro (Sebastian Käbisch)

SK: have relased first set of docs from WoT as Recommendations. There mention Thing Description (TD) templates. TD is just roughly defined in the specs. TD templates one of the big topics in the new charter to be addressed in the next months in standards work. Hope can work together on the topic. Can benefit from each other.

Typically explain usage of TDs with web pages. Human understands context, information, content, understand if have to click somewhere, find form fields, etc. Typical way to get information and use it.
Similar behaviour for things? Automation engineers typically asking have plenty of questions: what/who are you? serial number? what context you have? are actor/sensor? what unit you use? what functionality have? what data server? what payload structure looks like? Also: how can I access the data? What protocol / serialization offering? How can use security? What's the relation to other things?

Example of typical Siemens device. Need to look up in the manual to get info what protocol uses, in the text find network info like "need to use port number X". In the PDF in table the detapoints described. Need to find out which modbus ID to listen to to get certain value, what big shifting to do, etc. Also info about unit. Have to do this for every data point given by device. Typically with automation scenario have tens of thousands of data points. Very error prone process. Errors discovered late and get expensive.
Other example: more device-rich IoT device. Heavily used in maker scene. If like to understand how to use sensor data: have to go to web page and to undersand how to use. Code snippets how to get data. This is the state of the art in IoT market. No "web page" for machines available.
Reason why W3C investigated topics. Set up Thing Description, "index html" for things. Common langauge on what thing is offering. Provides answers to the questions discussed in the beginning. TD is extensible: can add additional info in the TD that does not belong to TD domain. TD is just describing what is there. Not making something new. If have device used in industry, heavily use e.g., eClass. TD is designed so that you can integrate existing knowledge like eClass or iotschema. Not defining new protocols or behaviour, just saying "take the TD and describe what is your system setup".

Components of TD: starts with JSON-LD context framework, security frameworks used in the market can be specified (how to securely interact), able to define relation types using web linking concepts. New thing standardized: property, action, event concepts. Data model is based on JSON schema. Binding templates have all the stuff needed to know what protocol and serializations used. Cool thing that data model separated from underlying protocol.

Example of TD: context and type from JSON-LD. Security info of oauth. Property, action, events descriptions. JSON schema embedded in type. Semantic annotations like "iot:Unit" and "iot:TurnOn" from iotschema. Links provide relationship to other things. Protocol binding in forms: uniform documentation of IoT protocols. Done for HTTP, MQTT, and CoAP so far. Can express special ways to use CoAP for OCF, for example. Also possible for other protocols. Node-wot has bindings also for websocket, modbus under development, OPC-UA binding, and also NETCONF.

AK: OPC-UA support ready? Not mentioned in README

SK: yes, full support. Need to update README.

SK: (continuing presentation) No restriction where to use TDs. Can retrofit old things with TDs.

MM: have discovery topic on current charter: how to get TD. Need to define .well-known etc. Also directory services planning to play with in the upcoming plugfest. To handle case with separate system describing a thing.

SK: also discovery task force where addressing this kind of topics. Can provide TD on edge devices to describe what data connected to. TD can be used for onboarding field devices to cloud system, digital twins. Can use TD for simulations, testing, making apps, etc.
The spec has some first approach of TD templates. Describes class of things. Things common with thousands of devices. Main difference to TD instance: not security setup or communication metadata. In many cases enough to describe IoT application. Just data model. Little bit in the direction what have in OneDM SDF.
Motivation for templates: mass production; just one TD for that. Instance only important when lamp is deployed with communication metadata: IP address, port number, etc. TDs important for Digital Twins; can already simulate devices and start with testing based on templates.

MM: in software development need class definitions

SK: if want to create new things and combine different TD models, and don't want to invent new one, can combie them. Still discussing if useful feature. First definition in the draft spec now (see page 14). Have list of features requested in Github. ... Idea of import/extend discussed. Now Bosch onboard with WoT and Eclipse Vorto project member.

Some open questions. What is TD and what happens when we exchange them. What is expecation? Should TD always be self-contained? All info should be defined as we expect with TDs? Or do we have depencies there; like point to other definitions and client has to organize them to get full info. Currently discussing.
Also what is minimum requirement for TD template? Empty object? Just context, maybe title/type, etc.?

CB: makes sense to look at SDF issues

SK: use cases and motivation would be interesting. Compared to TD templates and all info in SDF is easy to reflect also in TD. Title, versions, etc in TD metadata. Don't have copy-r and license but no big deal to motivate this and integrate it. Also easy to integrate to TD with extension.

MM: also with links, for example with license.

SK: name space concept interesting. Also have this in TD template but JSON-LD takes care of that. odm in the names is different. Have prop/act/events in TD too. Would understand odm is prefix. Can represent all the info in TD. 90% is identical to TD. Would provide SDF name space and SDF specific vocabulary. For odmProperty would put "@type".

MJK: alignment is very intentional. What did with SDF is aligned with TD intentionally. To enable easy communication between. That's a feature. Event/action/property model very well known across industry. Made a spread-sheet of different data models ("metamodel survey" shared on screen). In SDF wanted to unify the language different models are expressed.
Doing the same thing but problem set out to solve: looked at a few different priorities, ended up building a system where we can provide URIs as semantic anchors. Each concept, like over-heating, has URI in OneDM. Similar to iotschema. But didn't attract device or product vendors. Started in OneDM with those and tailored SDF to work on what was delivered. Ended up with CI, ways to submit models, schema-driven editors, etc. Overlap with, problem being solved of normalizing across models, is common. With WoT chose a mission/scope that specifically excluded any application vocabularies. Just protocols. Activities outside of WoT have excluded the protocol bindings, or even data schema. Reason is to partition the problem and focus on creating vocabularies. Naturally can be transferred from one to another. OneDM SDF similar to iotschema for WoT TD. TD template as a thing that could take SDF and make TD template of that and effortlessly compose into TD. Vorto has features to add here for functional behaviour definition. But intentionally conceptually aligned at low level. But different problem to solve in complementary set of solutions. What looking at with OneDM is same as with iotschema: have fixed URIs to reference well-known concepts. What is different between iotschema and SDF: ...

SK: have JSON based approach, with name space container. Is it same idea as "@context" of JSON-LD

MJK: good question; wanted to mention. Originally wanted to use JSON-LD for SDF. Would have been interesting approach. But really only needed the namespace feature. The other LD and RDF was just extra baggage. Wanted to have schema-driven editors, etc. Patter we built for name space prefix is compatible with how JSON-LD uses it. Maybe not all details round-trip transffer, but not important. But wanted separate name spaces for developers. Went to be exact like JSON-LD

SK: can sell JSON-LD as simple JSON format where info is there, if want also RDF you have it.

MJK: these could also be JSON-LD. Just add context tag. Have been using context file and shapes. Technology for RDF, shape driven editors, and -LD framing, the tools around those are not as well developed as JSON schema. Ari has built couple of schema-driven front-ends and tools. Eventually planning to evolve this to RDF. Want to convert these to iotschema with JSON-LD framing and shapes.

SK: to be fair, framing, shapes, shacl, are on the way being standardized by W3C. Tooling should be now stable and should be enough. Not expert user, used just for TD use. There are tools out there that seem fine. One or two years ago, can imagine the tools were not good yet since standard wasn't ready either.

MJK: true, now at the point JSON-LD and SHACL tools give lot more than year ago. Definitely a direction where would like to go. JSON part could be used for front-end, etc. JSON-LD gives nice entry-point to RDF.

SK: the discussion still open to rely on -LD?

MJK: in OneDM decided on-wire schemas and protocol bindings be out of scope. That functionality already exists in TD. Can use OpenAPI or Async-API for protocol binding. Don't need to invent new ways of doing things being done already. Need to pick the problem to solve. Would probably use TD template instead of adding context file to SDF. Could just convert to TD template. Two things that problem: have object and thing layers where we can compose on. SDF definitions are modularized so that little thing can be composed into complex ones.

SK: what can think of; have to understand SDF deeper. Maybe there are features we don't have in TD templates yet. Could discuss what we should have. Last time was discussion on starting new RFC for this. What TDs don't have, but SDF can specify, and provide this in namespace. Can integrate this in namespace in TD.

MJK: If were to align TD, add class and other things we call qualities in OneDM. Then TD templates, and IoT schema and OneDM, and other models like smart things capabilites, would just be different serializations of same model. Could translate losslessly between. In both cases want to take existing models and make TDs out of them. Harmonize models with SDF. Ended up with something that looks very similar. TD templates might start with simple description of affordances. Then would look a lot like the only thing we have with OneDM. Data types. ...
Template what it needs -- can be considered protocol binding step. Node-wot has bunch of protocol bindings. This just needs to hook up. When someone wants to do device definition for OPCUA device. They have data model that can be expressed with A/E/P. What workin on with WISHI is semantic proxy. That shows how all this stuff gets glued together. In semantic proxy TD template and SDF could be interchangeable. We don't have protocol binding where as TD has development work on that, and lines of code. IoT schema has only very few terms. Have to think how to add object class, how to compose, etc. Lightbulb for TD would have all in flat space. Need to reconsile that there is junk of functionality of cluster/capability/object and those have semantic anchors and what is used semantically discover from apps.

MM: need a way to preserve structure

MJK: semantic bread-crumbs. Can call it "mute" but still need to know it's "on-off-control" to get right logo in the GUI etc.

MM: JSON schema is used by OneDM and TDs. But not standard yet. Have small variations.

MJK: also need everyone to use the latest version

MM: need to sort that out. Use consistent version and get that version into proper standard. And action item that needs to happen.

SK: also in SDF have subset of JSON schema

MJK: had to duplicate the definition of JSON schema. Would like to take all of. Didn't start with that. OTOH some people say that don't want a feature and should not be included. We don't have the bar of W3C standard requiring implementation of all features so can move faster.

MM: if JSON schema became standard could define a profile for IoT. Could be subset. If feature missing in one system, breaks interop

MJK: agreed subset would be the standard. Don't process schemas in constrained devices. IoT data schema could be formal subset.

SK: next steps?

MJK: could take OneDM defs and make example TD templates. Try simple TDs. In OneDM really focused on developer tooling. In WoT on network tooling.

SK: in Helsinki meeting the next joint meeting. Web meeting? Could pick examples today? Look deeper in one of the next web meetings and go more practical in one of the plugfests.

AK: usually decide next meeting at the end of call

SK: if MJK could provide example that is interesting could see how to use that in node-wot and apply that in next plugfest

MJK: can point to couple of good examples. Can browse around if have time. Placeholders etc discussed this morning for TD templates. Did a few iterations on SDF already. Use JSON pointers in SDF. ...

SK: interested in JSON pointer approach .. point to particular doc?

MJK: node in a doc. Can reuse data def, event, action, property [...].

SK: good to have WISHI call before Helsinki meeting. Could discuss examples we can work on together and look how they look like in TD. Could work on examples for plugfest.

AK/SK: Friday May 15th one hour earlier?

MJK: 5AM is OK.

AK: two hours. Main agenda item?

SK: discussing examples. Preparations for plugfest.

MM: Workshop. Discovery APIs. Would overlap with semantics stuff. Looking into JSON path for that. Half hour on that would be useful too. WISHI people are welcome to attend plugfest. Will be software VPN used.

JB: working at IoT startup. Focusing on developer experience. Using CoAP and CBOR today. Looking at how development today, automating tooling -- one of the topics API descriptions. WGs focusing on traditional REST APIs, streaming protocols like Kafka, and if you squint they look somewhat compatible with what we discuss. Interest in those areas on IoT use cases. General discussion on what's the interest in using API definitions. Would make sense the work between OpenAPI and AsyncAPI part of this initiative, and how to bring to CoRE projects. Compatibility thing; or better solutions for CoRE. Love to get feedback and get some discussion offline perhaps.

MJK: very interesting. OCF uses OpenAPI. That's definitely in the scope. Interesting to see examples of TD and what that looks like in OpenAPI and AsyncAPI. See for opportunities around semantic conversions. How to represent on/off in OpenAPI/AsyncAPI. TD already does that. Maybe AsyncAPI has a few affordances. Could focus there in this group. How these work with semantics.

MM: OpenAPI was originally for validation and documentation. Here we talk a lot about automation of tools. Have done quite a bit of usecase work in WoT but developer use cases need to be clarified. What do we need this for.

MJK: in semantic proxy take SDF and spit out OpenAPI

MM: for agenda let's set use case for developers. NodeRED modules is one. Could talk about the requirements.

JB: authors of OpenAPI are contributing to AsyncAPI. Lots of the use cases targeted are true for the Async too. Just pub/sub type.

MM: question of scope and overlap of different specs

MJK: need to look at how used

AK: seems we have agenda items for next call and actions in between. Any other issues before we close?

MJK: as Carsten pointed out in the chat, we should plan to have more discusion on TDTs

AK: Agree

(meeting ended)