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

From: Bron Gondwana via Datatracker <[email-masked]>
Date: Wed, 25 Aug 2021 06:30:05 -0700

Reviewer: Bron Gondwana
Review result: Ready with Nits

This is a last-call review as part of the ARTART review team, of the document
draft-ietf-core-senml-data-ct-04.

This document describes an extension to RFC 8428 (SenML) to indicate the media
type and content-coding.

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)

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.  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.

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.

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.

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

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 25 Aug 2021 19:51:44 +0200

Hi Bron,

Thank you for this quite actionable review!

> 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.

> 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.
> 

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.

> "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

> 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

> reading it and the intentions, purpose and use of this document are clear.

Thank you!

Grüße, Carsten