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

["Gunter van de Velde (Nokia)" <[e-mail]>]

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

“
   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]>
Sent: Friday, June 7, 2024 2:09 PM
To: Gunter van de Velde (Nokia) <[e-mail]>
Cc: The IESG <[e-mail]>; [e-mail]; [e-mail]; [e-mail]; [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 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/
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/



----------------------------------------------------------------------
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/
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