Subject: Re: [netmod] Data model structure notation conventions

From: Xiang Li <[email-masked]>
Date: Wed, 15 Aug 2012 18:43:35 -0500

Hi,

These notation conventions are concise and work great but I think it may 
not be clear to someone who does not need to use pyang, but just need to 
read YANG modules.

I think these notation need to be explained somewhere. Perhaps in the 
core system module? Then all other modules such as interface, routing 
etc.  can simply refer to the definition there? Without this piece of 
information documented somewhere I don't think these draft yang module 
documents can be considered "complete".

--Xiang Li

On 6/14/2012 4:28 PM, Alexander Clemm (alex) wrote:
> 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,
>
> "Alexander Clemm (alex)" <[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.
> Glad you like it; I use it all the time when I get (large) data models
> to review and also during data model design.
>
>> 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)?
> 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
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
--Xiang Li
Web: www.seguesoft.com
Voice: 1 (872) 216-2610
Mobile: 1 (217) 472-4108