TDD TD: Don't Actions need an input field

[egekorkan]

The TDD TD has the following actions: createTD, updateTD, updatePartialTD. Don't these actions need an input that has an object type, which is the TD ?

[egekorkan]

By the way, similar comment regarding property values. There is no type:object for properties

[farshidtz]

It is optional. Isn't the contentType sufficient?

We can't add it for search outputs because the response is not always an object even though it is always JSON; see #156.

[egekorkan]

So the contentType only tells how it will be serialized but doesn't necessarily say that there will be a body. Regarding anything than is JSON, I would not have a good answer. However, not having an input or output field means that there is no body (or something for the application logic).

[mmccool]

I'd have to check the TD spec to be sure but the input (and output) data schemas of an action should both be optional. 1, either may not be structured data (e.g. an image) in which case there is only a contentType. 2, it is logical to have actions with no inputs and no return type, just like functions (consider "void f()"). In fact an action may have neither and still be valid. You're requesting an action, the request alone may be sufficient.

[egekorkan]

So if you the spec is tolerating if you supply additional data but ideally if you return a payload in an action, the TD should have an output field. The TDD returns a payload for actions but there is not output field. Similar for inputs for registering TD

[mmccool]

My comments were about TDs in general (e.g. void f() is a valid function signature) but for TDDs we should of course correctly identify the input and outputs of all interactions. I think the problem here is that embedding the JSON Schema for TDs in the TDD would be a huge mess. So I think as a practical matter we should just depend on the contentType, but maybe adding an explanatory note would be useful (e.g. "An input data schema for these actions has been omitted, since the input data format is identified by the content type. A JSON Schema for the input can be found in the TD specification.")

[mmccool]

Some thoughts:

1. Having a content type for an input but no schema is already acceptable for binary data, e.g. images. So I see no problem doing this for TDs as inputs.
2. Actions (e.g. queries) that produce JSON but JSON that can vary a lot in its schema is trickier. I think however the only practical option is using a contentType for the return type and no schema. In this specific case the consumer needs to know how to consume the result (and since the consumer sent the query, it should now how the result will be structured; the schema is known to the consumer, in short). The only real issue is what the TD spec says (e.g. if it says a schema is mandatory if the contentType is JSON we will be non-conformant).

Suggested resolution: no normative change to THIS spec, but perhaps some explanation of the design choices following the above, explaining why there is no schema.

[farshidtz]

I believe OP's point is about setting an object type for inputs/outputs and not related to whether the whole schema is necessary.

[egekorkan]

I believe OP's point is about setting an object type for inputs/outputs and not related to whether the whole schema is necessary.

Yes that was my point. If the TD doesn't specify a data schema, a consumer shouldn't think of looking at the forms to construct a certain payload structure. Saying type object is enough to imply that the payload isn't empty.

[farshidtz]

I've created a PR to add those.

I think the object type is also necessary when converting the TD to OpenAPI spec. See #82 (comment)