Subject: Re: [yang-doctors] Consistency for naming lists and leaf-lists

From: Martin Bjorklund <[email-masked]>
Date: Mon, 02 Dec 2019 09:44:26 +0100 (CET)

"Acee Lindem (acee)" <[email-masked]> wrote:
> Hi Rob,
> In ietf-ospf.yang and ietf-isis.yang, we did define an enclosing
> container for many of the lists. The impetus was that this would allow
> it to be retrieved with a single query.

IMO this is a protocol issue (if it is an issue).  It is perfectly
fine to do an XPath filter for /interfaces/interface  or subtree
filter <interfaces><interface/></interfaces> to get all list
entries, so the enclosing container isn't necessary for single query
retrieval.

/martin

> I do agree that we should have
> a guideline for this as we went back and forth. For example:
> 
>         container interfaces {
>             description "All interfaces.";
>             list interface {
>               key "name";
>               description
>                 "List of OSPF interfaces.";
>               leaf name {
>                 type if:interface-ref;
>                 description
>                   "Interface name reference.";
>               }
>               uses interface-config;
>               uses interface-state;
>             }
> 
> Thanks,
> Acee
> 
> 
> From: yang-doctors <[email-masked]> on behalf of "Rob
> Wilton (rwilton)" <[email-masked]>
> Date: Friday, November 29, 2019 at 5:53 AM
> To: YANG Doctors <[email-masked]>
> Subject: [yang-doctors] Consistency for naming lists and leaf-lists
> 
> Hi,
> 
> Perhaps this has been debated to death, or there is already an
> agreement, but do we have an agreed consistent approach for
> naming/containing lists in YANG?
> 
> In particular:
> 
> 1) Should the list be enclosed in its own container
> (e.g. interfaces/interface)?
> 
> 2)      Should the name of the list be singular or plural?
> 
> 3)      Should leaf-lists be treated similarly?
> 
> 4) What if the list is a top level YANG node, does it get put into a
> container in that scenario (e.g. network-instances/network-instance)?
> 
> I think that it would be good if we can have a consistent approach
> during reviews, perhaps folding into a future update of RFC 8407.
> 
> Looking at a couple of the recent models in RFCs, would seem to
> suggest:
> 
> 1)      Top-level data nodes should probably always be containers
> 
> 2) Lists don’t need to be enclosed in a container (and should not be
> top-level data-nodes).
> 
> 3)      Names of lists and leaf-lists should be singular not plural.
> 
> Does that align with other folk’s opinions?
> 
> Thanks,
> Rob
>