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

From: Joe Clarke <[email-masked]>
Date: Thu, 14 Sep 2017 11:33:56 -0400

I've been hacking on pyang, and I changed tree.py to add the enum values
for enumeration types and identiyref bases for identityref types.  Here
is an example:

module: yang-catalog
    +--rw catalog
       +--rw modules
       |  +--rw module* [name revision organization]
       |     +--rw name                     yang:yang-identifier
       |     +--rw revision                 union
       |     +--rw organization             string
       |     +--rw ietf
       |     |  +--rw ietf-wg?   string
       |     +--rw namespace                inet:uri
       |     +--rw schema?                  inet:uri
       |     +--rw generated-from?          enumeration [mib, code,
not-applicable, native]
       |     +--rw maturity-level?          enumeration [ratified,
adopted, initial, not-applicable]
...
                               +--rw protocols
                               |  +--rw protocol* [name]
                               |     +--rw name
identityref -> protocol
...

My questions are:

1. Is this useful?

2. If so, can this be added to pyang (happy to submit a PR) and
draft-ietf-netmod-yang-tree-diagrams?

3. What changes to the output format would you recommend?

Thanks.

Joe

---

From: Andy Bierman <[email-masked]>
Date: Thu, 14 Sep 2017 08:43:22 -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.

Andy

On Thu, Sep 14, 2017 at 8:33 AM, Joe Clarke <[email-masked]> wrote:

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Joe Clarke <[email-masked]>
Date: Thu, 14 Sep 2017 11:58:46 -0400

> The current format gets very cluttered and there are too many little symbols

I just went with text for these changes.  Yes, it adds more verbiage to
the output, but it doesn't add any cryptic symbols; plus I think it
makes it easier to comprehend the types.

Joe

> 
> 
> Andy
> 
> 
> On Thu, Sep 14, 2017 at 8:33 AM, Joe Clarke <[email-masked]
> <mailto:[email-masked]>> wrote:
> 
>     [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/netmod>
> 
>

---

From: Balazs Lengyel <[email-masked]>
Date: Thu, 14 Sep 2017 18:13:11 +0200

Did you consider to have a concise and a verbose tree output selected by 
an option?

regards Balazs

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909              email: [email-masked]

---

From: Joe Clarke <[email-masked]>
Date: Thu, 14 Sep 2017 12:32:23 -0400

> Did you consider to have a concise and a verbose tree output selected by

I did.  I wanted to get some broader feedback, but I figured people
would want something like --tree-print-expanded-types or the like.

Joe

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 14 Sep 2017 19:50:37 +0200 (CEST)

> The current format gets very cluttered and there are too many little symbols

I agree with Andy.  I also did some experiments with printing
enumerations, and they work ok for small enums.  But once you have
more than a handful they do tend to clutter the output.  Even worse so
for trees that go into RFCs (where lines need to be < 70 characters).

Lada is sometimes using a format with even less information, where he
has removed all type information, focusing more on the structure.

/martin

---

From: Joe Clarke <[email-masked]>
Date: Thu, 14 Sep 2017 14:03:18 -0400

> for trees that go into RFCs (where lines need to be < 70 characters).

What about protecting this with an optional parameter?  I certainly
appreciate the output could be large, but I think it does have its uses
sometimes.

Joe

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 15 Sep 2017 12:21:40 +0200

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.

I agree.

Lada

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Sep 2017 11:29:29 +0100

>> The current format gets very cluttered and there are too many little symbols
I definitely think that "x" is a bit confusing since it both means "RPC" 
and also "status deprecated" depending on where it is.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 15 Sep 2017 13:40:07 +0200 (CEST)

> >> The current format gets very cluttered and there are too many little

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

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.

Also, what is mounted under a mount point is not defined in the
schema, so a tool cannot generate this from the YANG modules.

So maybe we should remove "/" and "@", and just keep "mp".

> I definitely think that "x" is a bit confusing since it both means
> "RPC" and also "status deprecated" depending on where it is.

Possibly.  "x" for "deprecated" comes from smidump.  "x" for "execute"
(rwx) is of course common.  So if we should change something it is
probably "x" for "deprecated".  But "x" looks better than "d"...

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 15 Sep 2017 13:49:20 +0200

Martin Bjorklund píše v Pá 15. 09. 2017 v 13:40 +0200:
> > >> The current format gets very cluttered and there are too many little
> 
> > >> symbols
> 
> > >> to remember them all.
> 
> > > I agree.
> 
> 

Right, it is yet another example of confusing schema nodes with instances: the
tree diagram is a visualisation of the schema whereas parent references are
about concrete instances. Oh well...

Lada

> > >>> I've been hacking on pyang, and I changed tree.py to add the enum
> 
> > >>> values
> 
> > >>> for enumeration types and identiyref bases for identityref types.
> 
> > >>> Here
> 
> > >>> is an example:
> 
> > >>>
> 
> > >>> module: yang-catalog
> 
> > >>>      +--rw catalog
> 
> > >>>         +--rw modules
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Sep 2017 14:15:52 +0200

> schema, so a tool cannot generate this from the YANG modules.

This sounds broken. Manually edited tree diagrams will be a source of
pain.
 
> probably "x" for "deprecated".  But "x" looks better than "d"...

Yep, I am probably guilty for the deprecated 'x'. For obsolete,
smidump creates an 'o', so you have

        +--- foo
        x--- bar
        o--- baz

and I guess I visually liked it (and there was no execute in SNMP
land). I guess I still kind of like this. If I would start from
scratch for YANG, I would probably not use

       rw  for configuration data
       ro  for non-configuration data
       -x  for rpcs and actions
       -n  for notifications
       mp   for schema mount points

but rather single letters, e.g.

       c  for configuration data
       s  for non-configuration data
       r  for rpcs and actions
       n  for notifications
       m  for schema mount points

but this is a significant change to what we have done so far and
finding agreement on a new notation is likely difficult.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Benoit Claise <[email-masked]>
Date: Fri, 15 Sep 2017 14:54:31 +0200

Hi Joe,
> appreciate the output could be large, but I think it does have its uses
I would agree it has its uses sometimes.
And it helps the broader community with understanding YANG, this is good.
Now, if you are already a YANG expert, I guess you don't use the tree 
output much.

Regards, Benoit (as a contributor)
> .

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 15 Sep 2017 15:01:19 +0200 (CEST)

> Now, if you are already a YANG expert, I guess you don't use the tree

Personally, I use it all the time, it is extremely useful for
understanding the module.  But if it has too much details it becomes
less useful.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Sep 2017 15:21:28 +0200

On Fri, Sep 15, 2017 at 02:54:31PM +0200, Benoit Claise wrote:

> Now, if you are already a YANG expert, I guess you don't use the
> tree output much.

I think this has nothing to do with YANG experience. The intention of
the tree format was to provide a concise overview of the structure of
the schema tree. If we start to include type specifics that can get
very detailed, the diagrams loose their value.

/js

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Sep 2017 14:33:57 +0100

Perhaps "-X" could be used for "execute" instead?

Thanks,
Rob

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Sep 2017 15:41:56 +0200

> Perhaps "-X" could be used for "execute" instead?

A single uppercase letter? Looks ugly to my eyes. This is all very
subjective and perhaps things were easier as long as there was just
a tool. ;-)

/js

---

From: Joe Clarke <[email-masked]>
Date: Fri, 15 Sep 2017 09:50:04 -0400

> very detailed, the diagrams loose their value.

I agree that clutter is bad.  I had the same reservation, but I am also
working with models and sharing information with people where a tree
that has a _bit_ more information would be useful.

I agree that showing this by default will be messy in some cases.  And
maybe this has moved to a question more for you, Martin, in pyang's
GitHub channel.  But if this output were put behind an option, would you
entertain a PR?

Joe

---

From: Robert Wilton <[email-masked]>
Date: Fri, 15 Sep 2017 14:50:58 +0100

> subjective and perhaps things were easier as long as there was just
My rational was that there aren't too many RPCs or Actions defined hence 
changing it would be OK. :-)

I thought about suggesting "X" and "O" for deprecated and obsolete, but 
that would seem to draw attention to those nodes, which is probably the 
reverse of what is wanted.

I guess another alternative could be to leave deprecated and obsolete 
nodes out of the YANG tree output all together ... Personally, I like 
the idea of leaving out obsolete nodes since they are just noise, but 
I'm less sure about leaving out the deprecated nodes.  However, I know 
that Martin has left out the deprecated -state tree in 7223bis to make 
the tree diagram more concise.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 15 Sep 2017 15:55:34 +0200 (CEST)

> GitHub channel.  But if this output were put behind an option, would you

Right, there are two issues here, what do we specify in the draft and
what extensions will tools do.  It seems we agree that we shouldn't
put this into the specification.

(as for pyang, I'll send you a private email)

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 15 Sep 2017 15:55:05 +0200

On Fri, Sep 15, 2017 at 02:50:58PM +0100, Robert Wilton wrote:
> 
> I guess another alternative could be to leave deprecated and obsolete nodes
> out of the YANG tree output all together ... Personally, I like the idea of
> leaving out obsolete nodes since they are just noise, but I'm less sure
> about leaving out the deprecated nodes.  However, I know that Martin has
> left out the deprecated -state tree in 7223bis to make the tree diagram more
> concise.
>

Well, in code, this is just a simple option. ;-)

/js

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Fri, 15 Sep 2017 13:56:22 +0000

+1 - Also it is hard enough to format the tree output to fit in a draft
w/o further annotations (even with —-tree-line-length).
Thanks,
Acee

---

From: "t.petch" <[email-masked]>
Date: Fri, 15 Sep 2017 17:51:09 +0100

----- Original Message -----
From: "Joe Clarke" <[email-masked]>
Sent: Friday, September 15, 2017 2:50 PM

Joe

Less is more.

I agree with Andy, Martin and Lada that it has got too cluttered.

And as for line length, I cannot recall when last I read an I-D that did
not break the rules for RFC.

Tom Petch

---

From: Lou Berger <[email-masked]>
Date: Mon, 18 Sep 2017 11:46:04 -0400

Martin,

Speaking as a contributor:

On 9/15/2017 7:40 AM, Martin Bjorklund wrote:
> 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 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.

> Since a parent
This is just a conditional and we have precedent on how to handle
conditional representation.   

> 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. 
Further more, some mounts are hard to spot.  For example, notice ospf. 
Did you notice that it's a mount? Is it a mount or parent reference? 
With the / and @ both cases are transparent:

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

> schema, so a tool cannot generate this from the YANG modules.

I think this is a limitation in the current schema-mount definition that
perhaps will be revisited to support design time mounts, but
nonetheless  still has value to model any reader and implementor.
...

Lou

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Sep 2017 13:29:47 +0200 (CEST)

Lou Berger <[email-masked]> wrote:
> 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.

> and this is one way to help convey (a) what is expected of server
> implementors and (b) what client implementors should expect.
>
   Hence 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.

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

> Did you notice that it's a mount?

This is actually not correct.  ospf is *not* a mount; it is an augment.

/martin

> Is it a mount or parent reference?

---

From: Lou Berger <[email-masked]>
Date: Tue, 19 Sep 2017 09:28:20 -0400

> with an instantiated /schema-mounts tree.
using what syntax?  JSON and XML really isn't that easy for the (human)
reader to parse.

> authors.  Mixing schema and instance data does not help here.

Can you propose an alternative?  The routing WG participants seem to
find these useful, we can also ask there for broader input if you'd like.

> This is actually not correct.  ospf is *not* a mount; it is an augment.
it's a mounted module that augments another mounted module.

Lou

---

From: Robert Wilton <[email-masked]>
Date: Tue, 19 Sep 2017 14:39:16 +0100

> using what syntax?  JSON and XML really isn't that easy for the (human)
Perhaps there needs to be multiple versions of the generated tree output?

1) A normative tree diagram that shows the structure of the model.
2) A subsequent example that demonstrates what it looks like with the 
schema mounted modules.  Within the confines of a text document, the 
tree format still seems like a reasonable way to illustrate this, and I 
would say it is preferable to the verbosity of JSON or XML.

I note that RFC 8022 includes an overview tree model in section 4 with 
some branches pruned, and then the complete representation in an 
appendix, which seems like a pragmatic approach.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Sep 2017 15:42:38 +0200 (CEST)

> using what syntax?  JSON and XML really isn't that easy for the (human)

Either JSON or XML.

> 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

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.

> 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

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Sep 2017 15:47:28 +0200 (CEST)

Robert Wilton <[email-masked]> wrote:
> tree format still seems like a reasonable way to illustrate this, and
> I would say it is preferable to the verbosity of JSON or XML.
> 

Sure, but the question is about what special symbols we define.  Do we
need the extra symbols "/" and "@", and do we agree on what they mean?

/martin

---

From: Robert Wilton <[email-masked]>
Date: Tue, 19 Sep 2017 14:55:19 +0100

> need the extra symbols "/" and "@", and do we agree on what they mean?
If we agree that tree style output is OK to illustrate the use of schema 
mount, then I think that draft-ietf-netmod-yang-tree-diagrams could 
define them, but indicate that they are only used to illustrate how 
schema mount is used, and would not be seen in a regular YANG tree 
diagram illustrating the structure of a YANG module.  The alternative 
might be that the RFCs that uses them defines what '/' and '@' mean for 
that specific example.

As for what the precise definition of '/' and '@' should be, I'm not 
sure.  I think that you and Lou have a better handle on that ;-)

Thanks,
Rob

---

From: Lou Berger <[email-masked]>
Date: Tue, 19 Sep 2017 10:20:51 -0400

>> using what syntax?  JSON and XML really isn't that easy for the (human)
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. 

> have said that they prefer a less cluttered format.
In the context of listing enums...

> 'control-plan-protocol' doesn't have the "/"?  What addition info does
That it is a (sub)tree that is present due to a mounted module.

Lou

---

From: Lou Berger <[email-masked]>
Date: Tue, 19 Sep 2017 10:22:16 -0400

On 9/19/2017 9:55 AM, Robert Wilton wrote:
> diagram illustrating the structure of a YANG module.  

This seems like a reasonable compromise to me, and not a major change to
the draft.

Martin, what do you think?

Lou

> The alternative

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 19 Sep 2017 17:20:55 +0200

[...]

I prefer that the (schema) tree format is restricted to show the
schema tree.

If a tree format is also needed for data trees, then this really is a
different tree format. It may use a similar base notation but what it
shows is fundamentally different.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 20 Sep 2017 08:34:39 +0200 (CEST)

> 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

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 20 Sep 2017 08:40:16 +0200 (CEST)

> Martin, what do you think?

This is not a compromise.  Either the tree document defines the
symbols or it doesn't.  The draft already says:

  Module trees may be included in a document as a whole, by one or
  more sections, or even subsets of nodes.

and

  At times when the composition of the nodes within a module schema
  are not important in the context of the presented tree, peer nodes
  and their children can be collapsed using the notation '...' in
  place of the text lines used to represent the summarized nodes.

so the usage in 8022 is already covered.

> > sure.  I think that you and Lou have a better handle on that ;-)

Since Lou and I have different opinions on this, it would be very
useful to hear what others think.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 20 Sep 2017 09:00:19 +0200

> shows is fundamentally different.

+1

Lada

---

From: "t.petch" <[email-masked]>
Date: Wed, 20 Sep 2017 11:09:07 +0100

----- Original Message -----
From: "Martin Bjorklund" <[email-masked]>
Sent: Tuesday, September 19, 2017 2:42 PM

> have said that they prefer a less cluttered format.

A union is what might be termed the OSI approach to design, an approach
that led to ... well, ISIS and that's about it.

draft-ietf-isis-yang-isis-cfg-18 has some 10 pages of tree structure
which are of little help to me in understanding the module.

With draft-ietf-teas-yang-te-topo-12, the tree structure
runs to over 35 pages and then I think that the tree structure has
failed.

Adding more symbols will not help.

Less is More.

Tom Petch

> > >>> reference can be very specific, e.g. one specific interface, it
isn't
<snip>

---

From: Lou Berger <[email-masked]>
Date: Wed, 20 Sep 2017 07:35:01 -0400

> So is 'control-plane-protocol', so then it should also have '/',

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

Lou

---

From: Lou Berger <[email-masked]>
Date: Wed, 20 Sep 2017 07:46:42 -0400

> useful to hear what others think.

I completely agree that hearing from the WG makes sense (I can also take
this to the users in the RTG WG and see if there is any input from that
WG). 

Obviously, if there's no consensus for these symbols at this time,
they're dropped!

Thanks ,
Lou
(as contributor)

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Mon, 25 Sep 2017 16:30:03 +0000

Martin, Lada, et al,

While I don’t think we need additional annotations that Joe had prototyped
(at least not as the default), I strongly believe we need to keep the ‘@‘
and ‘/‘ in the tree output for schema mount. While the former enhancement
provided details, the schema mount tree designations are every bit as
important as knowing, for example, whether or not a schema leaf is a
presence node. 

Thanks,
Acee

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 25 Sep 2017 19:39:03 +0200 (CEST)

"Acee Lindem (acee)" <[email-masked]> wrote:
> and ‘/‘ in the tree output for schema mount.

Can you explain what information "/" gives the reader?  Compare these
two trees:

  +--mp vrf-root
     +--rw rt:routing/
        +--rw rt:router-id

and

  +--mp vrf-root
     +--rw rt:routing
        +--rw rt:router-id

What did the "/" in the first tree tell me that I don't see in the
second tree?

Then consider:

  +--ro if:interfaces@

and

  +--ro if:interfaces
     +-- if:interface@

and

  +--ro if:interfaces@
     +-- if:interface@

Which ones are legal, and what do they mean?

/martin

While the former enhancement

---

From: "Xufeng Liu" <[email-masked]>
Date: Mon, 25 Sep 2017 22:56:54 -0400

To a user of the schema-mount, it is important to be able to visualize all key elements of the mounting mechanism: mount-point, mounted schema module, and parent-reference. The details can be worked out, but if any of these elements were not useful in the presentation, it would be questionable whether it had well-specified in the schema mount draft.

> -----Original Message-----
> From: netmod [mailto:[email-masked]] On Behalf Of Martin
> Bjorklund
> Sent: Monday, September 25, 2017 1:39 PM
> To: [email-masked]
> Cc: [email-masked]
> Subject: Re: [netmod] Proposal to enhance the YANG tree output
> 
> > While I don’t think we need additional annotations that Joe had
> > prototyped (at least not as the default), I strongly believe we need
> > to keep the ‘@‘ and ‘/‘ in the tree output for schema mount.
> 
> Can you explain what information "/" gives the reader?  Compare these two
> trees:
> 
>   +--mp vrf-root
>      +--rw rt:routing/
>         +--rw rt:router-id
> 
> and
> 
>   +--mp vrf-root
>      +--rw rt:routing
>         +--rw rt:router-id
> 
> What did the "/" in the first tree tell me that I don't see in the second tree?

[Xufeng] Because the schema mount draft allows an augmenting module not to be listed in the mounted schema list. The following two examples show two different configurations:

  +--mp root
     +--rw rt:routing/

where ospf augments rt, and has been listed in the mounting schema list.

  +--mp root
     +--rw rt:routing/

where ospf augments rt, and has not been listed in the mounting schema list.

> Which ones are legal, and what do they mean?
[Xufeng] The display shows the result of the XPath, right? Whether they are legal or not should be determined by the schema-mount draft, not by the displaying notation.

> > >+1 - Also it is hard enough to format the tree output to fit in a
> > >+draft
> > >>> The current format gets very cluttered and there are too many
> > >>>little symbols  to remember them all.
> > >>
> > >>I agree.
> > >>
> > >>Lada
> > >>
> > >>>
> > >>>
> > >>> Andy
> > >>>
> > >>>
> > >>> > adopted, initial, not-applicable] ...
> > >>> >                                +--rw protocols
> > >>> >                                |  +--rw protocol* [name]
> > >>> >                                |     +--rw name
> > >>> > identityref -> protocol
> > >>> > ...
> > >>> >
> > >>> > My questions are:
> > >>> >
> > >>> > 1. Is this useful?
> > >>> >

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 26 Sep 2017 08:36:42 +0200 (CEST)

"Xufeng Liu" <[email-masked]> wrote:
> To a user of the schema-mount, it is important to be able to visualize
> all key elements of the mounting mechanism: mount-point, mounted
> schema module, and parent-reference. The details can be worked out,
> but if any of these elements were not useful in the presentation, it
> would be questionable whether it had well-specified in the schema
> mount draft.

We agreed that we probably don't want to list all enums in the tree.
Does that imply that enumerations are not well-specified in YANG?

> > two
> [Xufeng] Because the schema mount draft allows an augmenting module
> not to be listed in the mounted schema list. The following two
> examples show two different configurations:
> 
>   +--mp root
>      +--rw rt:routing/

If the ospf module is NOT listed in the yang library data for the
mount point, then it will not be present in the tree.  So in this case
the tree will be:

   +--mp root
      +--rw rt:routing
             // no ospf here

[Think about it the other way around; if we were to show all nodes
from all modules that are NOT mounted, our tree would be inifinitely
big...]

If the ospf module *is* listed in the yang library data for the
mount point, then the tree can be:

   +--mp root
      +--rw rt:routing

No need for a '/'.

> [Xufeng] The display shows the result of the XPath, right?

I don't know what it shows; I'm not proposing this notation.  Also
note that the result of the XPath is a node set of *instance data*,
but the tree shows the *schema*, and mixing the two is confusing.

Hopefully by looking at the trees above, the reader will understand
what's behind this notation.  So I ask again, what do the notations
above mean?

> Whether
> they are legal or not should be determined by the schema-mount draft,
> not by the displaying notation.

The schema mount draft does not specify the rules for the '@' in the
tree output.

--

My points are that:

  (1)  "/" is redundant and not needed.  The same information can be
       conveyed w/o "/".

  (2)  "@" is under specified, and it mixes schema and instance data.

/martin

---

From: Yingzhen Qu <[email-masked]>
Date: Tue, 26 Sep 2017 17:28:24 +0000

Hi all,

I personally like to keep the ‘@’ and the '/' in the tree output. As we know that a tree may not catch all what a module is trying to do, but it can help users to quickly get an idea of the module's overall architecture etc. The '@' and the '/' is very helpful in order to understand all the mounting points.

Thanks,
Yingzhen

-----Original Message-----
From: netmod [mailto:[email-masked]] On Behalf Of Acee Lindem (acee)
Sent: Monday, September 25, 2017 9:30 AM
To: Ladislav Lhotka <[email-masked]>; [email-masked]; Martin Bjorklund <[email-masked]>
Subject: Re: [netmod] Proposal to enhance the YANG tree output

Martin, Lada, et al,

While I don’t think we need additional annotations that Joe had prototyped (at least not as the default), I strongly believe we need to keep the ‘@‘ and ‘/‘ in the tree output for schema mount. While the former enhancement provided details, the schema mount tree designations are every bit as important as knowing, for example, whether or not a schema leaf is a presence node. 

Thanks,
Acee 

On 9/15/17, 9:56 AM, "Acee Lindem (acee)" <[email-masked]> wrote:

>>>symbols  to remember them all.
>>
>>I agree.
>>
>>Lada
>>
>>> 
>>> 
>>> Andy
>>> 
>>>

---

From: "Xufeng Liu" <[email-masked]>
Date: Wed, 27 Sep 2017 09:31:01 -0400

> From: Martin Bjorklund [mailto:[email-masked]]
> Sent: Tuesday, September 26, 2017 2:37 AM
> To: [email-masked]
> Cc: [email-masked]; [email-masked]
> > > > prototyped (at least not as the default), I strongly believe we
> > > > need to keep the ‘@‘ and ‘/‘ in the tree output for schema mount.
> > >
> If the ospf module is NOT listed in the yang library data for the mount point,

[Xufeng] I think that draft-ietf-netmod-schema-mount has the distinction between yang library data and schema-mounts/schema list. Do you mean the latter?

> then it will not be present in the tree.  So in this case the tree will be:
> 
>    +--mp root
>       +--rw rt:routing
> [Think about it the other way around; if we were to show all nodes from all
> modules that are NOT mounted, our tree would be inifinitely big...]
> 
> If the ospf module *is* listed in the yang library data for the mount point, then
> the tree can be:
> 
>    +--mp root
>       +--rw rt:routing
[Xufeng] What if the user does want to see all nodes in the system, whether they are mounted or un-mounted, is it possible?

Also, there is another case: I think that draft-ietf-netmod-schema-mount does not prohibit the mount-point container from containing other sub-containers. How can we tell these sub-containers are not from mounted modules?

   +--mp root
      +--rw rt:routing
      |  +--rw router-id?                 yang:dotted-quad
      |  +--rw control-plane-protocols
      |     +--rw control-plane-protocol* [type name]
      |        +--rw ospf:ospf
      +--rw other:other-container  // augmented by module "other"
      |  +--rw other-leaf?                 int32

> I don't know what it shows; I'm not proposing this notation.  Also note that the
> result of the XPath is a node set of *instance data*, but the tree shows the
> *schema*, and mixing the two is confusing.
> 
> Hopefully by looking at the trees above, the reader will understand what's
> behind this notation.  So I ask again, what do the notations above mean?
> 
> > Whether
> The schema mount draft does not specify the rules for the '@' in the tree output.
> 
> --
> 
> My points are that:
> 
[Xufeng] I agree that we should have "@" fully specified, but I'd hope that it won't get dropped so that there won't be a convenient way to tell whether a node is a parent-reference or not.

Thanks,
- Xufeng

> > > > provided details, the schema mount tree designations are every bit
> > > > as important as knowing, for example, whether or not a schema leaf
> > > > is a presence node.
> > > >
> > > > Thanks,
> > > > Acee
> > > >
> > > >
> > > > >>> > 2. If so, can this be added to pyang (happy to submit a PR)
> > > > >>> > and draft-ietf-netmod-yang-tree-diagrams?
> > > > >>> >