Subject: [netmod] Data model structure notation conventions

From: "Alexander Clemm (alex)" <[email-masked]>
Date: Wed, 13 Jun 2012 18:51:19 -0700

Hi,

I have a question regarding the notation conventions with which the
Internet Drafts provide an overview of the structure of YANG modules.
(Example, section 3 in draft-ietf-netmod-interfaces-cfg-04)  I really
like that aspect of the Drafts a lot as it provides a very simple way to
visualize what is going on and look at the forest, not the trees.  

I notice that "?" is used to indicate that a leaf is optional. What I am
wondering is why it was not instead decided to use "!" to indicate that
a leaf is mandatory.  "Mandatory" was chosen as a substatement/keyword
in YANG, not "optional", presumably because a much larger number of
leaves would turn out to be optional than mandatory and hence a more
compact specification would result.  However, the same is true for the
structure summary, where instead of appending most nodes with a "?",
much fewer nodes could be appended with a "!" (and the connection with
the corresponding YANG keywords would be more direct, not inversely
direct, providing for slightly improved continuity).  

On similar lines, I am wondering whether it was considered to use a
prefix when "config = false", instead of prepending every node with "rw"
or "ro" (the "r" itself looking redundant)?  

Regards

--- Alex

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 14 Jun 2012 09:10:23 +0200

On Jun 14, 2012, at 3:51 AM, Alexander Clemm (alex) wrote:

> Hi,
>  
> I have a question regarding the notation conventions with which the Internet Drafts provide an overview of the structure of YANG modules.  (Example, section 3 in draft-ietf-netmod-interfaces-cfg-04)  I really like that aspect of the Drafts a lot as it provides a very simple way to visualize what is going on and look at the forest, not the trees. 
>  
> I notice that “?” is used to indicate that a leaf is optional. What I am wondering is why it was not instead decided to use “!” to indicate that a leaf is mandatory.  “Mandatory” was chosen as a substatement/keyword in YANG, not “optional”, presumably because a much larger number of leaves would turn out to be optional than mandatory and hence a more compact specification would result.  However, the same is true for the structure summary, where instead of appending most nodes with a “?”, much fewer nodes could be appended with a “!” (and the connection with the corresponding YANG keywords would be more direct, not inversely direct, providing for slightly improved continuity).

I think it is a good point. Also, it might be helpful to indicate nodes that are conditional, i.e. dependent on a 'when' statement. For example, the subtree "routing-tables" in the routing draft looks like this:

+--rw routing-tables
   +--rw routing-table [name]
      +--rw name
      +--rw address-family?
      +--rw safi?
      +--rw description?
      +--ro routes
      |  +--ro route
      |     +--ro source-protocol
      |     +--ro age
      |     +--ro outgoing-interface?
      |     +--ro v4ur:dest-prefix?
      |     +--ro v4ur:next-hop?
      |     +--ro v6ur:dest-prefix?
      |     +--ro v6ur:next-hop?
      …

This gives a false impression that the data model contains sibling nodes with the same local name ("dest-prefix" and "next-hop"), which would of course be a dubious design. But it is not the case because each pair of nodes is only valid for specific values of "address-family" and "safi" (IPv4/IPv6 unicast).

It is however more complicated than "?" (or "!") because entire subtrees might be conditional.
One possibility could be to change "+" into "*" for the root of the conditional subtree and "|" into "I", for example

*-- rw cond-container
I   +-- rw cond-leaf-1
I   +-- rw cond-leaf-2
+-- rw noncond-leaf

Lada

>  
>  
> On similar lines, I am wondering whether it was considered to use a prefix when “config = false”, instead of prepending every node with “rw” or “ro” (the “r” itself looking redundant)? 
>  
> Regards
> --- Alex    
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

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

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 14 Jun 2012 09:58:35 +0200 (CEST)

Hi Alex,

> visualize what is going on and look at the forest, not the trees.  

Glad you like it; I use it all the time when I get (large) data models
to review and also during data model design.

> or "ro" (the "r" itself looking redundant)?  

Good points!  The reson for this is that I really liked the -f tree
output from smidump, so I implemented -f tree in pyang, and I more or
less used the same notation as smidump.  The '?' and '*' was used
simply b/c those are common symbols known to many people (from
regexps), as are rw/ro.

The complete syntax is:

<status> <flags> <name> <opts>   <type>

  <status> is one of:
    +  for current
    x  for deprecated
    o  for obsolete

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

  <name> is the name of the node
    (<name>) means that the node is a choice node
   :(<name>) means that the node is a case node

   If the node is augmented into the tree from another module, its
   name is printed as <prefix>:<name>.

  <opts> is one of:
    ?  for an optional leaf or presence container
    *  for a leaf-list
    [<keys>] for a list's keys

  <type> is the name of the type for leafs and leaf-lists

So this tree output is typically generated using pyang, and then
copied into the documents.

<another-shameless-plug>

  pyang also has support for generating UML, javascript trees, and
  hyperbolic trees from YANG modules.  See
  http://code.google.com/p/pyang/wiki/UMLOutput and
  http://code.google.com/p/pyang/wiki/JSTreeandHyperTree for
  screenshots.

</another-shameless-plusg>

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 14 Jun 2012 10:08:30 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> > I have a question regarding the notation conventions with which the Internet
> > Drafts provide an overview of the structure of YANG modules.  (Example,
> > section 3 in draft-ietf-netmod-interfaces-cfg-04) I really like that aspect
> > of the Drafts a lot as it provides a very simple way to visualize what is
> > going on and look at the forest, not the trees.
> >  
> > I notice that “?” is used to indicate that a leaf is optional. What I am
> > wondering is why it was not instead decided to use “!” to indicate that a
> > leaf is mandatory.  “Mandatory” was chosen as a substatement/keyword in YANG,
> > not “optional”, presumably because a much larger number of leaves would turn
> > out to be optional than mandatory and hence a more compact specification
> > would result.  However, the same is true for the structure summary, where
> > instead of appending most nodes with a “?”, much fewer nodes could be
> > appended with a “!” (and the connection with the corresponding YANG keywords
> > would be more direct, not inversely direct, providing for slightly improved
> > continuity).
> 
> I think it is a good point. Also, it might be helpful to indicate nodes that
> are conditional, i.e. dependent on a 'when' statement. For example, the subtree
> "routing-tables" in the routing draft looks like this:
> 
> +--rw routing-tables
> This gives a false impression that the data model contains sibling nodes with
> the same local name ("dest-prefix" and "next-hop"), which would of course be a
> dubious design. But it is not the case because each pair of nodes is only valid
> for specific values of "address-family" and "safi" (IPv4/IPv6 unicast).
> 

When I implemented the output in pyang I tried some different ideas,
but soon realized that using too many symbols make the diagram
difficult to read.  I would like to be able to give the diagram to
people without too much YANG knowledge, and they should be able to get
the idea.  We have to accept that we cannot capture everything in this
diagram - it gives an informative overview of the structure; for
details you have to go the YANG definitions.

One thing I did add was a weird syntax for choice/case; it is not
obvious it helps...

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 14 Jun 2012 10:28:05 +0200

> details you have to go the YANG definitions.

Yes, it is not easy to find the right compromise. In the routing draft I also removed the datatypes on the right, but that was because some lines exceeded 72 chars.

> obvious it helps…

But it would be really confusing without it.

Lada

---

From: "Alexander Clemm (alex)" <[email-masked]>
Date: Thu, 14 Jun 2012 14:28:53 -0700

Thanks, Martin, for the explanation.  
--- Alex

-----Original Message-----
From: Martin Bjorklund [mailto:[email-masked]] 
Sent: Thursday, June 14, 2012 12:59 AM
To: Alexander Clemm (alex)
Cc: [email-masked]
Subject: Re: [netmod] Data model structure notation conventions

Hi Alex,

The complete syntax is:

  <status> is one of:
    +  for current
    x  for deprecated
    o  for obsolete

  <flags> is one of:

  <opts> is one of:

<another-shameless-plug>

/martin