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

Carsten Bormann <cabo@tzi.org> Wed, 25 August 2021 17:51 UTC

Return-Path: <cabo@tzi.org>
X-Original-To: core@ietfa.amsl.com
Delivered-To: core@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id C70F73A120A; Wed, 25 Aug 2021 10:51:58 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id RC4cFaPS2ULY; Wed, 25 Aug 2021 10:51:50 -0700 (PDT)
Received: from gabriel-smtp.zfn.uni-bremen.de (gabriel-smtp.zfn.uni-bremen.de [134.102.50.15]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id D3D263A1201; Wed, 25 Aug 2021 10:51:48 -0700 (PDT)
Received: from [192.168.217.118] (p548dc8d5.dip0.t-ipconnect.de [84.141.200.213]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-smtp.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4Gvtp91dyDz2xY3; Wed, 25 Aug 2021 19:51:45 +0200 (CEST)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.7\))
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <162989820511.22802.13018106629607951033@ietfa.amsl.com>
Date: Wed, 25 Aug 2021 19:51:44 +0200
Cc: art@ietf.org, last-call@ietf.org, draft-ietf-core-senml-data-ct.all@ietf.org, core@ietf.org
X-Mao-Original-Outgoing-Id: 651606704.662935-5aa696863cfea984958527d0dd4247e4
Content-Transfer-Encoding: quoted-printable
Message-Id: <8AE2D0CA-C259-4E4A-8369-601D750DAA9D@tzi.org>
References: <162989820511.22802.13018106629607951033@ietfa.amsl.com>
To: Bron Gondwana <brong@fastmailteam.com>
X-Mailer: Apple Mail (2.3608.120.23.2.7)
Archived-At: <https://mailarchive.ietf.org/arch/msg/core/KXHCyhDFyPj-d4aood8w5s3bf8s>
Subject: Re: [core] [art] Artart last call review of draft-ietf-core-senml-data-ct-04
X-BeenThere: core@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Constrained RESTful Environments \(CoRE\) Working Group list" <core.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/core>, <mailto:core-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/core/>
List-Post: <mailto:core@ietf.org>
List-Help: <mailto:core-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/core>, <mailto:core-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 25 Aug 2021 17:51:59 -0000

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