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

Martin Bjorklund <mbj@tail-f.com> Tue, 19 September 2017 13:44 UTC

Return-Path: <mbj@tail-f.com>
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 75DDA132EC4 for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 06:44:13 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, 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 1bls05HvFFjO for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 06:44:11 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 46DB213292E for <netmod@ietf.org>; Tue, 19 Sep 2017 06:44:11 -0700 (PDT)
Received: from localhost (unknown [173.38.220.41]) by mail.tail-f.com (Postfix) with ESMTPSA id 1399F1AE02A7; Tue, 19 Sep 2017 15:44:10 +0200 (CEST)
Date: Tue, 19 Sep 2017 15:42:38 +0200
Message-Id: <20170919.154238.1738748131929616921.mbj@tail-f.com>
To: lberger@labn.net
Cc: rwilton@cisco.com, netmod@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <990b8722-7a48-46ce-3f5d-96bc5cb66075@labn.net>
References: <c5352dde-4026-7549-bafa-30b19d7bb789@labn.net> <20170919.132947.358857445863848356.mbj@tail-f.com> <990b8722-7a48-46ce-3f5d-96bc5cb66075@labn.net>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset="utf-8"
Content-Transfer-Encoding: base64
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/WkJa5t9ilFiq9ZIrRnE5XNbmUoI>
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 13:44:13 -0000

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.

> >> 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.

> >>> 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?


/martin