Produce() method should ignore instance specific information

[egekorkan]

At the current state, produce() method claims to accept a Thing Description that always contains instance specific information such as href's IP address and contenttype. It should be made clear that this is not possible since a server cannot replicate the IP address of another server or that this server may not be able to provide the same contenttype.

[zolkis]

produce() method claims to accept a Thing Description always contains instance specific information such as href's IP address and contenttype.

Where is that claimed? The produce() algorithm doesn't. However, it is indeed missing some steps/information.

When creating a new Thing by consuming a TD and using the object to supply to produce(), it doesn't really harm if IP address and content type are provided as a Thing model, since the algorithm of the produce() method should state what are the minimum set of properties in a TD init object that should be there, and what happens if an IP address and content type are provided - the implementation may take it as a hint, but that information there will be overridden in the newly created ExposedThing object.

[egekorkan]

Where is that claimed?

The function description has the following:

Accepts a model argument of type ThingModel

After looking at the definition of ThingModel:

The ThingModel type represents either a ThingFragment, or a ThingDescription.

And after looking at the ThingDescription definition:

Serialized representation of the Thing Description (a JSON-LD document).

So this means that Scripting API uses the same definition of the Thing Description as the Thing Description spec which in turn means that produce() method must be able to accept a normal TD and generate an Exposed Thing according to that.

the implementation may take it as a hint

I also don't see what this means :)

In my head, there has to be a clause/sentence saying that the forms of a TD are instance specific and that the produce() method can recreate an ExposedThing object with the same instance only if the instance is the same. This being a very rare case, we should make it possible to add instance specific information such as contenttype, method, (href). Since we may have multiple forms, there should be something like addForm() that can be called on an InteractionFragment which would push a Form into the array of forms.

[zolkis]

This is a JavaScript API and a function can accept any initialization object or any of its property subset. The algorithm tells how to use the init object. Instance in this context means the JavaScript object. Multiple forms are passed as array property in the init object.

[egekorkan]

Doesn't this imply that the meaning of the TD object as an argument can have two different meanings for two different implementations?

[zolkis]

No, it's not a TD object yet, it is a JavaScript object that is used for initializating an ExposedThing object which represents a TD "object" in the same way a ConsumedThing represents a TD "object". One script might be different from another script of course, and may use different initialization objects. But they can use also the same ones, as the developer decides.

[egekorkan]

No, it's not a TD object yet

But the scripting API spec says that the argument is a serialized form of the TD defined in the TD spec.
I totally agree that ExposedThing represent an object like the ConsumedThing but I do not understand how the argument of expose(), which is allowed to be a TD specified by the TD spec can be "allowed" to be interpreted differently. Does this mean that I can provide a TD with a property called myProperty and the ExposedThing can have a property called megaProperty instead of myProperty? Where do we draw the line?

[zolkis]

how the argument of expose()

ExposedThing.expose() does not accept arguments.

As the spec says, WoT.produce() accepts a string (serialized TD which is used for initializing the new ExposedThing object) or a dictionary object that is used for initializing the new ExposedThing object, i.e. its properties become the ExposedThing object properties and the other required properties in the TD spec are initialized with default values. Sorry I don't understand the source of your concern.

[egekorkan]

Sorry, I meant produce() instead of expose() in my previous comment.

is used for initializing the new ExposedThing object, i.e. its properties become the ExposedThing object properties

This is exactly what I mean and I think we are on the same point. If we say that ExposedThing is initialized with the properties of the argument TD string, then the forms field of the argument TD string should be present in the ExposedThing. This is what I mean by instance-specific information of a TD. Without instance specific information, we would simply get a TD template (Thing fragment) and the current Scripting API spec does not tell that we can actually accept "only" a TD template.

I have put only in quotes since if the exposer of that TD (that came in the argument) can fulfill instance specific requirements, its ExposedThing will have exactly the same values for every key. I think there has to be at least a note about this constraint.

[zolkis]

If we say that ExposedThing is initialized with the properties of the argument TD string, then the forms field of the argument TD string should be present in the ExposedThing.

Not necessarily. The ExposedThing creation algorithm does not have to take all input as it is, instead it may take it as a hint when determining the init value of the property in the ExposedThing object, so implementations may override the provided init values under conditions specified in the produce() algorithm.

Indeed we need to extend/clarify the produce() algorithm how does it initialize the new ExposedThing based on the input (string or object).

[zolkis]

Should be fixed by #174.

[egekorkan]

I am not sure if this is fixed now since there is still no mention of the following details:

so implementations may override the provided init values under conditions specified in the produce() algorithm.

Indeed we need to extend/clarify the produce() algorithm how does it initialize the new ExposedThing based on the input (string or object).

[zolkis]

I think there may be a misunderstanding about the intended work flow when creating an ExposedThing.

From the network API point of view, we see that a new Thing is created on a device that serves requests and exposes a TD.

How does that happen? A script gets [deployed and] executed on that device.
That script defines the Thing behaviour and uses the infrastructure provided by the scripting runtime (currently node-wot). A script can use a dictionary (like a pre-filled TD template) to initialize an ExposedThing object and also needs to define the callback methods that are invoked when requests come to the ExposedThing.
The expose() method is implemented in node-wot and is responsible to "create the TD" that is shared on and align it with the implementation details (protocol bindings etc).

That includes instantiating a request handler for each Form declared in the TD template object and making sure external requests be dispatched to the right request handler and Form.

So the questions in this issue are basically encapsulated by expose() implementation, but the developer needs to know the following:

• what protocol bindings can be used on that device
• what Forms to define in the TD template
• what request handlers to define and how (also using the device's local HW API, i.e. local SW environment).