Event Affordance subscription and cancellation payloads are not usable by scripting

[egekorkan]

In the TD spec, the Event affordance has the subscription and cancellation keys. With these keys, one can describe a payload that needs to be passed along for subscribing or unsubscribing from an event.

In the Scripting API, this behavior is not specified explicitly for the subscribeevent method and is not specified at all for the unsubscribeevent method. For subscribeevent, it is said that one can use InteractionOptions vocabulary which however says that currently they are used only for URI variables. For unsubscribeevent, InteractionOptions do not seem to be even allowed.

A further discussion would be whether these are actually interaction options or params like the invokeAction() method.

[zolkis]

The question is, from where the subscription and cancellation options (data) come from: application or implementation/bindings?

If they come from the app, then:

• in subscribeEvent, the InteractionOptions should carry an optional subscribeOptions property (any), which is opaque to the implementation and used by the protocol bindings on the other end;
• in unsubscribeEvent, there should be InteractionOptions, that can carry an optional unsubscribeOptions (any) which is again opaque to the implementation and used by the protocol bindings on the other end.

If these come from the protocol bindings, then they need not be exposed to the app. What should be the behaviour if the app defines these, should the implementation try to use them (how) and signal error or ignore them?

[egekorkan]

That's a very good question. Here are some TDs that define subscription and cancellation payloads:

• From Oracle and @mlagally :
  This TD requires a very complex payload for subscription. I would doubt that an implementation can figure this out on its own or that such information could be specified statically in a configuration file.
• From Siemens and @sebastiankb :
  The subscription information targetURL cannot be provided on the scripting level since the developer does not necessarily know the URL of the Thing. Then the subscriptionID needs to be managed by the implementation since it needs to be provided back for unsubscription. So I would say that this example is encouraging that these payloads are handled by the implementation.

In the case that this needs to be figured out by the implementation:

• Every other DataSchema information is handled in Scripting level. It would be weird that there is a difference for events.
• How does the implementation find what needs to be handled by the implementation and what values should they get. So for the targetURL example, a semantic annotation (if it exists) can tell that this should be handled by the implementation but then the implementation needs to understand that the URL of the Thing/Consumer the implementation is running on corresponds to this field.

By the way, the one from Oracle has wrong description of uriVariables:

• @mlagally : In the cancellation object, you define another object called uriVariables that are then referenced in the form corresponding to unsubscribeevent. A normal TD parser would not be able to link them. uriVariables should not be in the DataSchema but in the InteractionAffordance level, so outside of cancellation. A correct example for their use in an Action Affordance is here

[zolkis]

In the first case (Oracle) it seems that the subsciption/cancellation information exposes the full protocol details of the underlying implementation piggybacked via this optional data field. We don't have any benefit of using WoT here, since the app needs to know all the details anyway.

This would be one reason why to not allow these options to interactions but keep them on bindings level because that would force a better design on the service.

It is OK to include key management stuff, but that should be a WoT mechanism, not and Oracle mechanism disguised as subscription data.

In the Siemens case, yes, that id could be managed by the underlying implementation.

[zolkis]

I am not sure where to go with this one.
We have discussed this issue before and the subscribe/unsubscribe information should belong to the protocol bindings, not the applications.
Semantically, an app only needs to know the event name for using that interaction, and should be able to handle the data that comes with the notifications.

Apart from that, InteractionOptions should be supported by unsubscribeevent as well.

[egekorkan]

I think that it is due to the fact that we didn't experiment much with subscription and cancellation payloads by looking at what is the common practice.

[relu91]

We might reconsider this. Please comment on the following use case that I described in w3c/wot-thing-description#1053:

I too tend to agree that what should be handled transparently by the runtime should not be exposed by the TD. However, about the subscription payload, I had a use case in mind. TDDs you can have events about added or removed Thing Descriptions. Therefore one client can subscribe to one or the other to obtain useful information about what is currently available in its environment. Translating that to a TD is pretty straightforward:

{
    /*other TD fields */
    "events": {
        "added":{
            "title": "Thing Description added",
            "description": "Fired every time a new TD is added to the TDD"
        },
        "removed":{
            "title": "Thing Description removed",
            "description": "Fired every time a new TD is removed from the TDD",
        }
    }
}

Now consider that I can use JSONPath to filter the notifications and be notified only for things with @type : "sosa:Sensor". How could I describe this use case without the subscription field? I think this is strong evidence that there might be subscriptions that depend on applciation data rather than just protocol configuration and prelude.

Not sure if we can say the same about cancellation.

[zolkis]

I think this is strong evidence that there might be subscriptions that depend on applciation data rather than just protocol configuration and prelude.

That sounds like actions would be more fitting interaction types for this use case. They could accept parameters as context for special subscription + action for special canceling.
Usually on the Web Platform events are not cluttered with app data to be kept around during the subscription.
Also, because app data needs to be managed by the subscription provider, fingerprinting might become an issue.
I would try to avoid this pattern in IoT.

[relu91]

That sounds like actions would be more fitting interaction types for this use case. They could accept parameters as context for special subscription + action for special canceling.

Could you go more in-depth here? How would you model a push notification system based on a parameterized query with actions within the WoT interaction model?

[relu91]

Maybe I can auto-answer 🤣 did you think about an action that returns a TD handle where you have the added and removed events parameterized by your in input in the action? Much like the discussed approach about long-running actions that never landed in something concrete sadly.