Re: [yang-doctors] guideline for enum and value?

[Benoit Claise <[e-mail]>]

> On Thu, Jan 25, 2018 at 09:59:21AM +0100, Martin Bjorklund wrote:
>> Hi,
>>
>> Juergen Schoenwaelder <[e-mail]> wrote:
>>> On Thu, Jan 25, 2018 at 09:18:27AM +0100, Benoit Claise wrote:
>>>> Dear all,
>>>>
>>>> Still busy with the RFC6087bis AD review, reviewing the enum sections now.
>>>>
>>>> Do I recall correctly a guideline about not using "value" in enum?
>> I think this was a discussion on YANG 1.1, not 6087bis (but I might be
>> wrong).
>>
>>>> Something to be inserted in RFC6087bis? At least a pros and cons discussion?
>>>>
>>> I would rather say the opposite:
>>>
>>>    YANG automatically assigns numeric values to enums if no values are
>>>    specified. This automatic assignment requires that (a) the order of
>>>    enums never changes and (b) additional enums are only appended but
>>>    never prepended or inserted. This is subtle and using explicit value
>>>    assignments, though more verbose, tends to be more robust when
>>>    modules are revised.
>> Is this a recommendation to always use the "value" statement?  I don't
>> think now is the right time to add such an recommendation, and I don't
>> think it should be recommended.  Maybe we could say something about
>> taking care when adding an enum, but RFC 7950, section 11, bullet 1
>> already says that value must not change, so we would essentially just
>> say that you must follow the rules of 7950.
>>
> The text I wrote explains the issue. It does not say you have to use
> explicit value assignments (but if you want to be robust, then its
> probably a good idea to use explicit assignments).
>
> The fact that Benoit did not recall this correctly is likely an
> indication that people not deeply involved in YANG do not necessarily
> memorize this subtlety. Not everybody knows RFC 7950 by heart. (But
> yes, not everybody will read RFC6087bis either and there are likely
> quite a few things in RFC6087bis that are not strictly needed.)
Investigating further, Einar mentioned:

    I don't advice "value" because the value doesn't appear on the wire
    & is primarily something for the backend implementation. Thus it may
    change, and having it in the model gives an opportunity for a change
    that breaks RFC 7950 backwards compatibility rules. For something
    that is irrelevant to the model consumer.

Granted, I read RFC 7950, section 11, bullet 1 multiple times by now, 
but I forgot. And finding that paragraph back is ... well challenging
The point is to provide guidelines to YANG module designers. Yes, we 
wish everybody would read (and remember) all the RFCs beforehand. I 
believe we can help those YANG module designers reading RFC6087bis, 
looking up "enum" in the TOC, found "Enumeration and Bits" and boom, 
they would find a text expressing something such as:

   YANG automatically assigns numeric values to enums if no values are
   specified. This automatic assignment requires that (a) the order of
   enums never changes and (b) additional enums are only appended but
   never prepended or inserted. Therefore, think carefully whether you
   want to assign values to enumerations in YANG modules. On one side, though
   more verbose, assigning values might be considered more robust when modules
   are revised. On the other side, NETCONF and RESTCONF do not send the numeric
   values on the wire due to the way the XML and JSON encodings are defined
   (other protocols might), so assigning values is irrelevant to the model
   consumer.

Do you believe it's useful guidance? I believe it is.
Btw, I trust the YANG doctor on the right text.

Regards, Benoit
> Anyway, I do not plan to spend more time on guessing whether this is
> helpful or not.
>
> /js
>