From 2095bfb252aec7c0d20a5fbe51805a395fb8c2d9 Mon Sep 17 00:00:00 2001 From: reluc Date: Wed, 15 Apr 2026 12:35:25 +0200 Subject: [PATCH 1/5] feat: handle interaction error response algorithm Initial draft of the algorithm to handle interaction error response, as described in the issue #560. Referenced in readProperty method. --- index.html | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index f527b7a..b42a301 100644 --- a/index.html +++ b/index.html @@ -355,7 +355,7 @@ The generic WoT terminology is defined in [[!wot-architecture11]]: Thing, Thing Description (in short TD), Partial TD, Web of Things (in short WoT), WoT Interface, Protocol Bindings, WoT Runtime, Consuming a Thing Description, TD Directory, Property, Action, Event, DataSchema, Form, - SecurityScheme, NoSecurityScheme etc. + SecurityScheme, NoSecurityScheme, AdditionalExpectedResponse etc.

WoT Interaction is a synonym for Interaction Affordance. @@ -366,6 +366,10 @@ Hence for the sake of readability, this document will use the previous term WoT interaction or, simply, interaction instead.

+

+ interaction method indicate one of the method defined in the {{ConsumedThing}} interface + to interact with a Thing (e.g. readProperty(), writeProperty(), invokeAction(), etc.). +

WoT network interface synonym for WoT Interface.

@@ -1434,6 +1438,91 @@

The ActionInteractionOutput interface

title="Error handling"/>
Error handling in WoT interactions
+ +
+

The InteractionError interface

+

+ Represents an error that occurred during a WoT Interaction with + additional diagnostic information from the Thing in the form of + response data associated with an AdditionalExpectedResponse defined in + the Thing Description. +

+ 
+        [SecureContext, Exposed=(Window,Worker)]
+        interface InteractionError : Error {
+          constructor(DOMString message, InteractionOutput data);
+          readonly attribute InteractionOutput data;
+        };
+
+

+ The data attribute represents + the {{InteractionOutput}} object containing the response payload from the + failed WoT Interaction. +

+
+ +
+

The handle interaction error response algorithm

+

+ This algorithm is used by interaction methods to process error responses + from the Protocol Bindings and determine whether to create an + {{InteractionError}} or map to a standard error type. +

+

+ To handle interaction error response given |error|, |form:Form| and |response|, + run these steps: +

+
    +
  1. + if |response| is not defined or null, attempt to map |error| + to a suitable {{DOMException}} or, if none, to {{OperationError}}. + Return that error and stop. +
    2. +
  2. + Let |additionalResponses| be |form|.|additionalResponses|, if it exists. +
    3. +
  3. + Let |binding| be the binding that was used to make the request which resulted in |response|. +
    4. +
  4. + If |additionalResponses| is defined, for each |responseEntry:AdditionalExpectedResponse| in + |additionalResponses|: +
      +
    1. + Let |match| be a boolean expression that checks if |response| matches a |responseEntry| according to |binding| +
      2. +
    2. + If |responseEntry|.|success| is `false` or not defined and if |match| is `true` for |responseEntry|, + then run these sub-steps: +
        +
      1. + Let |responseSchema| be |responseEntry|.|schema|, if it exists. +
        2. +
      2. + Let |errorOutput:InteractionOutput| be the result of running + parse interaction response on |response|, |form|, and + |responseSchema|. +
        3. +
      3. + Return a new {{InteractionError}} constructed with |errorOutput| an appropriate + message derived from the |binding| or |error|. +
        4. +
      +
      3. +
    +
    5. +
  5. + If no match was found in |additionalResponses| but |binding| indicates + a failure, attempt to map the error + to a suitable {{DOMException}} or other appropriate + error type. +
    6. +
  6. + Otherwise, return {{OperationError}}. +
    7. +
+
+

This topic is still being discussed in Issue #200. @@ -1635,7 +1724,18 @@

The readProperty() method

using |form| and the optional URI templates given in |options|.|uriVariables|.
  • - If the request fails, [=reject=] |promise| with the error received from the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the followingsub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Let |response| be the response received to the request. From c60275f38af427b55201fd36f697fa6b39b99d74 Mon Sep 17 00:00:00 2001 From: reluc Date: Wed, 29 Apr 2026 12:28:45 +0200 Subject: [PATCH 2/5] link error handling algorithm to all ConsumedThing methods --- index.html | 116 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 104 insertions(+), 12 deletions(-) diff --git a/index.html b/index.html index b42a301..14cbd28 100644 --- a/index.html +++ b/index.html @@ -1778,11 +1778,26 @@

    The readMultipleProperties() method

  • Let |result:object| be an object and for each string |name:string| in |propertyNames| add a property with key |name| and the value `null`.
    • +
  • + If this cannot be done with a single request with the Protocol Bindings, [=reject=] |promise| with a + {{NotSupportedError}} and stop. +
  • Make a request to the underlying platform (via the Protocol Bindings) to retrieve the Property values given by |propertyNames| with |form| and optional URI templates given in |options|' |uriVariables|.
  • - If this cannot be done with a single request with the Protocol Bindings, [=reject=] |promise| with a {{NotSupportedError}} and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Process the response and for each |key| in |result|, run the following @@ -1850,7 +1865,18 @@

    The readAllProperties() method

    If this cannot be done with a single request with the Protocol Bindings of the Thing, then [=reject=] |promise| with a {{NotSupportedError}} and stop.
  • - If the request fails, [=reject=] |promise| with the error received from the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Process the reply and let |result:object| be an object with the keys and values obtained in the reply. @@ -1920,7 +1946,18 @@

    The writeProperty() method

    |options|' |uriVariables|.
  • - If the request fails, [=reject=] |promise| with the error received from the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Otherwise [=resolve=] |promise|. @@ -2004,8 +2041,18 @@

    The writeMultipleProperties() method

    with a {{NotSupportedError}} and stop.
  • - If the request fails, return the error received from the - Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Otherwise [=resolve=] |promise|. @@ -2093,8 +2140,18 @@

    The observeProperty() method

    optional URI templates given in |options|' |uriVariables|.
  • - If the request fails, [=reject=] |promise| with the error received from - the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • [=map/Set=] |thing|.{{ConsumedThing/[[activeObservations]]}}[|propertyName] to |subscription| and [=resolve=] |promise|. @@ -2183,7 +2240,18 @@

    The invokeAction() method

    Make a request to the underlying platform (via the Protocol Bindings) to invoke the Action identified by |actionName| given |args| and |options|.|uriVariables|.
  • - If the request fails locally or returns an error over the network, [=reject=] |promise| with the error received from the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |form| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • Let |value| be the reply returned in the reply. @@ -2272,8 +2340,18 @@

    The subscribeEvent() method

    and optional subscription data given in |options|.|data|.
  • - If the request fails, [=reject=] |promise| with the error received from - the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + {{Subscription/[[form]]}} and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
  • [=map/Set=] |eventName| to |thing|.{{ConsumedThing/[[activeSubscriptions]]}}[|eventName|] to |subscription|. @@ -2489,8 +2567,22 @@

    The stop() method

    unsubscribe data given in |options|.|data|.
  • - If the request fails, [=reject=] |promise| with the error received from - the Protocol Bindings and stop. + If the request fails with error |receivedError| and optionally |failedResponse|, + run the following sub-steps: +
      +
    1. + let |error| be the result of running + handle interaction error response given the |receivedError| + |unsubscribeForm| and |failedResponse|. +
      2. +
    2. + [=Reject=] |promise| with |error| and stop. +
      3. +
    3. + If the underlying platform receives further notifications for this + subscription, implementations SHOULD silently suppress them. +
      4. +
  • Otherwise: From 8120d4be90b301a33e35307aed85232baa01aa1b Mon Sep 17 00:00:00 2001 From: reluc Date: Wed, 29 Apr 2026 12:32:45 +0200 Subject: [PATCH 3/5] improve interaction error response intro --- index.html | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index 14cbd28..8defd91 100644 --- a/index.html +++ b/index.html @@ -366,10 +366,6 @@ Hence for the sake of readability, this document will use the previous term WoT interaction or, simply, interaction instead.

    -

    - interaction method indicate one of the method defined in the {{ConsumedThing}} interface - to interact with a Thing (e.g. readProperty(), writeProperty(), invokeAction(), etc.). -

    WoT network interface synonym for WoT Interface.

    @@ -1464,9 +1460,9 @@

    The InteractionError interface

    The handle interaction error response algorithm

    - This algorithm is used by interaction methods to process error responses - from the Protocol Bindings and determine whether to create an - {{InteractionError}} or map to a standard error type. + This algorithm is invoked by any {{ConsumedThing}} method that performs a WoT Interaction. + It processes error responses returned by the Protocol Bindings and determines whether to + throw an {{InteractionError}} or map the response to a {{DOMException}}.

    To handle interaction error response given |error|, |form:Form| and |response|, From 8b054c06411fe11f3c2fd38fe79963b1ff320855 Mon Sep 17 00:00:00 2001 From: reluc Date: Wed, 29 Apr 2026 12:36:26 +0200 Subject: [PATCH 4/5] change Editor's note in Error handling section --- index.html | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/index.html b/index.html index 8defd91..dabaf2e 100644 --- a/index.html +++ b/index.html @@ -1437,6 +1437,10 @@

    The ActionInteractionOutput interface

    The InteractionError interface

    +

    + Currently, we are looking for wider implementation of the following section. + The alorithm presented here might be subject to changes in the future. +

    Represents an error that occurred during a WoT Interaction with additional diagnostic information from the Thing in the form of @@ -1518,16 +1522,6 @@

    The handle interaction error response algorithm

    • - -

    - This topic is still being discussed in - Issue #200. - A standardized error mapping would be needed in order to ensure consistency - in mapping script errors to protocol errors and vice versa. In particular, - when algorithms say "error received from the Protocol Bindings", - that will be factored out as an explicit error mapping algorithm. Currently, - that is encapsulated by implementations. -

    From 0b8567dadf987c9c2c89b37f00f244a29e3b0098 Mon Sep 17 00:00:00 2001 From: reluc Date: Wed, 13 May 2026 15:28:38 +0200 Subject: [PATCH 5/5] fix: minor typos --- index.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index dabaf2e..8ab9477 100644 --- a/index.html +++ b/index.html @@ -1439,7 +1439,7 @@

    The ActionInteractionOutput interface

    The InteractionError interface

    Currently, we are looking for wider implementation of the following section. - The alorithm presented here might be subject to changes in the future. + The algorithm presented here might be subject to changes in the future.

    Represents an error that occurred during a WoT Interaction with @@ -1504,8 +1504,9 @@

    The handle interaction error response algorithm

    |responseSchema|.
  • - Return a new {{InteractionError}} constructed with |errorOutput| an appropriate - message derived from the |binding| or |error|. + Return a newly constructed {{InteractionError}}, using a message + derived from the |binding| or |error| as first argument, and |errorOutput| + as second argument.