[Teas] Re: Gunter Van de Velde's Discuss on draft-ietf-teas-actn-vn-yang-27: (with DISCUSS)

[Mahesh Jethanandani <[e-mail]>]

Hi Gunter/Dhruv,

Gunter, you are right that the idea of YANG has been to make it a very readable, and therefore understandable language. And this extends to how node names are selected. The section that you quote below goes to the heart of that desire, and has been captured after extensive discussion in the NETMOD WG. If I understand you, there are two issues that you highlighting. The use of acronyms in node names, and the naming of parent vs child nodes.

To the use of acronyms in node names, there is obviously a balance between that and providing descriptive enough names that make the model reading easy, i.e., avoid long XPaths. Generally, if the draft uses an acronym and explains its usage in the draft, it is fair to use it in the YANG model. Towards that end, the compromise that the WG came up with, sounds reasonable to me. However, I do expect the authors to use the description field in the YANG model to carry some of that description from the draft, to help with readability. That is because once the YANG model is separated from the draft, the description in the draft can get lost. Therefore, if the YANG model names a node ‘vn’, I expect the description field to expand it to say “Virtual Network (VN) ...”. Moreover, lot of tools, including OpenAPI generators, use the description field to describe usage, which makes it all the more important to have good descriptions.

The use of parent identifier in the child is a litte more straight forward. There is really no need to. In this case, instead of ‘vn-id’, ‘id’ would have sufficed.

HTH.

> On Jun 7, 2024, at 6:07 AM, Gunter van de Velde (Nokia) <[e-mail]> wrote:
> 
> Hi Dhruv,
>  
> Using container names in leaf names is something that should be avoided. It adds no additional meaning and increases the path length.
>  
> Descriptions clarify what a particular node or statement is intended for, making the model easier to understand for those who read it.
>  
> There is a hint about this specified in:
> https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc6087bis-20#section-4.3.1 <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc6087bis-20#section-4.3.1>
>  
> “
>    Identifiers SHOULD include complete words and/or well-known acronyms
>    or abbreviations.  Child nodes within a container or list SHOULD NOT
>    replicate the parent identifier.  YANG identifiers are hierarchical
>    and are only meant to be unique within the the set of sibling nodes
>    defined in the same module namespace.
>  
>    It is permissible to use common identifiers such as "name" or "id" in
>    data definition statements, especially if these data nodes share a
>    common data type.
> “
>  
> However, I'm uncertain whether the IETF mandates or enforces the use of human-readable names for YANG nodes, or whether there are guidelines to avoid including parent node names in the names of sibling nodes.
>  
> Perhaps @Mahesh Jethanandani <mailto:[e-mail]> (NETMOD AD) could provide some insight on this matter? If this aspect hasn’t been a priority and has not been enforced at the IETF, then I might be overly concerned about the readability and style of YANG. 
>  
> G/
>  
>  
>  
>  
>  
> From: Dhruv Dhody <[e-mail] <mailto:[e-mail]>> 
> Sent: Friday, June 7, 2024 2:09 PM
> To: Gunter van de Velde (Nokia) <[e-mail] <mailto:[e-mail]>>
> Cc: The IESG <[e-mail] <mailto:[e-mail]>>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>
> Subject: Re: Gunter Van de Velde's Discuss on draft-ietf-teas-actn-vn-yang-27: (with DISCUSS)
>  
>  
> CAUTION: This is an external email. Please be very careful when clicking links or opening attachments. See the URL nok.it/ext <http://nok.it/ext> for additional information.
>  
> 
> Hi Gunter,
>  
> On Fri, Jun 7, 2024 at 12:01 PM Gunter van de Velde (Nokia) <[e-mail] <mailto:[e-mail]>> wrote:
> I understand. It is always a compromise. I fight with this myself all the time when suffering yang coding moments.
>  
> In this file i see for example src. Why not use ‘source’? same with other key-words.
>  
>  
> Dhruv: It was kept as 'src' to match it with 'dest'.
> If we change it, we should change to 'source' and 'destination'. And also handle other leaves like multi-src, multi-dest, src-vn-ap-id, dest-vn-ap-id and feature name 'multi-src-dest'.
>  
> Longer names also makes the tree diagram difficult to follow because of the 80 char width (especially with the feature name).
>  
>  
> About your example:
>  
> path "/virtual-network/vn/vn-id"; will become
> path "/virtual-network/virtual-network/virtual-network-identifier";
>  
> I question the fact that it is not required that the virtual-network should be repeated for the “identifier” leaf.
> More user friendly and less long would be:
> path "/virtual-network/virtual-network/identifier";
>  
> Once you are in the node virtual-network, you know you are handling a virtual-network identifier. Why name it double? It makes the path longer for no apparent reason as you correctly observed.
>  
>  
> Dhruv: I agree. If the change is made, following your suggestion would make sense. I was just illustrating my point :)
>  
> I am a little apprehensive in making this late change that will have a huge churn in the document (and the model). The JSON examples would need to be reworked as well as other YANG models that build on the VN model. Could I add text in the description clause in the YANG module that expands these abbreviations instead? 
>  
> But, if you feel strongly about this (and the responsible AD confirms) I will make the requested change.  
>  
> Thanks,
> Dhruv
>  
>  
>  
>  
>  
>  
> G/
>  
>  
> From: Dhruv Dhody <[e-mail] <mailto:[e-mail]>> 
> Sent: Friday, June 7, 2024 12:35 PM
> To: Gunter van de Velde (Nokia) <[e-mail] <mailto:[e-mail]>>
> Cc: The IESG <[e-mail] <mailto:[e-mail]>>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>;[e-mail] <mailto:[e-mail]>
> Subject: Re: Gunter Van de Velde's Discuss on draft-ietf-teas-actn-vn-yang-27: (with DISCUSS)
>  
>  
> CAUTION: This is an external email. Please be very careful when clicking links or opening attachments. See the URL nok.it/ext <http://nok.it/ext> for additional information.
>  
> 
> Hi Gunter,
>  
> Thanks for your review.
>  
> On Fri, Jun 7, 2024 at 10:47 AM Gunter Van de Velde via Datatracker <[e-mail] <mailto:[e-mail]>> wrote:
> Gunter Van de Velde has entered the following ballot position for
> draft-ietf-teas-actn-vn-yang-27: Discuss
> 
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
> 
> 
> Please refer to https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/ <https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/> 
> for more information about how to handle DISCUSS and COMMENT positions.
> 
> 
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-teas-actn-vn-yang/ <https://datatracker.ietf.org/doc/draft-ietf-teas-actn-vn-yang/>
> 
> 
> 
> ----------------------------------------------------------------------
> DISCUSS:
> ----------------------------------------------------------------------
> 
> # Gunter Van de Velde, RTG AD, comments for draft-ietf-teas-actn-vn-yang-27
> 
> Please find https://www.ietf.org/blog/handling-iesg-ballot-positions/ <https://www.ietf.org/blog/handling-iesg-ballot-positions/>
> documenting the handling of ballots.
> 
> Many thanks for the RTG-DIR reviews from Darren Dukes and many thanks to Vishnu
> Pavan Beeram for the Shepherd write-up.
> 
> Please find below 1 blocking DISCUSS about the yang node names used, that seems
> reasonably simple to address
> 
> #DISCUSS items
> #=============
> ##DISCUSS1
> One of the motivations to use YANG is to have human readable structure to
> understand config and state of a device. When looking through the document i
> see many very abbreviated acronymns. e.g. vn, vn-id, src, src-vn-ap.id <http://src-vn-ap.id/>, etc
> 
> If not overly lengthy, why not use node names in the style of source,
> virtual-network, virtual-network-id, etc? There is no real reason to abbreviate
> in the yang model, assuming the node names are not overly long and it makes
> reading and understanding the leafs more trivial.
> 
>  
> Dhruv: The complaint that we get with longer names is that the leafref paths become too long and lose human readability. 
>  
>   +--rw virtual-network
>      +--rw vn* [vn-id]
>         +--rw vn-id                     vn-id
>  
>  
> path "/virtual-network/vn/vn-id"; will become
> path "/virtual-network/virtual-network/virtual-network-identifier";
>  
> The idea of expanding it once as a top container and using VN for leaves inside seems like a good compromise. I would also consider VN to be well-known for anyone dealing with this YANG file. 
>  
> Hope this explains our thinking, does it make sense to you? 
>  
> Thanks,
> Dhruv


Mahesh Jethanandani
[e-mail]