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://github.com/core-wg/senml-data-ct/commit/90a3deb > 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://github.com/core-wg/senml-data-ct/pull/4/commits/4d994bb > 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 -- last-call mailing list last-call@xxxxxxxx https://www.ietf.org/mailman/listinfo/last-call
