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

Martin Bjorklund <mbj@tail-f.com> Wed, 15 January 2020 14:40 UTC

Return-Path: <mbj@tail-f.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 97A32120091 for <yang-doctors@ietfa.amsl.com>; Wed, 15 Jan 2020 06:40:37 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001] autolearn=unavailable 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 P0VWM_ebw0j9 for <yang-doctors@ietfa.amsl.com>; Wed, 15 Jan 2020 06:40:33 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 1AA10120033 for <yang-doctors@ietf.org>; Wed, 15 Jan 2020 06:40:33 -0800 (PST)
Received: from localhost (unknown [173.38.220.41]) by mail.tail-f.com (Postfix) with ESMTPSA id 720E51AE08D8; Wed, 15 Jan 2020 15:40:30 +0100 (CET)
Date: Wed, 15 Jan 2020 15:39:53 +0100 (CET)
Message-Id: <20200115.153953.1163160295542187125.mbj@tail-f.com>
To: rwilton@cisco.com
Cc: scott.mansfield=40ericsson.com@dmarc.ietf.org, yang-doctors@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <MN2PR11MB4366BE4459F74059C2B246C2B5370@MN2PR11MB4366.namprd11.prod.outlook.com>
References: <SN6PR15MB23827FBAD5C61D8868ECECEE8B370@SN6PR15MB2382.namprd15.prod.outlook.com> <20200115.135907.604098548525922549.mbj@tail-f.com> <MN2PR11MB4366BE4459F74059C2B246C2B5370@MN2PR11MB4366.namprd11.prod.outlook.com>
X-Mailer: Mew version 6.8 on Emacs 25.2
Mime-Version: 1.0
Content-Type: Text/Plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/8ONlQPZiQVVVQJnUpN6mFd31H5Y>
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:40:37 -0000

"Rob Wilton (rwilton)" <rwilton@cisco.com> wrote:
> Hi Martin, Juergen,
> 
> For clarification, are you saying that you think that all operational
> lists should have a corresponding size leaf?

No!  My reply was to the question *if* this leaf is needed, how should
it be documented.


/martin


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