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

[Dhruv Dhody <[e-mail]>]

Hi Gunter,

On Fri, Jun 7, 2024 at 2:07 PM 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.
>
>
>

Dhruv: I understand where you are coming from. But within the context of
this YANG module and for all practical purposes, these abbreviations are
kind of well-known from the POV of the target audience of this model.

BTW the discussion on these names came up during the early YANG doctors
review as well -
https://mailarchive.ietf.org/arch/msg/teas/D9vgIfwsTztWWwfRPd7zBy_Pqu4/ and
the WG setteled on the current way where we use complete words as a top
container and use abbreviation for child nodes which made sense as a good
compromise :)

Let's see what Mahesh has to say...

Thanks,
Dhruv






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