Action - double check node-wot's error codes, are there error response payloads?

[danielpeintner]

see recorded action https://www.w3.org/2021/05/06-wot-arch-minutes.html#a04

node-wot is an implementation of the Scripting API which is defined in WebIDL. As such, errors are also described with the according error codes (see https://heycam.github.io/webidl/#idl-DOMException-error-names), e.g.,

• SyntaxError
• SecurityError
• NotFoundError
• ...

As one can see the list is abstract (which I think should remain so) and does not provide protocol specific errors.

See also error handling in the scripting API which references Issue #200 about mapping error codes.

Hence, the format of an error response (besides some textual description) is not yet described in the Scripting API. Moreover, I don't think a fully fledged out error description for every protocol will ever be the case since we want to be independent from an actual binding.

What I could imagine are some protocol specific flags to identify the protocol in use with some additional hints...

@zolkis @relu91 anything you would like to add?

[zolkis]

The reason for mapping errors to JS is to be able to write binding-agnostic code, i.e. portable across protocols.

Also, for privacy and security reasons, using opaque data in errors is not recommended, so implementations would need to be able to translate protocol specific error information to standard terms that can be used in scripts.

That means WoT should be able to describe interactions that use protocol-specific payload formats in errors or success responses, and map these to web-friendly formats.

In general the TD spec should provide all mechanisms to be able to do this, including interaction definitions that include error handling and content handling as well.

Right now a lot of things are not specified in the TD spec (e.g. in property writes, can the response or error have content payload and how is that represented). This is done by e.g. most Swagger definitions and it should be doable in TDs.

It is not a technical problem in Scripting to represent protocol-specific payloads in responses, including property writes, see the InteractionOutput interface.

However, for payloads included with errors we'd need to create a special Error object which has an optional data property. There is a problem, given the preference (by the TAG design principles doc) to use standard errors, and the ECMAScript spec allowing only stringifiable input in error constructors. Subclassing Error is usually done for new error names, not for added error data. We can add error data (as an object property) and throw that, but it's not guaranteed to be interoperable between browsers and it's not future-proof, either. I guess we won't be bothered by that for now (and in node-wot).

Also, there is the question how to represent that error data: by a full InteractionOutput (including streams, binary data, JSON, etc)? Remember that low-level access to protocol-specific error information is privacy and security sensitive, so preferably we want them translated (for which we need to collect the use cases, then define and standardize the mappings).
So yes, if data can be present in errors, these need to be standardized in the TD spec.
(IMHO when non-standardized data is included in errors, that is already a broken interface design, but let's put that apart).

However, the counter-argument was that this is not necessarily needed, since all interactions that return data meant to be used by the app can and eventually should be modeled as Actions. Modeling them as actions would solve the problem since that moves data handling to the success branch. That means for certain things (e.g. Echonet, Philips Hue etc), the TD definitions may be more complex and less beautiful than if property writes could return data and if errors could have data attached to them, but still doable.

[zolkis]

FWIW in real-world devices (e.g. several OCF device types) may use payload with certain errors and also with certain success responses.

As also mentioned here, in most cases this is used for conveying simple types or simple JSON objects, never streams or binary data.

On success case (e.g. on writes, i.e. responses to a PUT or POST), it's mainly equal to the values sent, so WoT Scripting implementations can encapsulate them (just check for equality). But still there are gaps in TD, for modeling precision and step besides range.

On errors, the payloads usually provide textual context (which can be mapped to an Error.message), or (more rarely) specify error resolution options (which would better be represented by Actions). So based on these use cases alone, we don't need to add data property to Error objects, but in general one may argue it would make sense.

So the TD should be able to model these payloads both in success and error responses (as Body), i.e. specifying content type and optionally DataSchema.

I think the first action point is on the TD TF, then that would propagate to Scripting, Bindings, etc.

[mlagally]

@danielpeintner , @sebastiankb
The discussion is about requirements for the TD specification which should be continued in the TD TF.
I have created w3c/wot-thing-description#1691 for the important requirement to describe structured action responses that contain a metadata envelope and a response value.

Let's close this issue, since it is not profile specific.

[danielpeintner]

I suggest to close both issues, this issue and w3c/wot-thing-description#1691.
The discussion came up during an Architecture/Profile call and it is more or less a summary of possible error codes but not per se an actual "issue".

[danielpeintner]

Since w3c/wot-thing-description#1691 has been closed I think we can close this issue also.