Re: [core] [art] Artart last call review of draft-ietf-core-senml-data-ct-04

[Francesca Palombini <[e-mail]>]

Bron: thanks for this ARTART review! Carsten, authors, thanks for addressing Bron's review. I am waiting on the updated revision before sending the document to IESG.

Francesca

On 25/08/2021, 19:52, "art on behalf of Carsten Bormann" <[e-mail] on behalf of [e-mail]> wrote:

    Hi Bron,

    Thank you for this quite actionable review!

    > It is mostly easy to understand, however there is a missing reference to one
    > registry, and some phrases that may be confusing.
    > 
    > The missing registry is here:
    > http://www.iana.org/assignments/http-parameters/http-parameters.xhtml#content-coding
    > (I found it by following normative references, however other similarly
    > registered data fields in this document link to their registries, and could
    > likewise be found by following references)

    I completely agree that we need to become better in identifying the registries that we are using.  Fix below.

    > The document specifies `Content-Coding` as:
    > 
    >   Content-Coding:  a registered name for an encoding transformation
    >      that has been or can be applied to a representation.  Confusingly,
    >      in HTTP the Content-Coding is then given in a header field called
    >      "Content-Encoding"; we *never* use this term (except when we are
    >      in error).
    > 
    > I found this quite confusing, and it also comes across as very snarky and
    > suggesting infighting.  

    (It’s more about being humbled by having made the same mistake before, say in Section 12.3 of RFC 7252…)

    > I suggest removing the "except when we are in error"
    > entirely.
    > 
    > I also found "has been or can be" is also confusing.  In the context of this
    > document, I understood Content-Coding in a `ct` field to mean that said coding
    > HAS BEEN applied to the value in `vd`, however this wording makes me question
    > that assumption.

    That text was stolen from RFC 7231:

       Content coding values indicate an encoding transformation that has
       been or can be applied to a representation.  Content codings are

    But “can be" here probably is more about Accept-Encoding, for which we don’t have an equivalent in SenML, so we can leave this aspect out.

    > Maybe something like this is sufficient?
    > 
    > Content-Coding: a name registered in [IANA.content-coding] as specified by
    > [RFC7230].  Confusingly, in HTTP the Content-Coding is found in a field called
    > "Content-Encoding", however "Content-Coding" is the correct term.

    Combining some better use of references (see your point above) with this input, I came up with:

       Content-Coding:  A name registered in the HTTP Content Coding
          registry [IANA.http-parameters] as specified by Section 8.5 of
          [RFC7230], indicating an encoding transformation with semantics
          further specified in Section 3.1.2.1 of [RFC7231].  Confusingly,
          in HTTP the Content-Coding is found in a header field called
          "Content-Encoding", however "Content-Coding" is the correct term.

    (Links in the HTML version on every section or registry reference, which are not visible in this plaintext copy-paste.)

    Now in https://protect2.fireeye.com/v1/url?k=b63ae234-e9a1db32-b63aa2af-86ee86bd5107-3248b112897beaf1&q=1&e=38e64623-52dd-4890-be02-23258b6d566d&u=https%3A%2F%2Fgithub.com%2Fcore-wg%2Fsenml-data-ct%2Fcommit%2F90a3deb

    > The other confusing section was this in section 3:
    > 
    >  If no "@" sign is present outside the media type parameters, the
    >  Content-Coding is not specified and the "identity" Content-Coding is used -- 
    >  no encoding transformation is employed.
    > 
    > "If no @ sign is present outside" is a really clunky turn of phrase that left
    > me more confused than the examples!  I assume this construction was used
    > because theoretically an '@' sign could be present inside the media-type, or
    > inside a parameter, if correctly quoted.  I would suggest at least changing
    > "present outside" to after, or trailing, or something.
    > 
    > Maybe this?
    > 
    > If no "@" sign is present after the media-type parameters, then no
    > Content-Coding has been specified, and the "identity" Content-Coding is used --
    > no encoding transformation is employed.

    I restructured the paragraph along these lines:

       To indicate that a Content-Coding is used with a Content-Type, the
       Content-Coding value is appended to the Content-Type value (media
       type and parameters, if any), separated by a "@" sign.  For example
       (using a Content-Coding value of "deflate" as defined in
       Section 4.2.2 of [RFC7230]):

       text/plain; charset=utf-8@deflate

       If no "@" sign is present after the media type and parameters, then
       no Content-Coding has been specified, and the "identity" Content-
       Coding is used -- no encoding transformation is employed.

    (Again, a link in the HTML version on the section reference.)

    Now in https://protect2.fireeye.com/v1/url?k=28321037-77a92931-283250ac-86ee86bd5107-7440f4e9314603fa&q=1&e=38e64623-52dd-4890-be02-23258b6d566d&u=https%3A%2F%2Fgithub.com%2Fcore-wg%2Fsenml-data-ct%2Fpull%2F4%2Fcommits%2F4d994bb

    > Other than those two slightly confusing bits, great document - I enjoyed
    > reading it and the intentions, purpose and use of this document are clear.

    Thank you!

    Grüße, Carsten

    _______________________________________________
    art mailing list
    [e-mail]
    https://www.ietf.org/mailman/listinfo/art