Clarify the behavior when a response does not have body

[lu-zero]

We mention in https://w3c.github.io/wot-profile/#http-basic-profile-protocol-binding-invokeaction and other places:

Content-Type header set to application/json
A body with an input to the action, if any, serialized in JSON

Since some http implementation unhelpfully may pass the empty string to a json deserialiser, might be useful to suggest to either explicitly pass "{}" or not set the Content-Type if there isn't a body.

[egekorkan]

+1

Also it would be good to specify the behaviour around the null type where this topic is discussed.

[benfrancis]

@lu-zero wrote:

Since some http implementation unhelpfully may pass the empty string to a json deserialiser

Note that an empty JSON string (as in two double quotation marks as opposed to just an empty body) could actually be a valid action input (e.g. to reset the message on an LED matrix display by passing the value "" to a setMessage action).

might be useful to suggest to either explicitly pass "{}"

That would be an invalid input if the type of the input is not "object".

or not set the Content-Type if there isn't a body.

That's a better idea. Although if a Thing is expecting an input then it should probably be checking that a valid body was supplied, and if it isn't expecting an input it can just ignore the body.

@egekorkan wrote:

Also it would be good to specify the behaviour around the null type where this topic is discussed.

What behaviour do you think needs to be defined?

One limitation of the current profiles is that they currently assume all payloads of properties, actions and events are JSON. We have use cases in WebThings where the type of a property is set to null, e.g. an ImageProperty where the value is a binary image and a contentType is set on a Form instead.

[egekorkan]

What behaviour do you think needs to be defined?

I just wanted to say explained in detail since emptiness can mean different things to people: empty body, a JSON null, an empty object, empty string and probably some other things. So when this paragraph to explain this is added, I would just recommend to be more verbose. For me only the empty body is true "emptiness" but as stated above, the spec actually asks the implementations to still set the header to json in case of empty payload. I think it is fine as it is specified, just some explanations are helpful for implementers.

[lu-zero]

@lu-zero wrote:

Since some http implementation unhelpfully may pass the empty string to a json deserialiser

Note that an empty JSON string (as in two double quotation marks as opposed to just an empty body) could actually be a valid action input (e.g. to reset the message on an LED matrix display by passing the value "" to a setMessage action).

That's a good example of the papercut: JSON.parse("") is an error JSON.parse('""') is the zero-sized string.
Also the "" vs {} is interesting as corner case but for that the DataSchema should help.

We could consider the http+deserializer that misbehave non-standard and be done with that, but maybe just suggest to avoid the problem and suggest to avoid setting information that is unnecessary because there is no body.

[relu91]

I just wanted to say explained in detail since emptiness can mean different things to people: empty body, a JSON null, an empty object, empty string and probably some other things. So when this paragraph to explain this is added, I would just recommend to be more verbose. For me only the empty body is true "emptiness" but as stated above, the spec actually asks the implementations to still set the header to json in case of empty payload. I think it is fine as it is specified, just some explanations are helpful for implementers.

I recall discussing these topics, but I am not sure where. Probably, when I refactored the protocol interface in node-wot or when we discussed the new template for payload bindings in Protocol Bindings Templates. I think these general guidelines should first be defined in the corresponding protocol binding template and then narrowed at will in the profiles. I know it is kind of a convoluted approach but we should keep these efforts in sync.

[lu-zero]

Shall we make sure the protocol-level no-body and content-type-level empty are clearly separated and defined?

[relu91]

Linking some old issues: w3c/wot-binding-templates#184