Re: [netmod] Proposal to enhance the YANG tree output
Martin Bjorklund <mbj@tail-f.com> Wed, 20 September 2017 06:33 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 DD0F1132F2C for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 23:33:11 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.901
X-Spam-Level:
X-Spam-Status: No, score=-1.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-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 H2K9M876I0Ui for <netmod@ietfa.amsl.com>; Tue, 19 Sep 2017 23:33:10 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id D65B71326ED for <netmod@ietf.org>; Tue, 19 Sep 2017 23:33:09 -0700 (PDT)
Received: from localhost (h-40-225.A165.priv.bahnhof.se [94.254.40.225]) by mail.tail-f.com (Postfix) with ESMTPSA id 0DEA01AE0383; Wed, 20 Sep 2017 08:33:08 +0200 (CEST)
Date: Wed, 20 Sep 2017 08:34:39 +0200
Message-Id: <20170920.083439.2133568542308133041.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: <d555bb7e-c800-64c6-8272-5e2210028603@labn.net>
References: <990b8722-7a48-46ce-3f5d-96bc5cb66075@labn.net> <20170919.154238.1738748131929616921.mbj@tail-f.com> <d555bb7e-c800-64c6-8272-5e2210028603@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/f_CuR09E46grCy8u6xk_qlRjrjM>
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 06:33:12 -0000
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? /martin
- Re: [netmod] Proposal to enhance the YANG tree ou… Xufeng Liu
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- [netmod] Proposal to enhance the YANG tree output Joe Clarke
- Re: [netmod] Proposal to enhance the YANG tree ou… Andy Bierman
- Re: [netmod] Proposal to enhance the YANG tree ou… Joe Clarke
- Re: [netmod] Proposal to enhance the YANG tree ou… Balazs Lengyel
- Re: [netmod] Proposal to enhance the YANG tree ou… Joe Clarke
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Joe Clarke
- Re: [netmod] Proposal to enhance the YANG tree ou… Ladislav Lhotka
- Re: [netmod] Proposal to enhance the YANG tree ou… Robert Wilton
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Ladislav Lhotka
- Re: [netmod] Proposal to enhance the YANG tree ou… Juergen Schoenwaelder
- Re: [netmod] Proposal to enhance the YANG tree ou… Benoit Claise
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Juergen Schoenwaelder
- Re: [netmod] Proposal to enhance the YANG tree ou… Robert Wilton
- Re: [netmod] Proposal to enhance the YANG tree ou… Juergen Schoenwaelder
- Re: [netmod] Proposal to enhance the YANG tree ou… Joe Clarke
- Re: [netmod] Proposal to enhance the YANG tree ou… Robert Wilton
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Juergen Schoenwaelder
- Re: [netmod] Proposal to enhance the YANG tree ou… Acee Lindem (acee)
- Re: [netmod] Proposal to enhance the YANG tree ou… t.petch
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Robert Wilton
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Robert Wilton
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Juergen Schoenwaelder
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Ladislav Lhotka
- Re: [netmod] Proposal to enhance the YANG tree ou… t.petch
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Lou Berger
- Re: [netmod] Proposal to enhance the YANG tree ou… Yingzhen Qu
- Re: [netmod] Proposal to enhance the YANG tree ou… Acee Lindem (acee)
- Re: [netmod] Proposal to enhance the YANG tree ou… Martin Bjorklund
- Re: [netmod] Proposal to enhance the YANG tree ou… Xufeng Liu