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

[Juergen Schoenwaelder <[e-mail]>]

On Thu, Jan 25, 2018 at 11:26:05AM +0100, Benoit Claise wrote:
> 
> > 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.

Yes, the XML and JSON encodings do not use the value. However, the
CBOR encoding does use the value [draft-ietf-core-yang-cbor-05]. So we
either make sure the values are stable or we tell the CBOR people that
they can't use the value for their encoding. [There may also be bad
side effects on backend implementations if values change but the IETF
could declare that this is not the module writer's problem but the
backend writers problem.]

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

If the CBOR encoding goes forward as it is designed today, then there
is nothing that prevents to use CBOR with RESTCONF (this combination
actually makes sense in situations where you care about payload size
and encoding/decoding efficiency). What I am trying to say is that if
we allow the enum value to be used by encodings, then any protocol is
affected that can use that encoding. So listing specific protocols is
likely misleading since RESTCONF for sure can be affected (as it
supports multiple encodings).

Note, this is what RFC 7950 says on page 177:

   o  An "enumeration" type may have new enums added, provided the old
      enums's values do not change.  Note that inserting a new enum
      before an existing enum or reordering existing enums will result
      in new values for the existing enums, unless they have explicit
      values assigned to them.

My reading of the first sentence is that RFC 7950 does _not_ allow
enum value changes.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://www.jacobs-university.de/>