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

Lou Berger <lberger@labn.net> Tue, 19 September 2017 14:21 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 D50B113219B for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 07:21:10 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Level:
X-Spam-Status: No, score=-4.2 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, URIBL_BLOCKED=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 eoBvdbF-JC0w for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 07:21:03 -0700 (PDT)
Received: from gproxy9-pub.mail.unifiedlayer.com (gproxy9-pub.mail.unifiedlayer.com [69.89.20.122]) (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 E10AD13318C for <netmod@ietf.org>; Tue, 19 Sep 2017 07:21:02 -0700 (PDT)
Received: from cmgw3 (unknown [10.0.90.84]) by gproxy9.mail.unifiedlayer.com (Postfix) with ESMTP id 31D011E0A3B for <netmod@ietf.org>; Tue, 19 Sep 2017 08:20:57 -0600 (MDT)
Received: from box313.bluehost.com ([69.89.31.113]) by cmgw3 with id BSLt1w00q2SSUrH01SLwYl; Tue, 19 Sep 2017 08:20:57 -0600
X-Authority-Analysis: v=2.2 cv=K/VSJ2eI 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=wU2YTnxGAAAA:8 a=AUd_NHdVAAAA:8 a=fp591vAULOXga0goXgIA:9 a=QEXdDO2ut3YA:10 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:From:References:Cc:To:Subject: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=F4fTWPV733Gp4MKjI33ZybzYFiP0k9TOwhrwCUPOsVw=; b=s4haNJBxbC8yX/RwaltWHZxiq7 5T1OAUasfiV0uYEPgA29S1k/2qAre+C5ct5AgbUtAiZbr2aG9FTju3G3Y5XS4LPFxoMV5v/QBDGBb vILvxmyuTBcziiRErojyR6gXj;
Received: from pool-100-15-84-20.washdc.fios.verizon.net ([100.15.84.20]:47876 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 1duJOP-001XO0-BM; Tue, 19 Sep 2017 08:20:53 -0600
To: Martin Bjorklund <mbj@tail-f.com>
Cc: rwilton@cisco.com, netmod@ietf.org
References: <c5352dde-4026-7549-bafa-30b19d7bb789@labn.net> <20170919.132947.358857445863848356.mbj@tail-f.com> <990b8722-7a48-46ce-3f5d-96bc5cb66075@labn.net> <20170919.154238.1738748131929616921.mbj@tail-f.com>
From: Lou Berger <lberger@labn.net>
Message-ID: <d555bb7e-c800-64c6-8272-5e2210028603@labn.net>
Date: Tue, 19 Sep 2017 10:20:51 -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: <20170919.154238.1738748131929616921.mbj@tail-f.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Content-Language: en-US
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: 1duJOP-001XO0-BM
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]:47876
X-Source-Auth: lberger@labn.net
X-Email-Count: 4
X-Source-Cap: bGFibm1vYmk7bGFibm1vYmk7Ym94MzEzLmJsdWVob3N0LmNvbQ==
X-Local-Domain: yes
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/vs2NyWkryPB4ymsZMakxWsbmlTg>
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: Tue, 19 Sep 2017 14:21:11 -0000


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.

Lou

>
>
> /martin