Make contentType optional in ExpectedResponse and AdditionalExpectedResponse classes

[JKRhb]

Description of Changes

This PR deals with an issue that was discovered in the context of w3c/wot-discovery#465 and #1776: At the moment, there is always a contentType assumed for an ExpectedResponse or AdditionalExpectedResponse, although there are cases where a server does not return any kind of payload (e.g., in the case of an HTTP No Content response). This PR provides a potential fix for the issue, although there might be some more discussion needed here.

Related Issue

Closes #1780

Type of Change

Check the correct box and add the corresponding label if you are an editor.

• Editorial (non-normative) with label .

• Normative with label

---

Preview | Diff

[JKRhb]

I noticed in the meantime that there are also assertions related to the ExpectedResponse and AdditionalExpectedResponse classes (e.g., in section 5.3.4.2.2) that need to be adjusted. I will update this PR accordingly.

[egekorkan]

I am fine with this direction given the use case. However, we are not clear about the meaning of the lack of contentType (a bit like #2028 but not exactly). Here, we want to really say that there is no content type in the response header. However, the lack of contentType in the form level means that the defaults should be assumed. Maybe both meanings can be changed at the same time, i.e.:

• contentType is optional in all levels without any default mechanism
• Lack of it means contentType SHOULD NOT be used in the request or response

[JKRhb]

I've now made a first attempt at adjusting the assertions for the two classes. I have the impression that this requires a bit more care than initially expected 😅 But I hope that the changes I made so far point in the right direction. One area that also needs to be revisited carefully is the table on the content type usage, which I haven't taken a closer look at so far.

[benfrancis]

@egekorkan wrote:

contentType is optional in all levels without any default mechanism

That sounds like a big change. Would that mean that all forms which previously defaulted to application/json would now need an explicit contentType?

[JKRhb]

That sounds like a big change. Would that mean that all forms which previously defaulted to application/json would now need an explicit contentType?

Hmm, I think by default, we could stick to application/json as the default content type for input and output data, the latter of which could be overridden via the response classes. One thing, though, I am wondering about just now is whether we also need a way to express that a request should be empty/not have a content type. Maybe, though, we could also use null to specify that?

[egekorkan]

@egekorkan wrote:

contentType is optional in all levels without any default mechanism

That sounds like a big change. Would that mean that all forms which previously defaulted to application/json would now need an explicit contentType?

Not a big change in my opinion. We will have a container to define defaults for all forms anyways. Also see w3c/wot-binding-templates#357 (comment) and the comments below it

[egekorkan]

TD call 20 Feb:

• Some more changes are needed to the assertions around this feature
• The contentType in the form level (requests) can be optional as well, which will be useful for cases where the request requires no payload (e.g. an action invoke without input such as toggling a light)
• This will be a breaking change as TD2.0 TDs not having the contentType will mean JSON for TD 1.1 Consumers
• This can be a non-issue for some protocols that have automatic mechanisms
• It should be possible to require it at the binding level. Some protocols do not have a mechanism to provide this information in-band. So it has to be out-of-band via TD.
• The discussion (BACnet media type wot-binding-templates#357) should be taken into account, where only the bindings define the keyword related to contentType
• We should check the impact to Scripting API algorithms.

[egekorkan]

TD call 05 March:

• We are fine to make contentType optional with no default in all levels.
• The relationship between the lack of data schema (e.g. no input or no output in an action or no data in an event) and the contentType should be explained in the text, probably with assertions. The same for the presence of data schema, i.e. when there is data schema, there must be contentType (no default value)

[benfrancis]

We are fine to make contentType optional with no default in all levels.

I don't love the global default being removed. Can this at least wait until there is somewhere to specify a default for a specific Thing Description? Otherwise I'm going to have to start adding "contentType": "application/json" in every single Form.

[egekorkan]

@benfrancis there will be the way to add a global default for a data schema as a result of https://github.com/w3c/wot-thing-description/tree/main/proposals/initial-connection. Also, we plan on adding a logic saying "if there is an input schema, the contentType is application/json in the form"

[JKRhb]

Okay, I think this PR should now be closer to a mergable state :) Besides adjusting the assertions that were already subject to this PR to reflect our latest consensus, I also removed two assertions that seemed unneeded/obsolete to me, and also added a new example that illustrates how the empty response object can be used to indicate that the response is neither supposed to contain a payload nor a contentType.

With these changes, the discussion we had earlier on making contentType optional at the form level does not have to be resolved right now and can be revisited after merging this PR.

I hope that the PR will now be ready to be merged, but I would ask you to conduct another careful review to make sure that there was no oversight from my sight. I also noticed one aspect regarding AdditionalExpectedResponses myself that could be addressed as a follow-up.

[egekorkan]

TD call today:

• Example 37 should have an input to show that the contentType belongs to the input
• @egekorkan will check the HTML diff to see if the ids of the assertions are ok.
• The paragraph starting with Similar considerations apply to additional responses. should reflect - with assertions - about the lack of contentType in response.
  • Here, also splitting it into a list would help as some "structured thinking" is needed with conditions.

[TallTed]

Small stuff.

[JKRhb]

TD call today:

• Example 37 should have an input to show that the contentType belongs to the input

• @egekorkan will check the HTML diff to see if the ids of the assertions are ok.

• The paragraph starting with Similar considerations apply to additional responses. should reflect - with assertions - about the lack of contentType in response.

  • Here, also splitting it into a list would help as some "structured thinking" is needed with conditions.

I think these aspects should now be addressed :) Looking forward to your feedback here.

[egekorkan]

I think it is looking very good now. I have also updated the assertions.csv file as assertions are changing. I will also start automating that now.

[relu91]

I'm still not completely satisfied about how we deal the absece of payloads (inputs or outputs), I hope that in the next revision we can find something cleaner. Perhaps this will help:

@benfrancis there will be the way to add a global default for a data schema as a result of https://github.com/w3c/wot-thing-description/tree/main/proposals/initial-connection. Also, we plan on adding a logic saying "if there is an input schema, the contentType is application/json in the form"