Should Scripting API be normative?

[mmccool]

Current the Scripting API is a non-normative Note. However, it does define an API which, while not required for WoT implementations, should be implemented consistently to allow for portability of scripts. In order to encourage script interoperability, should we make this spec normative in the next charter?

[benfrancis]

As I understand it this has been discussed several times and the conclusion was always that the Scripting API should not be normative.

My personal view is that the Scripting API doesn't really need to be a specification at all, it should just be an open source JavaScript helper library (it is quite JavaScript specific). Or possibly two separate libraries, a consumer library and a producer library (arguably that's what node-wot already is). I also think it's fine for the description of the API (used by node-wot) to continue to be maintained as a WG Note if there are people who want to maintain it.

If it was standardised, what form would the implementations take and how would they interoperate with each other? Usually the consumer of a JavaScript API is a web page. What are the consumers of a WoT Scripting API? Is it a JavaScript app runtime for IoT applications (separate from the web app runtime of web browsers)? I don't think WoT should take that route. (The WebThings Gateway add-ons runtime arguably provides something a bit like this on the ExposedThing side, but the programming interface there is a language-agnostic WebSocket-based IPC mechanism rather than a language-specific scripting API, so that adapter add-ons can be implemented in different programming languages).

Based on my limited understanding of the WoT Scripting API:

• The ConsumedThing interface is really just an abstraction over existing browser APIs like fetch, but which no browser vendor intends to implement natively in a web browser, so it makes sense as a client-side helper library.
• The ExposedThing interface is really an implementation detail for Node.js based Thing implementations (again it's quite JavaScript specific). It's not exposed to Consumers, it is presumably only exposed internally within a Thing implementation to register internal handlers for incoming requests at the protocol level. It could be a server-side helper library (e.g. an npm package).
• The ThingDiscoveryProcess similarly appears to be a high level internal API for initiating different discovery processes inside a WoT Discovery client.

Every Consumer and Thing implementation will implement something like these interfaces internally but they will differ for different programming languages (e.g. not all languages have the concept of Promises, which the Scripting API heavily relies on). In my view there's not really a need for the API to be standardised, since the "narrow waist" of WoT is not at the scripting API level, it's at the Thing Description and protocol binding level. The internal scripting APIs implemented by Consumers and Things can be (and are) implementation specific.

[danielpeintner]

Note: In the recent past there was a somewhat lengthy discussion (see w3c/wot-scripting-api#354) which led to decision in the main call to move Scripting API from W3C Note to Note Track.

This change implies that we can use normative statements like MUST in the document.

My personal opinion: I think "Note Track" is what we need. I fear going for REC causes push-back, not only for scripting but the entire WoT charter.

[egekorkan]

Some of my opinions:

• It would be really nice if in the future all browsers come with a WoT.consume() function so that no one needs to add a helper library. Unless this is possible, we should not push for a REC. It would be nice to talk with browser vendors to see if this is possible or what is needed.
• The spec should keep the JS focus but the overall ideas can be applied to any language.
• I do not think that fetch API alone solves the problems of a WoT developer. Fetch does not support websockets or SSE, which are possible in the browser. So a WoT developer who wants to build a dashboard web app, needs to handle HTTP, SSE and all possible WS subprotocols and then all the logic to handle and parse TDs.
• It should be possible to use assertive words in all our specs so the Note Track is good direction.
• Exposed Thing side is indeed not exactly possible in a browser environment other than using WebSocket to make client side communication but having Thing behavior. I am not aware of a use case that has this so it is just a thought experiment.

[zolkis]

I agree with Ege, however Ben has valid points:

• browser vendors don't want the dependencies of WoT/IoT in the browser code base. We could have specific browser builds by putting native lib deps in third_party, but it's not upstream. I don't see it accepted generally by browser makers, not for a long time.
• I like the approach of standardizing a websockets flavor for WoT (in a CG)
• I agree the narrow waist is at network side API.

However, I do see value in "standardizing" (in the sense of the way of cooperation and documentation) a WoT scripting API, but I agree it should be non-normative, because the wild variety of possible client side implementations.
Anyway, when writing a Note for a scripting face of the TD spec, we need to be able to use normative language in non-normative documents. That has been a gap W3C needed to think about.

[relu91]

Sorry for answering late, my 2 cents:

What are the consumers of a WoT Scripting API? Is it a JavaScript app runtime for IoT applications (separate from the web app runtime of web browsers)? I don't think WoT should take that route.

In my understanding, even from the beginning, this was one of the goals of the group. Basically, the whole concept of the Servient is an app runtime for IoT applications and we have still (non-normative) sections that explain it throughout the architecture specification (e.g. https://www.w3.org/TR/wot-architecture11/#sec-servient-implementation).

What about the future? I don't know... putting bluntly it is clear that there is no production-ready implementation of a WoT runtime other than node-wot. The fact that we didn't convince any major browser vendors is also another downside. On this point, one concern that I have is that we might didn't try hard enough. For example, as far as I know, we have never tried to propose our work in https://www.chromium.org/teams/web-capabilities-fugu/, and the objections to introducing WoT API in browsers were made quite a few years back (when Web USB wasn't even a thing). As @egekorkan I would see some value in being able to consume and use Thing Description in a standardized way on the different deployment environments not only for applications but also for libraries.

One benefit of having a normative Scripting API document would be a consistent implementation of consumer and discoverers behaviors. Like for example, the long-running question of "how to choose a form" or how to deal with no-payloads for events and other implementation issues that we faced and recorded in the document. All of this might be squeezed as well in TD but we are keeping adding content to the TD document (protocol bindings and, now, maybe architecture too) that it might get out of hand.

Given the experimental nature of the scripting API, I don't mind if they keep staying on the Note track... however, the group should really decide the end goal. Do we want to use them as "node-wot documentation" or do we want to push its implementation in Javascript runtimes?

[relu91]

p.s. sadly I have a conflict with today's charter discussion, but I'll be there for Wednesday and in the next arch slot.

[mmccool]

It seems to me that there would not be an objection to making the Scripting API "Note Track" (allowing use of normative language) but there does not seem to be consensus on making it REC track.

I would like to propose we make it Note Track in the next charter. Are there any objections to that? We'll have to look into whether we need to say anything specific in the charter or if what we have is sufficient.

[benfrancis]

@relu91 wrote:

In my understanding, even from the beginning, this was one of the goals of the group. Basically, the whole concept of the Servient is an app runtime for IoT applications and we have still (non-normative) sections that explain it throughout the architecture specification (e.g. https://www.w3.org/TR/wot-architecture11/#sec-servient-implementation).

The "Abstract Servient Architecture" described in the WoT Architecture document is aspirational at best and it certainly doesn't describe the current reality. It describes a very complicated programming language agnostic, protocol agnostic and serialisation agnostic application runtime for IoT which doesn't exist today and for various reasons in my opinion probably never will. I certainly don't see it ever being implemented by browser vendors since it describes something completely separate to and very different from the existing web application runtime provided by browser engines.

I hope that WoT Architecture 2.0 will drastically reduce and simplify a lot of this text to better reflect the reality of real WoT implementations.

The fact that we didn't convince any major browser vendors is also another downside. On this point, one concern that I have is that we might didn't try hard enough. For example, as far as I know, we have never tried to propose our work in https://www.chromium.org/teams/web-capabilities-fugu/, and the objections to introducing WoT API in browsers were made quite a few years back (when Web USB wasn't even a thing).

The work on WebUSB (and WebBluetooth, WebMIDI, WebSerial, WebGPIO, WebI2C etc.) actually predates the Web of Things Working Group (e.g. see the now defunct System Applications Working Group), and yet it is still a long way from being a W3C Recommendation. It is still only implemented in Chromium, with strong objections from the other browser vendors. Note that those APIs take a very different approach to the Web of Things*.

One benefit of having a normative Scripting API document would be a consistent implementation of consumer and discoverers behaviors. Like for example, the long-running question of "how to choose a form" or how to deal with no-payloads for events and other implementation issues that we faced and recorded in the document. All of this might be squeezed as well in TD

I do think these issues should be addressed in the Thing Description specification.

Given the experimental nature of the scripting API, I don't mind if they keep staying on the Note track... however, the group should really decide the end goal. Do we want to use them as "node-wot documentation" or do we want to push its implementation in Javascript runtimes?

I agree.

Fundamentally what I don't understand about standardising the WoT Scripting API is if it's meant to abstract away the need to parse a Thing Description and implement protocol bindings, then why also standardise the Thing Description and protocol bindings? Should WoT Consumers consume Web Things by parsing Thing Descriptions and implementing protocol bindings, or should they consume Things via the scripting API? It doesn't make sense to me to standardise both, it seems like the Web of Things is trying to be everything to everyone and risks losing practical interoperability in the process.

If the scripting API really was what we wanted to be the standardised interface for consuming things, then I would argue that standardising protocol bindings would not be necessary, since they would just be implementation details abstracted away by the WoT runtime. But that doesn't seem to be the current direction of the Working Group.

---

* FWIW I personally do think the Web of Things could be useful for web browsers, for exposing local hardware features to web applications in a safer and more web-like way than the controversial WebUSB/WebBluetooth etc. APIs, but that's a separate topic which doesn't necessarily require a new scripting API.

[mmccool]

Agree with Ben that trying to standardize BOTH the metadata format and the API is not necessary and potentially confusing. It's also easier to make the metadata format language independent.

In the long run, I do think there would be some value in standardizing descriptions of "behavior" such as automations. A script is one way to do that, but there might be better, more declarative ways.

[mmccool]

Anyway, I'm not hearing any strong arguments to make the Scripting API normative, I only raised the issue to confirm the status quo.

[relu91]

In the long run, I do think there would be some value in standardizing descriptions of "behavior" such as automations. A script is one way to do that, but there might be better, more declarative ways.

I would say that this is a conversation that we should have sooner or after. I'm ok with keeping Scripting API alive as an experimental thing, but if the group believes that its scope is just a node-wot documentation page there are better ways to develop that.

Anyway, I'm not hearing any strong arguments to make the Scripting API normative, I only raised the issue to confirm the status quo.

Yup, as far as the charter is concerned I think we can close the discussion...

[mmccool]

Propose Closing, with the resolution to NOT make the Scripting API normative.