feat: introduce cov:confirmable vocabulary term

[JKRhb]

This PR contains my first attempt at resolving one of the aspects mentioned in #389 by introducing a cov:confirmable vocabulary term.

[netlify]

✅ Deploy Preview for wot-binding-templates ready!

Name	Link
🔨 Latest commit	7c34960
🔍 Latest deploy log	https://app.netlify.com/sites/wot-binding-templates/deploys/676421cc4329ea00082b4aca
😎 Deploy Preview	https://deploy-preview-392--wot-binding-templates.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[ektrah]

I think it would be helpful to explain when to include a "cov:confirmable": true or "cov:confirmable": false in a TD (e.g., by giving some examples and/or a rule of thumb). Otherwise, this looks good to me.

[JKRhb]

I think it would be helpful to explain when to include a "cov:confirmable": true or "cov:confirmable": false in a TD (e.g., by giving some examples and/or a rule of thumb). Otherwise, this looks good to me.

Thank you for your feedback, @ektrah! I tried to give some examples in 3df9138, let me know if you see room for improvement here :)

[ektrah]

In a TD we want to tell the TD consumer how to interact with the Thing, so this is about CoAP requests that the consumer sends to the Thing, right?

I would assume that if a TD consumer knows what it is doing (e.g. transmitting sensor data, retrieving a value, or invoking an action) it also knows whether it is best to do it with a CON or NON. Maybe the consumer just needs to give the CoAP driver a hint as to what it is doing?

Or what are the cases where a TD consumer is doing something and also knows what it is doing, but does not know whether to use CON or NON, and so the TD should tell it (or overrule what it would normally do)?

[JKRhb]

Hmm, yeah, these are good points. Maybe a better example could be sleepy devices that were also discussed in the context of #389? Although I am still not completely sure how to model that. Perhaps another use case could be resource constraints in general, where using NON could be slightly more efficient (although not that much when piggybacked acknowledgments are being used).

Do you see a better motivation here? (Also pinging @mkovatsc as we discussed this potential addition to the vocabulary during WoT week.)

[ektrah]

Sleepy devices are interesting because a TD consumer may spend a lot of time trying to reach a device that is unreachable, draining the resources of the network infrastructure, which may also be resource constrained. It would therefore be very desirable if a TD could give a consumer hints on how best to reach the sleepy device. Is the choice between CON and NON enough? Is the sleepy device awake at regular intervals so that the TD consumer only has to synchronize its schedule once and can then communicate at the fixed interval that is specified in the TD? This would then no longer be CoAP-specific but would go in the direction of the generic terms mentioned by @danielpeintner.

[TallTed]

A "hint" seems rather less powerful than the SHOULD (which looks like RFC2119, to me).

Suggested change

	To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
	A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
	However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
	When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.
	The vocabulary term `cov:confirmable` can be used to provide a hint whether CON or NON requests are expected to be better for accessing a CoAP resource associated with a form.
	A value of `true` encourages the Consumer to use CON requests, while a value of `false` encourages the Consumer to use NON requests. (For potential uses of the vocabulary term, see [[[#example-request-con-non]]].)
	Note that, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
	When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.

[TallTed]

Suggestions made against this content in index.html also apply to this content in index.template.html. But I don't understand why these files contain so much duplication.

[danielpeintner]

FYI: the duplication comes from the fact that based on index.template.html and additional resources like ontologies etc. the final index.html is generated. Hence, it is sufficient to fix index.template.html and tooling will do the rest.

[TallTed]

Hence, it is sufficient to fix index.template.html and tooling will do the rest.

That would be true only if index.html contains nothing in addition to what is in index.template.html. Rather, "it is sufficient to fix index.template.html where it is duplicated in index.html, and fix index.html where it is not duplicated from index.template.html, and then tooling will do the rest".

Lacking anything highlighting the differences between index.template.html and index.html, reviewing these is thereby made a much larger effort.

[danielpeintner]

There is a render script in place that uses index.template.html and adds additional parts to it (based on other resources like ontologies). The result will be stored in index.html. Hence, changing index.html only does not have any effect, since a subsequent render task will override it again. See https://github.com/w3c/wot-binding-templates?tab=readme-ov-file#tooling

[TallTed]

So index.template.heml is not a template, and index.html is an output artifact, which means it shouldn't be under git management, unless it is stored to a different folder of the repo, which clearly indicates that its contents are such artifacts.

[TallTed]

Suggested change

	In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
	Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
	</p>
	<p>
	To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
	A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
	However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
	In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
	Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
	</p>
	<p>
	The vocabulary term `cov:confirmable` can be used to provide a hint whether CON or NON requests are expected to be better for accessing a CoAP resource associated with a form.
	A value of `true` encourages the Consumer to use CON requests, while a value of `false` encourages the Consumer to use NON requests. (For potential uses of the vocabulary term, see [[[#example-request-con-non]]].)
	Note that, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.

[egekorkan]

So index.template.heml is not a template, and index.html is an output artifact, which means it shouldn't be under git management, unless it is stored to a different folder of the repo, which clearly indicates that its contents are such artifacts.

We are slowly getting there as that was also what @lu-zero suggested :) Btw, this is the same in wot-thing-description repository. Sorry for the confusion and thank you for reviewing!