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

Martin Bjorklund <mbj@tail-f.com> Mon, 02 December 2019 08:45 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 164C912022D for <yang-doctors@ietfa.amsl.com>; Mon, 2 Dec 2019 00:45:03 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham 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 5QcaXQldzSSN for <yang-doctors@ietfa.amsl.com>; Mon, 2 Dec 2019 00:45:01 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id F30C5120154 for <yang-doctors@ietf.org>; Mon, 2 Dec 2019 00:45:00 -0800 (PST)
Received: from localhost (unknown [173.38.220.41]) by mail.tail-f.com (Postfix) with ESMTPSA id 29BC41AE02AA; Mon, 2 Dec 2019 09:45:00 +0100 (CET)
Date: Mon, 02 Dec 2019 09:44:26 +0100
Message-Id: <20191202.094426.114887713283805872.mbj@tail-f.com>
To: acee@cisco.com
Cc: rwilton@cisco.com, yang-doctors@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <19B68566-741D-408A-871D-4C99E09643FB@cisco.com>
References: <19B68566-741D-408A-871D-4C99E09643FB@cisco.com>
X-Mailer: Mew version 6.8 on Emacs 25.2
Mime-Version: 1.0
Content-Type: Text/Plain; charset="utf-8"
Content-Transfer-Encoding: base64
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/yYS-8Kbw_En_UbP5Aih7PUOJq1s>
Subject: Re: [yang-doctors] Consistency for naming lists and leaf-lists
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: Mon, 02 Dec 2019 08:45:03 -0000

"Acee Lindem (acee)" <acee@cisco.com> 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 <yang-doctors-bounces@ietf.org> on behalf of "Rob
> Wilton (rwilton)" <rwilton@cisco.com>
> Date: Friday, November 29, 2019 at 5:53 AM
> To: YANG Doctors <yang-doctors@ietf.org>
> 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
>