Re: [yang-doctors] Style question from individuals working on IEEE YANG

"Rob Wilton (rwilton)" <rwilton@cisco.com> Wed, 15 January 2020 14:24 UTC

Return-Path: <rwilton@cisco.com>
X-Original-To: yang-doctors@ietfa.amsl.com
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 2D88D120025 for <yang-doctors@ietfa.amsl.com>; Wed, 15 Jan 2020 06:24:39 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -14.501
X-Spam-Level:
X-Spam-Status: No, score=-14.501 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5, SPF_PASS=-0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=unavailable autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.com header.b=G+FSa0Jx; dkim=pass (1024-bit key) header.d=cisco.onmicrosoft.com header.b=xa62i3NN
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 0jphBwUMILJ3 for <yang-doctors@ietfa.amsl.com>; Wed, 15 Jan 2020 06:24:34 -0800 (PST)
Received: from rcdn-iport-8.cisco.com (rcdn-iport-8.cisco.com [173.37.86.79]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 29122120026 for <yang-doctors@ietf.org>; Wed, 15 Jan 2020 06:24:34 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=7167; q=dns/txt; s=iport; t=1579098274; x=1580307874; h=from:to:cc:subject:date:message-id:references: in-reply-to:content-transfer-encoding:mime-version; bh=0G9Z6Mhgx8eBypKmTVjEbLznAbk2n1WhURPpCz25qPQ=; b=G+FSa0Jx1SorZpEitk2XwWV/SM3aKcyZr7LYleQFan7usgX5xEYjq1AD EjtZXVaqQ5KGJV+Ym0B3XHKGO9kBKfyEgC1IRtFDC+Yc0bSEALoXte56T rgymfoDF6qQfFvhF7F9F9qqtVV2JPj5AI2WOzeU5h7KzNEtY9nzQYoqO6 0=;
IronPort-PHdr: =?us-ascii?q?9a23=3AFM6PdhzTtsasw9fXCy+N+z0EezQntrPoPwUc9p?= =?us-ascii?q?sgjfdUf7+++4j5YhSN/u1j2VnOW4iTq+lJjebbqejBYSQB+t7A1RJKa5lQT1?= =?us-ascii?q?kAgMQSkRYnBZufFkz/MPnsRyc7B89FElRi+iLzPA=3D=3D?=
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0CwAADiHx9e/5FdJa1kGgEBAQEBAQE?= =?us-ascii?q?BAQMBAQEBEQEBAQICAQEBAYF7gVRQBWxYIAQLKgqHSwOKdIJfmA6BQoEQA1Q?= =?us-ascii?q?JAQEBDAEBGAsKAgEBhEACgX8kOBMCAw0BAQQBAQECAQUEbYU3DIVeAQEBAQM?= =?us-ascii?q?BARAoBgEBLAQHAQsEAgEIDgMEAQEBFQkQJwsdCAEBBAEJBAUIGoMFgkoDLgE?= =?us-ascii?q?CDJplAoE4iGGCJ4J/AQEFhRsYgg0DBoE2jBgagUE/gViCHi4+gmQBAQKBHBE?= =?us-ascii?q?OEBg9gwOCCiKWTZgFdgqCOIw2SolLgkeMR4tgjlybAAIEAgQFAg4BAQWBaSI?= =?us-ascii?q?qGoEUcBU7gmxQGA2IAYNzhRSFP3QCAYEmiXWBMgGBDwEB?=
X-IronPort-AV: E=Sophos;i="5.70,322,1574121600"; d="scan'208";a="701440100"
Received: from rcdn-core-9.cisco.com ([173.37.93.145]) by rcdn-iport-8.cisco.com with ESMTP/TLS/DHE-RSA-SEED-SHA; 15 Jan 2020 14:24:32 +0000
Received: from XCH-RCD-004.cisco.com (xch-rcd-004.cisco.com [173.37.102.14]) by rcdn-core-9.cisco.com (8.15.2/8.15.2) with ESMTPS id 00FEOWWF015063 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=FAIL); Wed, 15 Jan 2020 14:24:32 GMT
Received: from xhs-rtp-003.cisco.com (64.101.210.230) by XCH-RCD-004.cisco.com (173.37.102.14) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Wed, 15 Jan 2020 08:24:32 -0600
Received: from xhs-rcd-002.cisco.com (173.37.227.247) by xhs-rtp-003.cisco.com (64.101.210.230) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Wed, 15 Jan 2020 09:24:30 -0500
Received: from NAM12-MW2-obe.outbound.protection.outlook.com (72.163.14.9) by xhs-rcd-002.cisco.com (173.37.227.247) with Microsoft SMTP Server (TLS) id 15.0.1473.3 via Frontend Transport; Wed, 15 Jan 2020 08:24:30 -0600
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=jxoY/9VSjAEqouhsi6DfZ5KkOhvQJDm+QCVrtjYqBM7QLnR4S0RsztzOQIC1PTvx47lA2KkwO7TB/aJ0Nu2WIMwAnoQzfFHKfu6SHLOA2Zt9/OnvhUXTxOohBOE64L0q3oFQ9HMEDXDvDcnq9doFOZK4ZuOuPxJJ+k5fb6daTh4wD6zZK0AcXKo0cKSCLLn6PLmoqZvMC6Aq+iO/iwu9gd/MQ/EIYCzBU7fRhxI6k8vaID8enNSXHA8lRcNEpubXy//jrPPsCQB4ocJj1zalCSsXlaXSirVyRL8Bdgwg5Iaqru6b5MozI0EvUyPhbK6v8wONY5Yv1A1BwT5xx1bTQQ==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=jQu8eJqW9NjH1DId2ZyHGMsWcjqh4EMP/WEx86rTnrg=; b=TgJOPcErdLp0VftL7GGhZOvXGOxKXAD26EIbaZcxPKWAOOC14I6a+gFmHPNOZ8WWrkb6BYndNhliaJrNP3yyKbGLaEZMX0aL3v/WK2uB4O0ikf3MQfyBeLl4ejjic3Qz0VPcyX0Ud3/go7zJl8XcE7NbHvNu1j7syXZ3YR8R4X8mvVDvH5sFmImOoFpZvf/SAlR7/BLK9GhwMWn5C2aZGPS7d/cgPzIbpO1ammfj/CyYA5m6MV9kepMrSwH2jv6nmX4pyQn1TJji2ru+PMZGwFDDmRbvUQrR0ao0XduSwVT/4zXAsgsFr04Z6BQjdLqZvUj3PnBuj0+XiO5ILhglxQ==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=cisco.com; dmarc=pass action=none header.from=cisco.com; dkim=pass header.d=cisco.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cisco.onmicrosoft.com; s=selector2-cisco-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=jQu8eJqW9NjH1DId2ZyHGMsWcjqh4EMP/WEx86rTnrg=; b=xa62i3NNmsqOB+SHpkwO35D79keRmHc+Ihix8itaaHAEpVSBNMAIgeLrBNnXV9YSPzXtvwQ1ZHpE9B4iUoZKscXoH4e4urYsDYF+o6JFOrSud2q4t6p7JYAWggpe6LYg/FivbogDf6A55uGFA7D2tAPja2QqLsjyqi+185qNHC8=
Received: from MN2PR11MB4366.namprd11.prod.outlook.com (52.135.38.209) by MN2PR11MB3742.namprd11.prod.outlook.com (20.178.254.79) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2623.9; Wed, 15 Jan 2020 14:24:28 +0000
Received: from MN2PR11MB4366.namprd11.prod.outlook.com ([fe80::b9ce:1058:5fa6:44a1]) by MN2PR11MB4366.namprd11.prod.outlook.com ([fe80::b9ce:1058:5fa6:44a1%7]) with mapi id 15.20.2623.018; Wed, 15 Jan 2020 14:24:28 +0000
From: "Rob Wilton (rwilton)" <rwilton@cisco.com>
To: Martin Bjorklund <mbj@tail-f.com>, "scott.mansfield=40ericsson.com@dmarc.ietf.org" <scott.mansfield=40ericsson.com@dmarc.ietf.org>
CC: "yang-doctors@ietf.org" <yang-doctors@ietf.org>
Thread-Topic: [yang-doctors] Style question from individuals working on IEEE YANG
Thread-Index: AdXLnSlUWHhFHNStQciOhysBaa3xVgABmjaAAAK3poA=
Date: Wed, 15 Jan 2020 14:24:28 +0000
Message-ID: <MN2PR11MB4366BE4459F74059C2B246C2B5370@MN2PR11MB4366.namprd11.prod.outlook.com>
References: <SN6PR15MB23827FBAD5C61D8868ECECEE8B370@SN6PR15MB2382.namprd15.prod.outlook.com> <20200115.135907.604098548525922549.mbj@tail-f.com>
In-Reply-To: <20200115.135907.604098548525922549.mbj@tail-f.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
authentication-results: spf=none (sender IP is ) smtp.mailfrom=rwilton@cisco.com;
x-originating-ip: [173.38.220.36]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 30ec742a-8c26-41c8-6859-08d799c6a193
x-ms-traffictypediagnostic: MN2PR11MB3742:
x-microsoft-antispam-prvs: <MN2PR11MB3742FD49340A9425DE39B1F6B5370@MN2PR11MB3742.namprd11.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:10000;
x-forefront-prvs: 02830F0362
x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(4636009)(376002)(346002)(39860400002)(366004)(396003)(136003)(189003)(199004)(316002)(55016002)(2906002)(5660300002)(52536014)(86362001)(26005)(478600001)(110136005)(53546011)(186003)(7696005)(66556008)(6506007)(71200400001)(64756008)(4326008)(81166006)(76116006)(66946007)(33656002)(8676002)(66446008)(81156014)(966005)(66476007)(8936002)(9686003); DIR:OUT; SFP:1101; SCL:1; SRVR:MN2PR11MB3742; H:MN2PR11MB4366.namprd11.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1;
received-spf: None (protection.outlook.com: cisco.com does not designate permitted sender hosts)
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: 5aTptU9Chun2Dlv60U3fUKXCYI83quiPrJB86uXLPloDooJE+/3JlufYbEF55NJZK3MrFBT3y5MI/KRHfpM/6mbpIOOlX9taaGyA7MFeiyVbsT4wvsSNmTFdUAESjC3re0xCoR7dB5+UBUUwj12yzqzrnH6s5JdgmnlaEaNBC4gbArzjIaPz+FgkFgL0tmmV+fXUsitRmgb+CfWvoub+XN5heNiuDLZ2gWDa0qGSYW0fe2p7XAFt2o6J8XBSZmzbBXK+Mpk4rbwKl395vUiLPEymNssXZ9LtdPnqMve5vrAGhkItA73EheXsmgZQY/XgAZAebQMJLxw6yiKsUy27+illt0OPEc/LIY0vyCvYOAlyHzjLPKdssDsR9j9HaUZ798wHHD4bv4asJDiJsBMA6w2GR/glZlivd8E0cIQVBR3+GVgQK+QWlBc9CyXE0sKxRz4vWisq8e7ej+wuULre7T+js12isIYH1opy1hGPwFE=
x-ms-exchange-transport-forked: True
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: 30ec742a-8c26-41c8-6859-08d799c6a193
X-MS-Exchange-CrossTenant-originalarrivaltime: 15 Jan 2020 14:24:28.6362 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 5ae1af62-9505-4097-a69a-c1553ef7840e
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: 7dCXCEsL9FKyWjnT2NzRedbe8BQcjzMuGWb3nLodP6XWHJDN8GEYjn96VvnTUyrgCDJGn4aLlbfmxUcXlQggrg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR11MB3742
X-OriginatorOrg: cisco.com
X-Outbound-SMTP-Client: 173.37.102.14, xch-rcd-004.cisco.com
X-Outbound-Node: rcdn-core-9.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/B0bduklWEiiXw9_QyLqSQZBFEiU>
Subject: Re: [yang-doctors] Style question from individuals working on IEEE YANG
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 15 Jan 2020 14:24:40 -0000

Hi Martin, Juergen,

For clarification, are you saying that you think that all operational lists should have a corresponding size leaf?  Note - I agree that they are unneeded and unhelpful in configuration.

Or for operational lists that are likely to be small (e.g. perhaps less than a dozen entries) then omitting a size leaf may be appropriate, i.e. forcing the client to request and count the list entries if a count is required.

Thanks,
Rob


-----Original Message-----
From: yang-doctors <yang-doctors-bounces@ietf.org> On Behalf Of Martin Bjorklund
Sent: 15 January 2020 12:59
To: scott.mansfield=40ericsson.com@dmarc.ietf.org
Cc: yang-doctors@ietf.org
Subject: Re: [yang-doctors] Style question from individuals working on IEEE YANG

Hi,

It seems that (A) is not really an option.  I agree that the info should be in the YANG model, so that leaves us with (C) or (D).

You have a config false node that has some semantics.  Since it is a config false node, someone needs to write code to implement it, so it is important that it is clear what the semantics are.  But it is also important that other readers of the model understand what the node is supposed to do.  Hence, I think taht you definitely should do (C), i.e., document the semantics in clear prose.

A must expression (D) in general doesn't convey the same information as plain text - you can define a constraint that must be true, but that doesn't mean that it is clear to everyone *why* the constraint must be true, or what an implementation is supposed to do in order to produce a value that matches the constraint.  

[In your example it might be obvious, especially if you also take the leaf's name into account:

     must '. = count(../my-list)';
]



/martin





Scott Mansfield <scott.mansfield=40ericsson.com@dmarc.ietf.org> wrote:
> This is an informal request to poll the YANG Doctors on a topic under 
> discussion
> 
> in the IEEE 802.1 working group.
> 
>  
> 
> The YANG people from IEEE 802.1 discovered a symmetric modelling issue 
> related
> 
> to YANG lists, and kindly request for feedback about the common 
> practices in
> 
> YANG modules beyond those from IEEE 802.1.
> 
>  
> 
> Consider the following YANG code example:
> 
> 01: leaf my-list-size {
> 
> 02:   type uint32;
> 
> 03:   config false;
> 
> 04:   description "The number of elements in 'my-list'";
> 
> 06: }
> 
> 07: leaf-list my-list {
> 
> 08:   type my-list-element-type;
> 
> 09: }
> 
>  
> 
> The state value of leaf my-list-size (L01) needs to be consistent with 
> the
> 
> number of elements in leaf-list my-list (L07). Therefore, IEEE 802.1
> 
> identified the following options:
> 
> A)           Delete the size leaf (i.e., my-list-size).
> 
> B)            Formulate consistency requirements in IEEE standards documents
> 
> C)            Formulate consistency requirements in YANG description nodes
> (e.g., L04).
> 
> D)           Formulate consistency requirements in YANG must statement(s)
> 
> E)            ???
> 
>  
> 
> The rationale of option A) is that a leaf-list implicitly provides the 
> number of
> 
> contained elements. NETCONF <get-config> or <get> operations can be 
> used to
> 
> retrieve all list elements content from a server, and thus the number 
> of
> 
> elements is also known to the client. A redundant size leaf is 
> entirely avoided.
> 
> The main concern in this approach is the associated amount of data to 
> be
> 
> transferred from server to client. As a practical example, a client 
> requiring
> 
> the number of entries in a Filtering Database (FDB) entries would read
> 
> potentially thousands of entries (IEEE 802.1Q does not specify a limit 
> here).
> 
> One might argue that clients don't have to know the number of elements 
> in the
> 
> FDB. However, the question whether there is a need or not is not the 
> point, it's
> 
> just an example, and there are several other, less commonly known, 
> lists
> 
> specified by IEEE 802.1 standards for which monitoring the size 
> information is
> 
> inevitable in practical use. Coexisting size leafs like leaf 
> my-list-size
> 
> appears more efficient for this purpose. 
> 
>  
> 
> As soon as a size leafs for list elements (or specific subsets, such 
> as FDB
> 
> entries of a particular type) exist, it is required to ensure 
> consistency
> 
> amongst a size leaf and the associated list in an unambiguous manner.
> Network
> 
> equipment specified by IEEE 802(.1) standards is often configured by 
> machines.
> 
> For example, a centralized controller device might compute and upload
> 
> network-consistent configurations to all devices in the network. As a 
> result,
> 
> configuration of such networks is lacking human intelligence - 
> unambiguous and
> 
> deterministic behavior is required, and thus it is also required that 
> the
> 
> relationship between lists and associated list size nodes is specified 
> cleanly.
> 
>  
> 
> Considering option B), such specification can (and is in many cases) 
> be located
> 
> in IEEE standards documents for the associated managed objects. 
> However, there
> 
> are concerns from IEEE 802.1 that implementers might accidentally 
> oversee such
> 
> statements (e.g., IEEE 802.1Q-2018 is a document with more than 2000 pages).
> It
> 
> is better to locate such information in YANG.
> 
>  
> 
> Option C) sketches such a specification in the YANG code in a human 
> readable
> 
> manner,  but it has some drawbacks. First, unambiguous normative 
> verbal
> 
> formulation can become long, YANG files become large, such strong 
> normative
> 
> specification is not helpful for client-side users and thus make the
> 
> descriptions more heavy-weight. Second, machines (e.g., YANG 
> compilers) cannot
> 
> interpret this specification.
> 
>  
> 
> Option D) appears to address these drawbacks: must statements allow 
> machine
> 
> readable XPath expressions (and also readable by humans). Moreover, 
> must
> 
> statements are separated from information in description nodes 
> relevant for
> 
> client-side users. However, IEEE 802.1 is not fully aware of the 
> feasibility,
> 
> limitations, and implications of this option. IEEE 802.1 could not 
> discover such
> 
> a use of must statements in IETF's published YANG files, such that 
> feedback from
> 
> other SDOs on this option would be highly appreciated.
> 
>  
> 
> Opinions desired and appreciated!
> 
>  
> 
> Regards,
> 
> -scott.
> 
> Scott Mansfield
> 
> Ericsson
> 

_______________________________________________
yang-doctors mailing list
yang-doctors@ietf.org
https://www.ietf.org/mailman/listinfo/yang-doctors