Subject: [netmod] tree diagrams - flags

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 21 Mar 2017 11:25:33 +0100

Hi,

if we want to standardize tree diagrams, we may want to take a more
critical look at them, in particular the flags (that were created
ad-hoc and in resemblance to MIB tree diagrams). pyang --tree-help
says:

  <flags> is one of:
    rw  for configuration data
    ro  for non-configuration data
    -x  for rpcs and actions
    -n  for notifications

This is (a) incomlete and (b) somewhat confusing since ct does not
equate to readwrite. I am attaching a sample yang file and here is the
output pyang 1.7.1 produces:

module: tree-sample
    +--rw config-true-container
    |  +--rw param?   string
    +--ro config-false-container
    |  +--ro value?   string
    +--rw inline-action
    |  +---x action
    |     +---- oops?     string
    |     +---w input
    |     |  +---w in?   string
    |     +--ro output
    |        +--ro out?   string
    +--rw inline-notification
       +---n notification
          +---- duration?   string

  rpcs:
    +---x rpc
       +---w input
       |  +---w in?   string
       +--ro output
       |  +--ro out?   string
       +--ro oops?     string

  notifications:
    +---n notification
       +--ro boom?   string

I think a better usage of two letter flags would have been this (since
it more naturally aligns with what the YANG definition says):

  <flags> is one of:
    ct  for configuration data
    cf  for non-configuration data
    x-  for rpcs and actions
    xi  for rpc or action input
    xo  for rpc or action output
    n-  for notifications
    nt  for notification tree (this is I think the term 7950 uses)

module: tree-sample
    +--ct config-true-container
    |  +--ct param?   string
    +--cf config-false-container
    |  +--cf value?   string
    +--ct inline-action
    |  +--x- action
    |     +--xi input
    |     |  +--xi in?   string
    |     +--xo output
    |        +--xo out?   string
    +--ct inline-notification
       +--n- notification
          +--nt duration?   string

  rpcs:
    +--x- rpc
       +--xi input
       |  +--xi in?   string
       +--ro output
          +--xo out?   string

  notifications:
    +--n- notification
       +--nt boom?   string

(And I think the oops leafs should have triggered an error.)

/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: Martin Bjorklund <[email-masked]>
Date: Tue, 21 Mar 2017 11:36:29 +0100 (CET)

>     nt  for notification tree (this is I think the term 7950 uses)

I'm fine with this, but perhaps use "no" for notification data - "t"
means "true" in "ct".

Also, in a grouping like this:

 grouping my-grouping {
    leaf param { type string; }
  }

pyang prints this as:

  my-grouping
      +---- param?   string

i.e., w/o any flags.

> (And I think the oops leafs should have triggered an error.)

They did.  To stderr.

/martin

---

From: Thomas Morin <[email-masked]>
Date: Tue, 21 Mar 2017 11:41:22 +0100

Hi Juergen,

(Just glancing through the list, and by chance reading this particular 
email)

>      cf  for non-configuration data

I think using "cf" to mean "non-configuration" is likely to end up being 
misleading, because "cf" is in other contexts sometimes used as a 
shorthand for "configuration".

-Thomas

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 21 Mar 2017 11:49:30 +0100

> On 21 Mar 2017, at 11:25, Juergen Schoenwaelder <[email-masked]> wrote:
> 
> Hi,
> 

Inside notifications and operations, "cf" carries no information and just clutters the output. My suggestion is to use "ct" or just "c" for config=true data and nothing elsewhere.

Lada

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

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 21 Mar 2017 12:32:46 +0100

> I'm fine with this, but perhaps use "no" for notification data - "t"

I once had nd (notification data) but then in the last moment moved
to nt since 7950 uses the term notification tree...
 
>     leaf param { type string; }

This makes sense, it just needs to get documented...

> > (And I think the oops leafs should have triggered an error.)

Oops, my fault.

/js

---

From: Robert Wilton <[email-masked]>
Date: Tue, 21 Mar 2017 11:50:49 +0000

> Inside notifications and operations, "cf" carries no information and just clutters the output. My suggestion is to use "ct" or just "c" for config=true data and nothing elsewhere.
Do, we also actually need the 'xi', 'xo', or 'nt' at all?  Would these 
be obvious from the paths anyway?

I think that having less symbols on the diagram may make it easier to 
parse, and perhaps less likely for the lines to wrap.

So I am suggesting perhaps just having:

  <flags> is one of:
    c  for configuration data
    x  for rpcs and actions
    n  for notifications

module: tree-sample
    +--c config-true-container
    |  +--c param?   string
    +--- config-false-container
    |  +-- value?   string
    +--c inline-action
    |  +--x- action
    |     +--x input
    |     |  +--x in?   string
    |     +--x output
    |        +--x out?   string
    +--c inline-notification
       +--n notification
          +--n duration?   string

etc.

Rob

> _______________________________________________
> netmod mailing list
> [email-masked]
> .

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 21 Mar 2017 13:01:58 +0100

> On 21 Mar 2017, at 12:50, Robert Wilton <[email-masked]> wrote:
> 
> 
> 
> Do, we also actually need the 'xi', 'xo', or 'nt' at all?  Would these be obvious from the paths anyway?

Yes, "input" and "output" tells everything.

> 
> I think that having less symbols on the diagram may make it easier to parse, and perhaps less likely for the lines to wrap.

+1

>   +--- config-false-container

I think the "x" and "n" is only needed next to the name of rpc/action/notification. So my version would be:

<flags> is one of:
  c  for configuration data
  x  for rpcs and actions
  n  for notifications

module: tree-sample
  |  +--- value?   string
  +--c inline-action
  |  +--x action
  |     +--- input
  |     |  +--- in?   string
  |     +--- output
  |        +--- out?   string
  +--c inline-notification
     +--n notification
        +--- duration?   string

Lada

---

From: [email-masked] (Dale R. Worley)
Date: Tue, 21 Mar 2017 09:22:07 -0400

>   +--- config-false-container

Naively, it seems to me that "c" for configuration and "s" for state
makes a great deal of sense.  ("cf" for state ("config=false") is
hazardous as "cf" is a natural contraction of "configuration".)
config/state is a somewhat messy distinction as the transition between
them can happen anywhere in the tree.

For RPCs, actions, and notifications, using a flag only for their top
nodes makes sense, because that makes it easy to find their top nodes,
and any node under them can only be assessed based on where it is
relative to the top node.

One thing that threw me the first time I saw it is marking lists with
"*".  That doesn't match the generic use of "*", which is to mark the
thing that is repeated.  (Compare using "?" to mark an optional thing,
which does match the generic usage.)  But in the context of Yang, you
don't want to flag the items in the list with "*", that would make the
tree harder to read.

I support having a rigid and consistent standard for indentation and
where the descending lines are placed under the parent nodes --
consistency in formatting allows one to train one's eye to parse the
diagram reflexively rather than having to pause and mentally group the
items into a structure.

Dale

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 21 Mar 2017 14:43:53 +0100 (CET)

[email-masked] (Dale R. Worley) wrote:
> thing that is repeated.

Hmm, "*" was choosen b/c people are used to read it as
"zero or more".  So for example:

     +---c server* [name]
         +--c name          string
         ...

means zero or more "server" elements.  Each indexed by "name".

> (Compare using "?" to mark an optional thing,

What is an "item in the list"?

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 21 Mar 2017 15:11:23 +0100

>   +--- config-false-container

Single character flags work for me as well. Since I have modules with
pretty complex RPC inputs (more than a single page in RFC formatting),
I think it is useful to be able to see that one is still starting at
an RPC input tree and not a regular data tree or a notification tree.
So I tend to like Rob's proposal a bit more.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 21 Mar 2017 16:55:18 +0100

> On 21 Mar 2017, at 15:11, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Even with long RPC parameter lists the indentation should make it obvious what belongs where. Another option might be to label every input parameter with "xi" or "i" and output with "xo"/"o", and remove the "input" and "output" nodes. This would make the output shorter and narrower.

> So I tend to like Rob's proposal a bit more.

Note however that Rob's proposal doesn't distinguish input and output parameters, all are labelled with "x".

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 21 Mar 2017 17:28:22 +0100

> Even with long RPC parameter lists the indentation should make it obvious what belongs where. Another option might be to label every input parameter with "xi" or "i" and output with "xo"/"o", and r…

I wrote multiple pages - indentation is difficult to follow over page
boundaries.

> Note however that Rob's proposal doesn't distinguish input and output parameters, all are labelled with "x".

I know. At least I know I am still in an rpc/action definition. But
yes, some of this may be personal preference.

/js

---

From: Phil Shafer <[email-masked]>
Date: Tue, 21 Mar 2017 15:57:46 -0400

>    ro  for non-configuration data

Given that these are really "config true" and "config false" and
that ephemeral data may well be writable and "config false", should
we change the names?  Writable read-only data would be a mistake.
"ct" and "cf"?  "c" and "-"?

Thanks,
 Phil

---

From: [email-masked] (Dale R. Worley)
Date: Tue, 21 Mar 2017 16:02:47 -0400

>From RFC 7223:

   module ietf-interfaces {
     ...
     container interfaces {
       ...
       list interface {
         key "name";

         leaf name {
           type string;
         }

         leaf description {
           type string;
         }
   ...

There is a top-level container node "interfaces", which contains a list
node "interface", which contains a sequence of list elements which
consist of groups of (a leaf "name", a leaf "description", etc.), which
elements are indexed by the value of the "name" leaf.

Dale

---

From: Phil Shafer <[email-masked]>
Date: Tue, 21 Mar 2017 16:03:41 -0400

>Juergen Schoenwaelder writes:

Apologies.  My brain's still in "low".....

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 21 Mar 2017 21:22:54 +0100 (CET)

> elements are indexed by the value of the "name" leaf.

Aha, ok.  This description is not a correct description of the YANG
data tree (in which XPath expressions etc are evaluated).  There is
not a single "list node" called "interfaces".  Look at an example of
an XML instance document:

  <interfaces>
    <interface>
      <name>eth0</name>
      ...
    </interface>
    <interface>
      <name>eth1</name>
      ...
    </interface>
  </interfaces>

This also reflects the data tree.

/martin

---

From: [email-masked] (Dale R. Worley)
Date: Thu, 23 Mar 2017 21:04:35 -0400

> not a single "list node" called "interfaces".  Look at an example of
                                  ^ I'm pretty sure you mean "interface" here.
> This also reflects the data tree.

OK, yes, I'm recalling that now.  I run into mental interference because
there are at least three ways of looking at it:

- The Yang statement is named "list" -- a singular noun -- and not
something like "repeated" or "repeated container".  And compared to
ordinary programming languages, the semantics is "array-of-structures".
(The fact that Yang doesn't orthogonalize the array and the structure is
why Yang must also have a leaf-list statement.)  So the "obvious"
semantics of the name is that it's "the name" of "the list".

- The XML version doesn't have an overt representation of the array, but
does have an overt representation of each structure and uses the list
name as the label of each structure.  The XPath expressions are
evaluated within this version, so the absence of an explicit array node
is important.

- The JSON representation overtly represents both the array ([...]) and
the structures ({...}), and applies the name to the array, not the
structures.  (Which means that you can't evaluate XPath expressions
directly against the JSON representation.)

Thus you get the contrasting representations:

   list bar {
     key foo;
     leaf foo {
       type uint8;
     }
     leaf baz {
       type string;
     }
   }

   <bar>
     <foo>123</foo>
     <baz>zig</baz>
   </bar>
   <bar>
     <baz>zag</baz>
     <foo>o</foo>
   </bar>

   "bar": [
     {
       "foo": 123,
       "baz": "zig"
     },
     {
       "baz": "zag",
       "foo": 0
     }
   ]

each of which invites one to speak of the schema in somewhat different
ways.

The way you'd describe a tree diagram differs depending on which way
you're looking at the schema.

Dale