Re: [netmod] choice/case in tree diagrams

[Lou Berger <[e-mail]>]

Martin,


On March 6, 2018 4:44:47 AM Martin Bjorklund <[e-mail]> wrote:

> Hi,
>
> After thinking some more about this, realizing that this document is
> in AUTH48, and looking at the first sentence in the Abstract:
>
>    This document captures the current syntax used in YANG module tree
>    diagrams.
>
> I have reached the conclusion that we probably shouldn't make any
> drastic changes.
>

I agree.

> The current syntax, with flags for choice but not for case, may look a
> bit odd, but it does follow RFC 7950 where a choice node can have a
> config property, but case cannot.  Also, this syntax has now been used
> for several years w/o causing much confusion.
>
> I suggest the following changes to this document:
>
> OLD:
>
>        <flags> is one of:
>          rw  for configuration data
>          ro  for non-configuration data, output parameters to rpcs
>              and actions, and notification parameters
>          -w  for input parameters to rpcs and actions
>          -u  for uses of a grouping
>          -x  for rpcs and actions
>          -n  for notifications
>          mp  for nodes containing a "mount-point" extension statement
>
> NEW:
>
>        <flags> is one of:
>          rw  for configuration data
>          ro  for non-configuration data, output parameters to rpcs
>              and actions, and notification parameters
>          -w  for input parameters to rpcs and actions
>          -u  for uses of a grouping
>          -x  for rpcs and actions
>          -n  for notifications
>          mp  for nodes containing a "mount-point" extension statement
>
>          case nodes do not have any <flags>.
>


> Then, since the syntax requires whitespace before <name>:
>
I think we should match current tooling/practice here as well. Can you 
confirm how pyang works today?

My memory is no such space is added.  If my memory is correct, my 
preference is to change the text rather then the tooling.

Lou
(As contributor)

>      <status>--<flags> <name><opts> <type> <if-features>
>
> we need to fix the examples:
>
> OLD:
>
>              +--rw (root-type)
>                 +--:(vrf-root)
>
> NEW:
>
>              +--rw (root-type)
>                 +-- :(vrf-root)
>
> (two occurances)
>
>
>
> /martin
>
>
>
> Vladimir Vassilev <[e-mail]> wrote:
>>
>>
>> On 03/05/2018 06:40 PM, Per Hedeland wrote:
>> > On 2018-03-05 16:06, Ladislav Lhotka wrote:
>> >> On Mon, 2018-03-05 at 15:49 +0100, Per Hedeland wrote:
>> >>> On 2018-03-05 15:41, Ladislav Lhotka wrote:
>> >>>> On Mon, 2018-03-05 at 15:26 +0100, Martin Bjorklund wrote:
>> >>>>> Juergen Schoenwaelder <[e-mail]> wrote:
>> >>>>>> On Mon, Mar 05, 2018 at 02:54:18PM +0100, Martin Bjorklund wrote:
>> >>>>>>>> So it seems the running code got it right. ;-)
>> >>>>>>> As the author of that code, I think that was purely by accident...
>> >>>>>>>
>> >>>>>>> But I'm not convinced it is the correct solution.  We have one example
>> >>>>>>> in the other thread where someone was confused by the "rw" flag and
>> >>>>>>> thought that it implied that the node would be present in the data
>> >>>>>>> tree.
>> >>>>>>>
>> >>>>>> So what does rw mean?
>> >>>>>>
>> >>>>>> (i)  The schema node has a rw property.
>> >>>>>> (ii) The schema node can be instantiated and the instantiated data
>> >>>>>> node
>> >>>>>>       has a rw property.
>> >>>>>>
>> >>>>>> I think it is difficult to have both at the same time. If the tree is
>> >>>>>> a representation of schema nodes, then (i) seems to make more
>> >>>>>> sense. That said, the explanation in 2.6 is somewhat vague since it
>> >>>>>> says 'data' and not 'nodes' (like everywhere else):
>> >>>>>>
>> >>>>>> OLD:
>> >>>>>>
>> >>>>>>         <flags> is one of:
>> >>>>>>           rw  for configuration data
>> >>>>>>           ro  for non-configuration data, output parameters to rpcs
>> >>>>>>               and actions, and notification parameters
>> >>>>>>
>> >>>>>> NEW:
>> >>>>>>
>> >>>>>>         <flags> is one of:
>> >>>>>>           rw  for configuration data nodes
>> >>>>>>           ro for non-configuration data nodes, output parameters to
>> >>>>>>           rpcs
>> >>>>>>               and actions, and notification parameters
>> >>>>> I think this is ok.  But that means that we also have to add:
>> >>>>>
>> >>>>>             --  for a choice or case node
>> >>>>>
>> >>>>> But in order to be consistent, we should probably have:
>> >>>>>
>> >>>>>             --  for a choice, case, input or output node
>> >>>> But unlike the three other statements, "choice" can have the config
>> >>>> substatement, so "rw/ro" makes sense there.
>> >>> I don't think so - that config statement does not a define a property
>> >>> of
>> >>> the choice node (it can obviously neither be read nor written), only a
>> >>> default for descendant data nodes, as described in section 7.21.1 of
>> >>> RFC
>> >>> 7950.
>> >> It is not a default - if a choice has "config false", then no
>> >> descendant can be
>> >> "config true". One of the benefits of having rw/ro in the ascii tree
>> >> is to see
>> >> where a state data subtree actually starts.
>> > It is a default, but yes, it is also a restriction in the specific
>> > case
>> > of the argument being "false" at a point where the default would
>> > otherwise be "true". And in that case it is equivalent to having
>> > "config
>> > false" on all the descendant data nodes, and they will of course be
>> > flagged as "ro" regardless of whether the "config false" comes from
>> > the
>> > choice or the individual data nodes - and that is where the state
>> > *data*
>> > suntree(s) actually start(s).
>> >
>> > So I guess the question then is whether this specific case motivates
>> > always having flags on specifically choice nodes, while the other
>> > non-data nodes have no flags. Since the 'config' statement is ignored
>> > in
>> > rpc/action input/output and notification, choice nodes there should
>> > then
>> > presumably have "-w"/"ro"/"-n". Personally I think the diagram is
>> > clearer with flags only on the data nodes.
>> When I think about it <flags> do not have any information contents 
>> outside of the context of a data tree and its schema. So if we are
>> removing clutter we should probably start there by specifying that
>> <flags> should be ommited under rpc,notification and action.
>>
>> Vladlimir
>> >
>> > --Per
>> >
>> >> Lada
>> >>
>> >>> --Per
>> >>>
>> >>>> Lada
>> >>>>
>> >>>>>
>> >>>>> This means that the correct tree syntax for choice and case will be:
>> >>>>>
>> >>>>>       +-- (subnet)?
>> >>>>>          +-- :(prefix-length)
>> >>>>>          |  +--rw prefix-length?   uint8
>> >>>>>          +-- :(netmask)
>> >>>>>             +--rw netmask?         yang:dotted-quad
>> >>>>>
>> >>>>>
>> >>>>> /martin
>> >>>>>
>> >>>>>
>> >>>>>> The document (as far as I searched for it) does not clearly say that
>> >>>>>> 'node' means 'schema node'. In hindsight, it might have been useful to
>> >>>>>> explicitely import terminology from RFC 7950 and to use it carefully
>> >>>>>> (RFC 7950 has 'schema node' and 'data node' but here we largely talk
>> >>>>>> about 'nodes' - and my assumption is that this means 'schema nodes'.)
>> >>>>> _______________________________________________
>> >>>>> netmod mailing list
>> >>>>> [e-mail]
>> >>>>> https://www.ietf.org/mailman/listinfo/netmod
>> >>> _______________________________________________
>> >>> netmod mailing list
>> >>> [e-mail]
>> >>> https://www.ietf.org/mailman/listinfo/netmod
>> > _______________________________________________
>> > netmod mailing list
>> > [e-mail]
>> > https://www.ietf.org/mailman/listinfo/netmod
>>
>> _______________________________________________
>> netmod mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/netmod
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>