Diagnostic notation for CoAP requests

[chrysn]

Several documents building on CoAP currently have examples like

REQ: GET
Uri-Path: foo
Observe: 0

RES: 2.01 Content
...

or

REQ: GET coap://host.example.com/path
Content-Format: foo
Payload:
...

(not trying to be particularly accurate in the above examples, suffice to say the notation varies)

It Would Be Nice If we could have an agreed-on notation, possibly through corrclar. HTTP/2 has something like this, which is used in practice in documents. This was suggested by different people before; I didn't take the time to look up the meetings or mailing list posts as I'm pretty sure none of them said anything more concrete than "it would be nice if".

I don't have a concrete proposal for here -- more starting a wishlist for whoever (may or may not be me) might pick that up later into corrclar if we want it there. Nice properties would include:

• Ability to express structured fields; a Block2 option should say 0/M/512byte or similar.
• Ability to use shortcuts, and express details only when deemed necessary: a Req: GET coap://[2001:db8::1]/.well-known/core?foo=bar may be easier to use, especially in long examples, than the full

  Req: GET, to 2001:db8::1 port 5683, mid=0x1234, token=0x
  Uri-Path: .well-known
  Uri-Path: core
  Uri-Query: foo=bar
  

• Ability to express (even nested?) OSCORE

The notation should not be designed for parsing, really just for illustration. (We may need one parser to verify document content, unless we have a single trusted pretty-printer and verify by having binary versions of all examples). In addition to serving as usable format for IDs, it might also double as debug output for CoAP sniffers or implementations.