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" <art-bounces@xxxxxxxx on behalf of cabo@xxxxxxx> 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
art@xxxxxxxx
https://www.ietf.org/mailman/listinfo/art
--
last-call mailing list
last-call@xxxxxxxx
https://www.ietf.org/mailman/listinfo/last-call
