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

[Ivaylo Petrov <[e-mail]>]

Hello Klaus,

I apologize for the late reply! Thank you for your review and your
suggestions! The link that you provided was very helpful, but I am still
wondering if I understand correctly the difference between Media-Type and
Content-Type. In my current understanding, if in a media-type
(application/cose) there is an option (application/cose; cose-type), having
a concrete value for that option is a Content-Type (application/cose;
cose-type="cose-encrypt"). In the "CoAP Content-Formats" it seems that such
strings are present and they are still called Media Type, hence my
confusion.

I applied your suggested changes with some deviation on applying the
example URLs suggestion. I tried to incorporate your advice, that of
Carsten and took some extra inspiration from the resource directory draft.
I believe that now it should be clear that the /c and /s are example values
and they should be discovered. Please let me know if the wording is clear
enough for you or if you have other suggestions.

You can find the difference between the last version you reviewed and the
current version here [1]. As usual, the editor's copy can be found here [2].

Best regards,
Ivaylo

[1]:
https://tools.ietf.org/rfcdiff?url1=https://raw.githubusercontent.com/core-wg/comi/99fcad48b28649fe79963c909c6d1483db496f00/draft-ietf-core-comi.txt&url2=https://core-wg.github.io/comi/draft-ietf-core-comi.txt
[2]: https://core-wg.github.io/comi/


On Mon, May 4, 2020 at 8:11 PM Klaus Hartke <[e-mail]> wrote:

> Ivaylo Petrov wrote:
> > I have changed content format to content type in all places where such a
> change seemed necessary. Please do not hesitate to let me know if I have
> missed any place or if I have misunderstood you.
>
> Hmm... I think in section 2.4 you're actually talking about media
> types, not content types.
>
> (I know it's confusing! Have a look at
> https://tools.ietf.org/html/draft-bormann-core-media-content-type-format-01
> )
>
> >> 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 :-)
> >
> > [IP]: I believe I captured what was suggested here, but please check if
> that is indeed the case.
>
> Hmmm... maybe </path/to/the/data/store/X9?k=eth0> wasn't the best
> idea. Some examples now overflow the page width. And it's a bit
> difficult to see where the free-to-choose path segments end and the
> standardized path segments start.
>
> Maybe </...coreconf-path.../X9?k=eth0>?
>
> BTW, in examples I think <example.com/something> should be
> <coap://example.com/something> or <coaps://example.com/something>.
> <example.com/something> looks like a relative URI where the first path
> segment happens to contain a dot.
>
> In see in some tables and examples </c> still being used. Is that
> intentional? I think it would be better to use the same path prefix
> everywhere consistently. (At least the text should point out what
> free-to-choose path segments are used in examples.)
>
> >> 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.
> >
> > [IP]: I believe now this is clear. It is now also clarified that 0 maps
> to false and 1 to true (which might not be what a person using a lot of
> bash would expect).
>
> The text now says:
>
>     o The method int2str() is used to convert an integer value to a
>        decimal string. For example, int2str(\x01\x23) returns the three-
>        character string "291" (the quotes are added for readability, but
>        they are not part of the payload).
>
> Why does int2str now take a byte string as input?
>
> And I think one of "the three-character string "291"" or "(the quotes
> are added for readability, but they are not part of the payload)" is
> enough, you don't need both :-)
>
> Proposal:
>
>     o The method int2str() is used to convert an integer value to a
>        decimal string. For example, int2str(0x0123) return the three-
>        character string "291".
>
> The text now says on Booleans:
>
>     o The boolean representations (0) and (1) are the single character
>        strings U+0030 and U+0031, where false maps to (0) and true maps
>        to (1).
>
> Why not just something like this?
>
>     o The boolean values false and true are represented as the
> single-character
>        strings "0" and "1" respectively.
>
> Then the text now says:
>
>     The resulting key strings are joined using commas between two
>     consecutive key values to produce the value of the 'k' parameter.
>
> That's a good clarification.
>
>     The string value of the 'k' parameter is encoded in a Uri-Query as
>     specified in [RFC7252] section 6.5.
>
> It seems after "Uri-Query", the word "option" is missing. I think I'd
> just omit this sentence, though. It should be clear that query
> parameters are encoded as Uri-Query options in CoAP, no?
>
> Klaus
>