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

[Dhruv Dhody <[e-mail]>]

Thanks Mahesh, Gunter,

I have made an update to the YANG.

- I updated the module description to include the abbreviations
- Changed the following leaf names of child nodes
          - vn-id to id
          - ap-id to id

- vn-ap-id to id

- vnm-id to id

- src to ap

- src-vn-ap-id to vn-ap-id

- dest to ap

- dest-vn-ap-id to vn-ap-id


Please check the update. I will update the tree, json, and text to upload a
new revision once you are satisfied.

Thanks,
Dhruv



On Fri, Jun 7, 2024 at 7:30 PM Mahesh Jethanandani <[e-mail]>
wrote:

> 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
>
> “
>    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 <[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]> 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]>
> *Sent:* Friday, June 7, 2024 12:35 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,
>
> Thanks for your review.
>
> On Fri, Jun 7, 2024 at 10:47 AM Gunter Van de Velde via Datatracker <
> [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,
> 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]
>
>
>
>
>
>
>