Re: [netmod] Proposal to enhance the YANG tree output

Lou Berger <lberger@labn.net> Wed, 20 September 2017 11:35 UTC

Return-Path: <lberger@labn.net>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 01E0412EC30 for <netmod@ietfa.amsl.com>; Wed, 20 Sep 2017 04:35:16 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.201
X-Spam-Level:
X-Spam-Status: No, score=-4.201 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-2.8, RCVD_IN_SORBS_SPAM=0.5, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (768-bit key) header.d=labn.net
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 UWnjbYGLO3Kh for <netmod@ietfa.amsl.com>; Wed, 20 Sep 2017 04:35:09 -0700 (PDT)
Received: from outbound-ss-1812.hostmonster.com (gproxy1-pub.mail.unifiedlayer.com [69.89.25.95]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 23A6D1321A0 for <netmod@ietf.org>; Wed, 20 Sep 2017 04:35:09 -0700 (PDT)
Received: from CMOut01 (cmgw2 [10.0.90.82]) by gproxy1.mail.unifiedlayer.com (Postfix) with ESMTP id 426F3175E5F for <netmod@ietf.org>; Wed, 20 Sep 2017 05:35:08 -0600 (MDT)
Received: from box313.bluehost.com ([69.89.31.113]) by CMOut01 with id Bnb41w00j2SSUrH01nb7ft; Wed, 20 Sep 2017 05:35:08 -0600
X-Authority-Analysis: v=2.2 cv=K4VSJ2eI c=1 sm=1 tr=0 a=h1BC+oY+fLhyFmnTBx92Jg==:117 a=h1BC+oY+fLhyFmnTBx92Jg==:17 a=IkcTkHD0fZMA:10 a=xqWC_Br6kY4A:10 a=2JCJgTwv5E4A:10 a=u07AKapRAAAA:8 a=wU2YTnxGAAAA:8 a=AUd_NHdVAAAA:8 a=L0rEDTKoYN_WA3rYJbkA:9 a=QEXdDO2ut3YA:10 a=SkebfZ6J2Mmvk2rLHZle:22 a=Yz9wTY_ffGCQnEDHKrcv:22
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=labn.net; s=default; h=Content-Transfer-Encoding:Content-Type:In-Reply-To:MIME-Version :Date:Message-ID:References:Cc:To:Subject:From:Sender:Reply-To:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=5ERSXn6c3gh7q9R+L55dpEn5Ty2u+IIoMjlSaDnGI34=; b=eeHrQkSeYi52KMxcCRd8Htwa23 pjKo8/qlEjO3m2OhTIK9P0Yi6ESY+REyddAqaceLVMBTToZdjP0a2qyYfDtx6F9uT+o4eP8US/4Qy 1SXGGutyGJEwbrJPupVIAD8L/;
Received: from pool-100-15-84-20.washdc.fios.verizon.net ([100.15.84.20]:39662 helo=[IPv6:::1]) by box313.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.87) (envelope-from <lberger@labn.net>) id 1dudHU-000kxr-67; Wed, 20 Sep 2017 05:35:04 -0600
From: Lou Berger <lberger@labn.net>
To: Martin Bjorklund <mbj@tail-f.com>
Cc: rwilton@cisco.com, netmod@ietf.org
References: <990b8722-7a48-46ce-3f5d-96bc5cb66075@labn.net> <20170919.154238.1738748131929616921.mbj@tail-f.com> <d555bb7e-c800-64c6-8272-5e2210028603@labn.net> <20170920.083439.2133568542308133041.mbj@tail-f.com>
Message-ID: <2816f2ca-8e86-aeb6-a8f3-bfad703f6362@labn.net>
Date: Wed, 20 Sep 2017 07:35:01 -0400
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.3.0
MIME-Version: 1.0
In-Reply-To: <20170920.083439.2133568542308133041.mbj@tail-f.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 8bit
X-AntiAbuse: This header was added to track abuse, please include it with any abuse report
X-AntiAbuse: Primary Hostname - box313.bluehost.com
X-AntiAbuse: Original Domain - ietf.org
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - labn.net
X-BWhitelist: no
X-Source-IP: 100.15.84.20
X-Exim-ID: 1dudHU-000kxr-67
X-Source:
X-Source-Args:
X-Source-Dir:
X-Source-Sender: pool-100-15-84-20.washdc.fios.verizon.net ([IPv6:::1]) [100.15.84.20]:39662
X-Source-Auth: lberger@labn.net
X-Email-Count: 3
X-Source-Cap: bGFibm1vYmk7bGFibm1vYmk7Ym94MzEzLmJsdWVob3N0LmNvbQ==
X-Local-Domain: yes
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/UcHGN2aMk4hoSXwAOAPG9UuJNrI>
Subject: Re: [netmod] Proposal to enhance the YANG tree output
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 20 Sep 2017 11:35:16 -0000



On September 20, 2017 2:33:47 AM Martin Bjorklund <mbj@tail-f.com> wrote:

> Lou Berger <lberger@labn.net> wrote:
>>
>>
>> On 9/19/2017 9:42 AM, Martin Bjorklund wrote:
>> > Lou Berger <lberger@labn.net> wrote:
>> >>
>> >> On 9/19/2017 7:29 AM, Martin Bjorklund wrote:
>> >>> Lou Berger <lberger@labn.net> wrote:
>> >>>> Martin,
>> >>>>
>> >>>> Speaking as a contributor:
>> >>>>
>> >>>>
>> >>>> On 9/15/2017 7:40 AM, Martin Bjorklund wrote:
>> >>>>> Robert Wilton <rwilton@cisco.com> wrote:
>> >>>>>> On 15/09/2017 11:21, Ladislav Lhotka wrote:
>> >>>>>>> Andy Bierman píše v Čt 14. 09. 2017 v 08:43 -0700:
>> >>>>>>>> Hi,
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> Actually I liked the early pyang output that was concise and easy to
>> >>>>>>>> remember.
>> >>>>>>>> The current format gets very cluttered and there are too many little
>> >>>>>>>> symbols
>> >>>>>>>> to remember them all.
>> >>>>>>> I agree.
>> >>>>> Me too.  The current draft adds three new magic symbols: "mp" "@" and
>> >>>>> "/".
>> >>>>>
>> >>>>> "mp" is for a mount point, and it can be generated directly from the
>> >>>>> YANG modules.
>> >>>>>
>> >>>>> Directly under a "mp", "/" and "@" are used to indicate that a node 
>> is mounted
>> >>>>> or available through a parent reference, respectively.
>> >>>>>
>> >>>>> I actually question the usability of "/" and "@".
>> >>>> I agree that / and @ are something new, and enabled by schema mount. 
>> >>>> There have been repeated comments in the RTG WG that there needs to be
>> >>>> some way for vendors to convey what they have implemented with Schema
>> >>>> mount
>> >>> If that's the requirement, using the tree diagram is probably not the
>> >>> best way.  The tree diagram is intended to provide an overview of a
>> >>> given (set of) YANG module(s).
>> >>>
>> >>> A perhaps better way to convey the information is to create a file
>> >>> with an instantiated /schema-mounts tree.
>> >> using what syntax?  JSON and XML really isn't that easy for the (human)
>> >> reader to parse.
>> > Either JSON or XML.
>> This is fine for code, less so for humans.  We include both in the NI
>> draft, the tree provides a quick overview, the JSON provides the details. 
>>
>> >
>> >>>> and this is one way to help convey (a) what is expected of server
>> >>>> implementors and (b) what client implementors should expect.
>> >>>>
>> >>>    Hence the
>> >>>> current draft text:
>> >>>>
>> >>>>   In describing the intended use of a module containing a mount point,
>> >>>>    it is helpful to show how the mount point would look with mounted
>> >>>>    modules.
>> >>>>
>> >>>> The whole point of trees is to facilitate understanding for those who
>> >>>> are less familiar with a model than the authors, and IMO that's the
>> >>>> paramount perspective in this discussion.
>> >>> Fully agree!  I would say that we have to make sure that the diagrams
>> >>> can be understood by people less familiar with the technology than the
>> >>> authors.  Mixing schema and instance data does not help here.
>> >> Can you propose an alternative?
>> > As I have written before, I think the "/" is not needed, so I would
>> > remove that.  I would also not list the nodes from "parent-references"
>> > in the same tree ouput.  It is not clear to me that this level of
>> > detail is needed in the tree, and - as noted before - it isn't even
>> > correct to list e.g. "interfaces" when the parent-reference in fact
>> > selects a single interface.
>> >
>> >> The routing WG participants seem to
>> >> find these useful, we can also ask there for broader input if you'd like.
>> > One approach is to add the union of eveything that some people find
>> > useful.  In the end we have to look for WG consensus.  Several people
>> > have said that they prefer a less cluttered format.
>> In the context of listing enums...
>>
>> >
>> >>>>> Since a parent
>> >>>>> reference can be very specific, e.g. one specific interface, it isn't
>> >>>>> really accurate to show:
>> >>>>>
>> >>>>>                   +--mp vrf-root
>> >>>>>                      +--rw rt:routing/
>> >>>>>                      |  ...
>> >>>>>                      +--ro if:interfaces@
>> >>>> This is just a conditional and we have precedent on how to handle
>> >>>> conditional representation.   
>> >>>>
>> >>>>> And the trailing "/" on rt:routing doesn't add any information we
>> >>>>> don't already know.  Since vrf-root is a mount point, it follows that
>> >>>>> its children are mounted.
>> >>>> The issue is a bit more complex when considering some real use cases,
>> >>>> particularity when parent references and augmentations are used.  For
>> >>>> example consider the following *without* the use / or @:
>> >>>>
>> >>>> module: ietf-network-instance
>> >>>>   +--rw network-instances
>> >>>>      +--rw network-instance* [name]
>> >>>>         | ...
>> >>>>         +--rw (root-type)
>> >>>>            +--:(vrf-root)
>> >>>>               +--mp vrf-root
>> >>>>                  +--ro rt:routing-state
>> >>>>                  |  +--ro router-id?                 yang:dotted-quad
>> >>>>                  |  +--ro control-plane-protocols
>> >>>>                  |     +--ro control-plane-protocol* [type name]
>> >>>>                  |        +--ro ospf:ospf
>> >>>>                  |           +--ro instance* [af]
>> >>>>                  +--rw rt:routing
>> >>>>                  |  +--rw router-id?                 yang:dotted-quad
>> >>>>                  |  +--rw control-plane-protocols
>> >>>>                  |     +--rw control-plane-protocol* [type name]
>> >>>>                  |     +--rw ospf:ospf
>> >>>>                  |        +--rw instance* [af]
>> >>>>                  |           +--rw areas
>> >>>>                  |              +--rw area* [area-id]
>> >>>>                  |                 +--rw interfaces
>> >>>>                  |                    +--rw interface* [name]
>> >>>>                  |                       +--rw name if:interface-ref
>> >>>>                  |                       +--rw cost?   uint16
>> >>>>                  +--ro if:interfaces
>> >>>>                  |  ...
>> >>>>                  +--ro if:interfaces-state
>> >>>>                  |  ...
>> >>>>
>> >>>>
>> >>>> It's certainly not too hard to spot the top level mounts, but it is
>> >>>> impossible to distinguish the parent references from the actual mounts. 
>> >>> My proposal would be to not even show the parent references in the
>> >>> diagram.  If we do that, the '/' is not needed.
>> >>>
>> >>>> Further more, some mounts are hard to spot.  For example, notice ospf. 
>> >>>> Did you notice that it's a mount?
>> >>> This is actually not correct.  ospf is *not* a mount; it is an augment.
>> >>>
>> >> it's a mounted module that augments another mounted module.
>> > But why would it have a "/" just b/c it is augmented, when its sibling
>> > 'control-plan-protocol' doesn't have the "/"?  What addition info does
>> > the "/" convey?
>> That it is a (sub)tree that is present due to a mounted module.
>
> So is 'control-plane-protocol', so then it should also have '/',
> right?

Why, it's defined in ietf-routing (under rt:routing-state and rt:routing)?

Lou

>
>
> /martin