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

[Lou Berger <[e-mail]>]

On 9/19/2017 9:42 AM, Martin Bjorklund wrote:
> Lou Berger <[e-mail]> wrote:
>>
>> On 9/19/2017 7:29 AM, Martin Bjorklund wrote:
>>> Lou Berger <[e-mail]> wrote:
>>>> Martin,
>>>>
>>>> Speaking as a contributor:
>>>>
>>>>
>>>> On 9/15/2017 7:40 AM, Martin Bjorklund wrote:
>>>>> Robert Wilton <[e-mail]> 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