Re: [core] Yangdoctors last call review of draft-ietf-core-yang-cbor-15

Carsten Bormann <cabo@tzi.org> Mon, 14 June 2021 12: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 344333A2332; Mon, 14 Jun 2021 05:51:03 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.897
X-Spam-Level:
X-Spam-Status: No, score=-1.897 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_FAIL=0.001, SPF_HELO_NONE=0.001, URIBL_BLOCKED=0.001] autolearn=no 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 gIP61jPzCkFX; Mon, 14 Jun 2021 05:50:58 -0700 (PDT)
Received: from gabriel-2.zfn.uni-bremen.de (gabriel-2.zfn.uni-bremen.de [IPv6:2001:638:708:32::19]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3CC9B3A2333; Mon, 14 Jun 2021 05:50:58 -0700 (PDT)
Received: from [192.168.217.118] (p548dcc89.dip0.t-ipconnect.de [84.141.204.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-2.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4G3WXG43vJz2xHN; Mon, 14 Jun 2021 14:50:54 +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: <CAJFkdRx9D8EcDLty02a60BxLcMF9n9WkcNBXDTDczdFnUULQFA@mail.gmail.com>
Date: Mon, 14 Jun 2021 14:50:54 +0200
Cc: Joe Clarke <jclarke@cisco.com>, draft-ietf-core-yang-cbor.all@ietf.org, yang-doctors@ietf.org, "ivaylopetrov@google.com" <ivaylopetrov@google.com>, core <core@ietf.org>, Last Call <last-call@ietf.org>
X-Mao-Original-Outgoing-Id: 645367854.17946-dcd403590f5c97a2a970fb4b32e46e06
Content-Transfer-Encoding: quoted-printable
Message-Id: <E79E58D6-2C0B-4A4B-AA36-F0AB5CB21E9F@tzi.org>
References: <161592338136.13562.2421108714318351834@ietfa.amsl.com> <CAJFkdRx9D8EcDLty02a60BxLcMF9n9WkcNBXDTDczdFnUULQFA@mail.gmail.com>
To: Ivaylo Petrov <ivaylo@ackl.io>
X-Mailer: Apple Mail (2.3608.120.23.2.7)
Archived-At: <https://mailarchive.ietf.org/arch/msg/core/M5rQULgbRxMeJ_eozpYazQAxJ1g>
Subject: Re: [core] Yangdoctors last call review of draft-ietf-core-yang-cbor-15
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: Mon, 14 Jun 2021 12:51:04 -0000

> On 2021-06-14, at 13:46, Ivaylo Petrov <ivaylo@ackl.io> wrote:
> 
>> I think documenting the true/false value of the primitives here (noted in the
>> CBOR encoding) would aid in clarity.  For example, "primitive(20) [false]".
> 
> [IP]: I am not against that, I am only concerned if that would be
> readable for others that are used to the diagnostic notation,
> otherwise I am fine to apply this change.

Let me pick this one because it is all my fault.

The “CBOR encoding” snippets are generated by the CBOR diagnostic tool (which is also available at cbor.me on the Web.)

The comments it generates in its “pretty hex” output are rather generic comments about the encoding; they are not trying to reflect the exact meaning of the content.  This usually comes up with negative numbers (where the argument numbers shown are not bit-wise inverted to generate the negative number), but more detail could also be added for false/null/true/undefined.

Instead of manually tweaking dozens of generated examples, I think it would be a good idea to agree about the best way to update the tool.  Until that is done and implemented, I would feel uncomfortable with all this tweaking, because it will be error-prone and inconsistent.

Grüße, Carsten