[core] Review of draft-ietf-core-comi-09

[Klaus Hartke <[e-mail]>]

Section 2.4: The document seems to use the terms "content format" as a
synonym for "content type". A content format is the combination of a
content type (which is the combination of a media type with specific
values for the media type's parameters) with a content coding. An
example for a media type is "text/plain", for a content type
"text/plain;charset=utf-8", and for a content format
"text/plain;charset=utf-8" combined with "gzip". I think you mean
content type, right?

Section 2.4: In the table, all the media types incorrectly have a leading "/".

Section 4: It's not okay to mandate or recommend specific paths like
</c> and </s>. Not even with a lower-cased "recommended". It's fine to
define a path structure after the "root path" of the application and
use an example path in examples, but implementers should not be
restricted or discouraged in any way to choose a different path (see
BCP 190). The best choice is probably to use a long, not very nice
looking path like </path/to/the/data/store/X9?k="eth0">, so that
implementers immediately get the idea to pick a shorter path
themselves :-)

Section 4: The document specifies the API in terms of the CoAP
Uri-Query option a lot. The Uri-Query option is just the way how the
query string of the request URI is encoded in CoAP, though. It would
be better to specify the API in term of query strings and not to
mention the Uri-Query option.

Section 4.1: It's unclear if a client should send the query string
<?k=0> or <?k="0"> (with quotes, as shown in the table) for a Boolean
value.

Section 4.1: It's unclear if the int2str function returns "291" (5
characters) or "291" (3 characters, typographically set in quotes).

Section 4.2.2: It's unclear if a client should send the query string
<?d=t> or <?d= 't'> (with a space and single quotes, as shown in the
indented paragraph).

Section 4.2.3.1: It's unclear why a client needs to send the query
string <?k="eth0"> instead of <?k=eth0>. The table in section 4.1
seems to say that a string `key` is written as `key`, not as `"key"`.
Can a `key` contain `"` characters itself and, if yes, how are those
escaped?

Section 4.5: If I understand this correctly, this enables getting
events by appending these to an internal "log file" and exposing the
latest few entries of the log file as the resource </s>. This resource
can be observed, so that if new entries are appended, the resource
changes its state and the client gets notifications. Correct? It might
be worth pointing out that this scheme does guarantee delivery of all
entries in the log file to the client. It might also be a good idea to
remind implementers of what happens when the size of the last few
entries is greater than the MTU.

Section 4.5: The last paragraph says "To check that the client is
still alive, the server MUST send Confirmable Message periodically."
That's what RFC 7641 already specifies. Please don't make normative
statements that repeat (or contradict) what RFC 7641 says. :-)

Klaus