Implications of assertion "accurately describe the data returned" (DataSchema)

[danielpeintner]

In w3c/wot-scripting-api#554 (comment) we discussed the consequences of some TD assertions.

Specifically the following assertion in 9.2 Data Schemas caught our attention.

A WoT Thing Description MUST accurately describe the data returned and accepted by each interaction.

We do have some concerns:

• it is very vague what "accurately describe" means
• I don't think it is possible to do that in all circumstances. We use JSON Schema to describe the "returned data". In use-cases that don't use JSON it is somehow impossible to describe the data accurately (e.g., describing XML content is somewhat limited given that there is no 1:1 mapping between JSON schema and XML schema etc.)

@relu91 @JKRhb @zolkis did I miss anything?

[egekorkan]

This is a bit underspecified indeed. I think that it should contain something like "it should describe as accurately as possible and resort to underdescribing when it is not possible to describe it accurately". I think some examples would be needed. Forcing everyone to describe it as accurately as possible (not that we can but anyways) can resort people in not specifying a data schema at all.

[sebastiankb]

I think the vague statement is coming from the situation when you have non-JSON / XML like structured data as payload and a precise JSON schema representation is not possible. In this case, it would be helpful if you had at least (accurate) high level indicators about the content of the data. E.g. a blob data you simply want to use “type”: “object” without nested properties. In combination with the contentType it can be the only indication of the data content.

[JKRhb]

Could we maybe turn this into a strict assertion for JSON data (that could be directly validated using the JSON Schema information) and define this more as a “policy” for non-JSON data (that could be turned into some kind of assertion via a corresponding “payload binding” document)?