feat(coap): add conformance section

[JKRhb]

Inspired by the MQTT Binding Document, this PR adds a conformance section to the CoAP document which would make it possible to use keywords like MUST or SHOULD to formulate (quasi-)normative statements.

I partly opened this PR to discuss if including such a section is actually possible for a binding document or if all statements must be strictly informative – if a conformance section cannot be included, then the existing documents (namely the MQTT binding) would require adjustments as well.

[egekorkan]

I think that this is a good start and almost complete from my point of view

[ektrah]

I'm not sure if this adds a lot of value to the document. The two sections are normative in the sense that they're providing the vocabulary and defaults you'll have to use if you want to be interoperable. Conformance to these sections would mean that your implementation does this correctly and is therefore interoperable. That kind of trivial, isn't it?

[JKRhb]

I think the main benefit would be the possibility to use RFC 2119 keywords (ReSpec automatically adds some boilerplate based on what is used within the document, see here). If we don't need that (or aren't allowed to use the keywords in a binding document) then we can just close this PR.

However, for the sake of consistency, I think it should be discussed in general if binding documents need/should include a conformance section since the MQTT document has one while the Modbus document does not.

[ektrah]

RFC 2119 keywords do not indicate requirements for conformance, they indicate what implementations may and must do to achieve interoperability with each other. (If you read RFCs, you'll find that there aren't any sections on conformance terms. It's always about interoperability.)

The document currently already specifies what implementations must do to be interoperable, whether with or without RFC 2119 keywords. IMHO adding a conformance section wouldn't change much about that.

[egekorkan]

So far as I know, all our documents should have a conformance section. Respec automatically generates the content of the conformance section once you put the section id. See https://github.com/w3c/wot-binding-templates/blob/main/index.html#L216 which has an empty section but the generated document has https://w3c.github.io/wot-binding-templates/#conformance

@JKRhb I have realized that the preview actually does not contain the explanation about the assertive keywords: https://deploy-preview-275--wot-binding-templates.netlify.app/bindings/protocols/coap/index.html

Is there a way to add what you put but keep the auto-generated content?

[JKRhb]

@JKRhb I have realized that the preview actually does not contain the explanation about the assertive keywords: https://deploy-preview-275--wot-binding-templates.netlify.app/bindings/protocols/coap/index.html

Is there a way to add what you put but keep the auto-generated content?

I think the explanation regarding the RFC 2119 keywords is only generated if one of the keywords is actually being used within the document (and then limited to what is actually being used). E.g., if you put a MUST in the document somewhere, then the explanation text should appear automatically, like so:

Currently, none of the keywords are present in the document, therefore the explanation is omitted.

[ektrah]

I'm fine with adding the W3C boilerplate and using RFC 2119 keywords in the document. I think more thought is needed as to what conformance actually means in the context of protocol bindings.

[egekorkan]

I think more thought is needed as to what conformance actually means in the context of protocol bindings.

I agree but this sort of extends to TDs in general. The normative consuming and parsing in the next charter should handle this

[egekorkan]

Call of 05.04:

• Merging and creating issue for @ektrah last comment.