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

From: Benoit Claise <[email-masked]>
Date: Thu, 25 Jan 2018 09:18:27 +0100

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?
Something to be inserted in RFC6087bis? At least a pros and cons discussion?

Regards, Benoit

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 25 Jan 2018 09:37:53 +0100

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

Background:

Note that NETCONF and RESTCONF do not send the numeric values due to
the way the XML and JSON encodings are defined. But this may be
different for other encodings, the proposed CBOR encoding uses the
numeric value. Some implementations do support mappings to protocols
such as SNMP where numeric values are used.

We had a longer discussion about this when we talked about how we deal
with timezones, which change regularly and have no natural numeric
value. Algorithms to produce YANG enumerations from the timezone
databases are difficult if you want to have stable numeric values.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 25 Jan 2018 09:59:21 +0100 (CET)

Hi,

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

>   assignments, though more verbose, tends to be more robust when

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.

/martin

> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 25 Jan 2018 10:11:18 +0100

> 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.)
Anyway, I do not plan to spend more time on guessing whether this is
helpful or not.

/js

---

From: Benoit Claise <[email-masked]>
Date: Thu, 25 Jan 2018 11:26:05 +0100

> 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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 25 Jan 2018 11:51:24 +0100

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

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

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Thu, 25 Jan 2018 10:57:15 +0000

I agree with Juergen. I also believe when the enum corresponds to some standard value (e.g., IETF address families), there is significant advantage in preserving that value in the YANG enum. 
Thanks,
Acee 

On 1/25/18, 3:38 AM, "yang-doctors on behalf of Juergen Schoenwaelder" <[email-masked] on behalf of [email-masked]> wrote:

    
    
    Background:

    
    /js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 25 Jan 2018 12:08:04 +0100 (CET)

> but I forgot. And finding that paragraph back is ... well

Note that when the initial module is designed, this doesn't matter.

When you upgrade a module, I think we can assume that people read
section 11 of RFC 7950.

> The point is to provide guidelines to YANG module designers.

Right.  And I don't think we should have a guideline that encourage
people to use explicit value statements in most cases.  I would be ok
with a recommendation along the lines:

  Do not use explicit 'value' statements, except if:

    o  the enum corresponds to some standard integer value, or

    o  you update the set of enums by inserting new enums in the
    middle of the list

/martin

> Yes, we

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 25 Jan 2018 12:53:26 +0100

> When you upgrade a module, I think we can assume that people read

Good luck with that.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 25 Jan 2018 13:00:04 +0100 (CET)

> > When you upgrade a module, I think we can assume that people read

I can rephrase:  It is as likely that people read section 11 of RFC
7950 as they read section XXX of RFC6087bis.

/martin

---

From: Christian Hopps <[email-masked]>
Date: Thu, 25 Jan 2018 07:16:57 -0500

> When you upgrade a module, I think we can assume that people read

This made me wonder, shouldn't incompatible changes be caught somewhere
in the model validation process? Do we have tooling to support that? I
realize this would only apply to our own process (and anyone who borrows
it).

Thanks,
Chris.