Add definitions for partialTD

[relu91]

This PR introduces the new concept of a PartialTD defined in the architecture PR: w3c/wot-architecture#577.
The changes are heavier than I thought therefore I'd like to receive some feedback about the direction that I am taking.

As you can see I changed the argument type of the produce method to PartialTD. This is because a Thing Description is also an instance of a PartialTD; in fact, the validation algorithm would accept any valid TD.

Another open point is how we transform a PartialTD to a valid Thing Description. I tried to sketch an algorithm in this PR; please have look.

Notice finally, how these changes affect the construction of an ExposedThing. Now the constructor has first to transform the PartialTD and then extend the obtained TD with the default values.

Fixes #287

---

Preview | Diff

[zolkis]

The first thing I asked myself, from the point of view of an external user not fully familiar with WoT TD, could we use simpler terms? PartialTD looks bad as a type name.

produce() needs an init dictionary and the algorithm tells how to use it. Its type is object, its semantic is 'partial TD', but in JS we often call init dictionaries with the type+Init suffix. So I think it would be more idiomatic to say

Promise<ExposedThing> produce(ThingDescriptionInit init)

and explain in the text that init is a partial TD in WoT Arch terminology.

[relu91]

At first, the suggestion seemed reasonable, but now I wonder if having yet another term to specify the same concept would increase the confusion. @danielpeintner what do you think?

[zolkis]

Another option could be to continue using the term ThingDescription, but mention in the text that the algorithm also accepts a Partial TD (links to definition). Also the internal algorithm names can be kept.

[danielpeintner]

Mhh, I tend to agree with Zoltan. We should not overly complicated it.
Sticking with ThingDescription and explaining that the input may be a partial TD in the case of expose() seems like a valid approach.

[relu91]

Another option could be to continue using the term ThingDescription, but mention in the text that the algorithm also accepts a Partial TD (links to definition). Also the internal algorithm names can be kept.

I would avoid this option because ThingDescription would be confused with the Thing Description requirements. A PartialTD is not a Thing Description. We clearly say that the ThingDescription type :

Represents a Thing Description (TD) as defined in [WOT-TD]. It is expected to be a parsed JSON object that is validated using JSON Schema validation.

If we stick with that definition (wich works for every other aspect and I don't think we should change it) and leave the produce method signature like it is in the current document, we can't use a PartialTD as argument.

In particular we cannot state the following:

Sticking with ThingDescription and explaining that the input may be a partial TD in the case of expose() seems like a valid approach.

It would be like saying that the input type is a Cat but you could use any Animal as input.

[zolkis]

It would be like saying that the input type is a Cat but you could use any Animal as input.

The argument does make logical sense, but I still think PartialTD is not a desirable name.

A JS developer will see an object. They pass a generic JS object that satisfies the specified validation algorithm (which may consider partial TDs, full TDs, etc).

Promise<ExposedThing> produce(object init);

but usually this is not recommended.
We could also give it a type name that avoids the TD confusions (and explain in prose where it maps):

typedef object ThingInit;
Promise<ExposedThing> produce(ThingInit init);

[egekorkan]

Well, something that worries me a bit is that I feel that we are being flexible but unclear at the same time. There are issues in node-wot that arise simply due to this confusion:

• Forms value and data validation for properties eclipse-thingweb/node-wot#375
• Possible bug in exposing WoT formats attribute eclipse-thingweb/node-wot#364

There can be some other ones that I don't remember but these were the recent ones. So if the discussion is about whether saying partialTD or not, I think that can be changed but saying

Another option could be to continue using the term ThingDescription, but mention in the text that the algorithm also accepts a Partial TD (links to definition)

does not fix the problem. I think it should say that it accepts partial TDs and it is not guaranteed that a full TD is taken in its entirety.

[relu91]

Totally agree with your comment @egekorkan , that's why I started a dedicated section where to describe how the runtime should treat the PartialTD to generate a valid TD (Implementing a PartialTD). The algorithm is still a WIP but I think we should answer also the questions contained in:

• Forms value and data validation for properties eclipse-thingweb/node-wot#375
• Possible bug in exposing WoT formats attribute eclipse-thingweb/node-wot#364

[danielpeintner]

Scripting Call 2021-01-25: replace PartialTD type with ExposedThingInit.

we might improve algorithmns step-by-step (by means of JSON Schema, ?JSON Schema Patch?)
@ashimura mentions the need of more examples, e.g., how to use partial TDs

[danielpeintner]

The general approach looks good to me 👍

A general comment about the new section headers. We should use

• Use and ExposedThingInit / Validate an ExposedThingInit OR
• Using and ExposedThingInit / Validating an ExposedThingInit

I wonder how we can make best progress w.r.t. the remaining TODOs. Shall we try to look into some of those to start with?

[relu91]

I tried to improve the algorithm for the generation of a TD from an ExposedThingInit. The idea is to have a first step where the algorithm removes all the values that couldn't be satisfied by the runtime and then generate the missing required properties.

Some issues that I have:

• Remove and replace user values feels a little bit intrusive to me. I followed this approach only because it is the standard de facto right now
• Some statements are still a little too vague. We can improve them after discussion.
• I added a final validation step to assure that the generated values are correct. I am not sure to keep it, should we trust runtime generated values?

I am open to comments/suggestions.

[zolkis]

Instead of the TODO, please use a <p class="issue"> </p> or <p class="ednote"> </p>

[zolkis]

Overall good, with minor nits (commented separately).

In general, please use line breaks/wrap around 80 chars, in order to ease review.
Though we applied this quite intermittently in the past. Make a choice :)

[danielpeintner]

Scripting Call 2021-02-08

• keep PR open, try to resolve some of TODOs
• use editorial note instead of TODO
• guidance security schemes (ask @mmccool)
• how to make sure user suggestions are fulfilled?
• improve example (last step)

[relu91]

Input from @mmccool about missing security field in partial tds:

• Applications should avoid entirely providing securityDefinitions
• They may choose a particular definition using the schema field (globally or at form level)
• There might be managment APIs to definite the default SecuirtySchema among the possible securityDefinitions

I'll open two more issues to keep track of other comments/insights that came up during the security call.

[danielpeintner]

Scripting Call 2021-02-22

• decided to merge PR
• go with additional smaller PRs (if needed)
• examples style (left right view, stay in sync with TD task force)