Allow array for response in From class?

[mkovatsc]

Originally, I expected that all possible responses can be described through the response(s) vocabulary term.

A use case is where the input of an Action might select the representation format (e.g., RAW vs JPEG vs PNG), and hence multiple responses are possible.

Furthermore, it might be an extension point to also describe expected error responses out-of-band in the future (i.e., to retrofit hypermedia behavior to devices that would only respond with an error code).

[sebastiankb]

Theoretically, it is possible to set up different form instances with different combinations of input contentType and response contentType.
I know, this may lead to complex TDs.
I do not have a hard opinion on that.

[mkovatsc]

I would change the Form class definition, so that the Type for response says "ExpectedResponse" or array of "ExpectedResponse".

Otherwise, it only supports a subset of the targeted use cases.

[mkovatsc]

A test is easily done through the takeSnapshot Action, where input can also specify the output format / media type.

[mkovatsc]

Giving multiple possible responses would on the other hand rely on content metadata. Good protocols have that, MQTT does not...

Let's defer.

[farshidtz]

Array of responses in Form may also be used to describe various response codes.

Describing a PUT method (based on https://tools.ietf.org/html/rfc7231#section-4.3.4):

{
    "href": "/resources/{id}",
    "htv:methodName": "PUT",
    "contentType": "application/json",
    "response": [
        {
            "description": "Created new resource",
            "htv:statusCodeValue": 201
        },
        {
            "description": "Updated existing resource",
            "htv:statusCodeValue": 204
        }
    ]
}

Response errors (relevant to #303):

{
    "href": "/resources/{id}",
    "htv:methodName": "GET",
    "response": [
        {
            "description": "Success response",
            "contentType": "application/json",
            "htv:statusCodeValue": 200
        },
        {
            "description": "Resource not found",
            "htv:statusCodeValue": 404
        }
    ]
}

Headers on success response (based on https://tools.ietf.org/html/rfc7231#section-4.3.3):

{
    "href": "/resources",
    "htv:methodName": "POST",
    "contentType": "application/json",
    "response": [
        {
            "description": "Success response",
            "htv:headers": [
                {
                    "description": "Resource identifier",
                    "htv:fieldName": "Location"
                }
            ],
            "htv:statusCodeValue": 201
        },
        {
            "description": "Invalid input",
            "htv:statusCodeValue": 400
        }
    ]
}

NOTE: the above examples may not be valid TD forms.

[egekorkan]

From @farshidtz comments above, this issue in the scripting api is also relevant: w3c/wot-scripting-api#200

[mmccool]

Adding an array in responses would break backward compatibility, and also if multiple responses are possible the TD NEEDS a way to distinguish the various response (eg a header field). So I'm thinking something like using the current "response" field as the "default" response, and a NEW field, which has an array of responses, each of which include a header to distinguish then. This could be called something like "alternateResponses" although we could argue about better names (eg just "alternates") if you would like...

[takuki]

Adding an array in responses would break backward compatibility, and also if multiple responses are possible the TD NEEDS a way to distinguish the various response (eg a header field). So I'm thinking something like using the current "response" field as the "default" response, and a NEW field, which has an array of responses, each of which include a header to distinguish then. This could be called something like "alternateResponses" although we could argue about better names (eg just "alternates") if you would like...

If the Thing with an alternateResponses field does not know the consumer can handle v1.1, the consumer would be surprised to receive a response that is different from what it expects.

I think although it does not break interoperability when parsing a TD, but it may break interoperability at run-time this way.

[sebastiankb]

From today's TD call:

• as @takuki mentioned supporting response as an array we will have backwards compatible issue
• we should clarify with the Discovery TF (@farshidtz @mmccool) how essential this feature is and may decide to do an exception

[egekorkan]

I wasn't there in the call but what's the relation to the Discovery TF?

[sebastiankb]

I wasn't there in the call but what's the relation to the Discovery TF?

w3c/wot-discovery#54

[sebastiankb]

From today's TD call:

• we introduce a new term additionalResponses as array in forms
• this keeps backwards compatibility to 1.1
• we have to evaluate the definition about different data schema that can be assigned to different responses
• first idea is to use anyOf at data schema level to provide different schema definitions
• we should also compare the discussion with SDFchoice
• within the response entries there can be a JSON pointer to a schema definition
• there needs a default assumption for the pointer
• @mmccool will discuss some use cases during the discovery TF
• @mmccool will also provide a PR to integrate this new feature if there is consensus

[mjkoster]

Entry point for the discussion on "anyOf" in SDF: ietf-wg-asdf/SDF#8

We should write up a FAQ entry for this

[sebastiankb]

issue is addressed by the latest draft