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

[Martin Bjorklund <[e-mail]>]

"Rob Wilton (rwilton)" <[e-mail]> 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 <[e-mail]> On Behalf Of Martin
> Bjorklund
> Sent: 15 January 2020 12:59
> To: scott.mansfield=[e-mail]
> Cc: [e-mail]
> 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=[e-mail]> 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
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors
>