Subject: [netmod] Y25 new solution Y25-02

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 13 Feb 2015 22:20:33 +0100

Hi,

Y25 (make enum numbering purely informative and optional) has been
discussed but no clear concensus has been reached so far. Y25-01
proposes to remove the auto-numbering mechanism. With the appearance
of a CBOR encoding proposal [1], the numeric values may actually be
used on the wire. An alternative is to keep the auto-numbering
mechanism but to clarify the risks, this is what I have written up as
solution Y25-02:

** Solution Y25-02

  Keep the auto-numbering procedure for enums and bits and add an
  explicit warning that inserting enum definitions or reordering of
  enum definitions very likely causes interoperability problem and
  that explicit value assignments avoid this problem.

  The guidelines document may add further rules such that enum/bits
  values must be explicitly defined in IETF modules (to be discussed
  in the context of the guidelines document).

[1] https://datatracker.ietf.org/doc/draft-vanderstok-core-comi/

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

---

From: Andy Bierman <[email-masked]>
Date: Fri, 13 Feb 2015 13:41:06 -0800

>   that explicit value assignments avoid this problem.

This is not really keeping the current procedure.
Currently, the auto-numbering is mandatory, and sec 10.
clearly prohibits changing any value or position statement.

IMO Y25 should be declared DEAD and the YANG 1.0 behavior
not changed at all.

You are proposing that Sec. 10 be changed so renumbering is
a warning, not a violation of the standard.

Andy

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

---

From: Per Hedeland <[email-masked]>
Date: Sat, 14 Feb 2015 00:11:07 +0100

> IMO Y25 should be declared DEAD and the YANG 1.0 behavior

+1

> a warning, not a violation of the standard.

Yes - and this is IMO clearly a non-backwards compatible change. The
"backwards compatible" requirement is extremely loosely specified by the
charter, i.e. "All compliant YANG 1.0 modules must be accepted as
compliant YANG 1.1 modules" - which if taken literally would allow for
anything that completely changes the semantics of a 1.0 module, as long
as it is still "accepted as compliant" in 1.1. This is clearly not what
anyone expects - the semantics should be unchanged, at least as long as
the 1.0 semantics are not clearly broken / unimplementable etc.

RFC 6020 makes the promise to implementations that enum values are
stable as long as section 10 is adhered to. The suggested change breaks
this promise, thus it should be considered non-backwards compatible.

The motivations for making any change at all are also very dubious:

1. "This rule makes updates of enumerations difficult"

Disregarding that "difficult" is a very subjective judgement, what
exactly is difficult about it? The only example that I have seen on the
mailing list is the infamous time zone case. This case revealed several
problems:

a) The specification of the auto numbering procedure was unclear. This
has been addressed by errata 3871.

b) No-one wanted to assume the responsibility of maintaining a standard
module specifying the enums, probably in no small part due to

c) The maintainers of the time zone data were clearly opposed to having
any part of it turned into any kind of standard, due to the (additional)
political controversy this could lead to.

However no technical or practical difficulty in maintaining a module for
these enums that adheres to section 10 has been demonstrated. In fact
assuming the obvious, that such a module would be auto-generated from
some free-form data, whether the raw timezone data or a simple list
(without any requirement on ordering) of identifiers, it is a very
trivial problem to solve. Martin already offered to provide a piece of
software to do that, I can do the same, but of course this particular
case is now moot.

In the more typical case of a handful of manually assigned enums,
maintaining the numbering can't reasonably be considered difficult.

2. "and/or forces the data modeller to assign the values explicitly even
   if they have no meaning otherwise."

The only case where a data modeller would be *forced* to assign values
is that of removing an enum other than the "last" one, without adding
another to take its place. As far as I can see, removing enums is
already ruled out by section 10, and not a candidate for change.

But obviously there are cases where some specific order of the enums is
more "natural" than others, and adhering to that order is likely to
improve readability, which is an important goal. Even in such a case
there is no need to assign values in the original version of the module,
but it may be needed on update if it is desired to add an enum "in the
middle" - but this is not being *forced*. (And readability can only be
an actual concern if the total set of enums is small, and then again it
can't reasonably be considered difficult to maintain the values.)

3. "The rule also contradicts the statement in Sec. 9.6.4.2 because the
    value in fact is used by YANG."

I disagree, the statement in 9.6.4.2 is accurate - the values aren't
*used* by YANG. YANG mereley puts some restrictions on them and provides
them to implementations. But if someone really feels strongly about
this, the obvious fix is to the text as s/YANG and// - not changing the
semantics.

--Per Hedeland

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 14 Feb 2015 10:07:53 +0100

> a warning, not a violation of the standard.

Have you read the text? I fail to see how the text implies that
existing behaviour changes. It is about adding an explicit warning.
Please explain.

/js

---

From: Per Hedeland <[email-masked]>
Date: Sat, 14 Feb 2015 12:57:30 +0100

> existing behaviour changes. It is about adding an explicit warning.

Since I came to the exact same conclusion as Andy (after reading the
text, but before reading Andy's message), I'll explain why I did that.

1. The proposal doesn't actually solve any of the alleged problems in
Y25 unless the rule in section 10 is removed.

2. The proposal explicitly mentions keeping the auto-numbering scheme,
but has no mention of the rule in section 10.

3. Adding a vague warning against something that is explicitly forbidden
by another part of the spec doesn't make any sense IMHO, and is likely
to result in confusion and risk for the rule to be overlooked.

Thus for me, the only reasonable conclusion was that you were
(implicitly) proposing that the rule in section 10 should be removed.
If this is not the case, i.e. you are proposing that both the
auto-numbering and the section 10 rule should be retained, but that
warning(s) should be added, I would suggest this text:

    Keep the auto-numbering procedures and the restrictions in section 10
    for enum values and bit positions, but add

- followed by one or both of:

a)  a warning that inserting or reordering enum or bit definitions will
    cause a violation of the rules in section 10, unless explicit
    value/position assignments are used

b)  a motivation (in section 10) of the rules in section 10, saying that
    changes to the values/positions may cause interoperability problems
    (perhaps also: and lose or at least significantly reduce the
    "convenience to implementors", since the values cannot be assumed to
    be stable)

Item a) would be quite useful IMO - actually I believe that this came as
a surprise to some of the participants in the "time zone discussion",
and the fact that it did so was a major cause of the perception of
"difficulty".

There's nothing wrong with b), but none of the other "itemized" rules
have any motivating text. This sounds like a separate issue, "Add
motivation to all the rules in section 10" (I don't personally think it
is important to do so though).

--Per

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 23 Feb 2015 15:46:03 +0100

> this promise, thus it should be considered non-backwards compatible.

What promise are you talking about? It is the enum *string* that is being
exchanged in the protocol(s), so, strictly speaking, in the context of RFC
6020 there is no way for a NETCONF/RESTCONF peer to tell whether any
implementation uses the auto-allocated values or not.

RFC 6020 also clearly says: "The value is unused by YANG and the XML
encoding, ...".

Of course, the situation changes if CBOR encoding chooses to use numeric
values but I'd argue this wasn't the original intention, and so the
motivation of the corresponding sec. 10 restriction remains unclear to
me.

> exactly is difficult about it? The only example that I have seen on

This has already been discussed several times. Consider an enumeration such as
ISO 3166 alpha-2 country codes:

https://www.iso.org/obp/ui/#search

It is sorted alphabetically, so new entries will most likely be added
somewhere in the middle. This is impossible with auto-numbering, so
currently the only solution would be to add a bogus number to each enum,
which would make the module defining such an enumeration longer by 30 %
or so.

What's your suggestion as to how such an enumeration should be set up and
maintained?

Lada

> the mailing list is the infamous time zone case. This case revealed several
> problems:

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Per Hedeland <[email-masked]>
Date: Mon, 23 Feb 2015 23:54:30 +0100

On 2015-02-23 15:46, Ladislav Lhotka wrote:
> What promise are you talking about?

The auto-numbering procedure, together with the restriction in section
10, guarantees that every enum will have an associated integer value
that doesn't change when the module is updated.

> It is the enum *string* that is being

Yes, this is not a protocol issue (yet), but ...

> RFC 6020 also clearly says: "The value is unused by YANG and the XML

... it goes on to say "... but is carried as a convenience to
implementors." I.e. being a "convenience to implementors" is the purpose
of the auto-numbering scheme and the section 10 restriction.

> values but I'd argue this wasn't the original intention,

Agreed.

> and so the

See above.

> which would make the module defining such an enumeration longer by 30 %

This can hardly be a significant concern for such a module.

> What's your suggestion as to how such an enumeration should be set up and

Same as for the time zone case, described below. If you are wondering
about the implementation of the auto-generating piece of software, it is
just a matter of parsing the previous version of the module to get the
existing value assignments, and make use of that information when
generating the new version.

However, note that the message you are replying to, and specifically the
commentary on Y25-02, was due to a misunderstanding of Juergen's
proposal. Per subsequent messages, Y25-02 was not intended to suggest
any changes to the auto-numbering scheme or the section 10 restriction.
And thus I support that proposal, although I made some suggestions for
a minor rewording.

--Per

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 24 Feb 2015 13:49:14 +0100

> Yes, this is not a protocol issue (yet), but ...

And that's my point, it is neither a language nor a protocol issue, and
therefore it doesn't belong to the specification.

> of the auto-numbering scheme and the section 10 restriction.

The real convenience is that implementors can choose whatever numbering
they like (or no numbering at all), there is no need that the numbering
be the same at the sending and receiving side.

> generating the new version.

Of course, but I have always assumed *human readability* of YANG modules
has the highest priority. And if the numbers are bogus, then they just add noise.

I simply don't agree the touted "convenience to implementors" outweighs
the inconvenience to readers of such modules and maintainers. YANG
wouldn't be less usable if the auto-numbering procedure was removed.

> And thus I support that proposal, although I made some suggestions for

I don't agree changes to values/positions can lead to interoperability
problems - unless we take the COMI decision to use these numbers in the
protocol for granted.

Lada

---

From: Andy Bierman <[email-masked]>
Date: Tue, 24 Feb 2015 08:46:41 -0800

> therefore it doesn't belong to the specification.

It will be a protocol issue soon.
Like tail-f, we also have customers who expect these mappings
to be permanent.  They are often used in the firmware instead of
the strings.  The spec clearly says these mappings are permanent.
Changing this mapping or removing the numbers altogether will
break YANG 1.0 implementations.

> has the highest priority. And if the numbers are bogus, then they just add noise.

There are not really many cases where the list of enums is auto-generated
from an external source like IANA.  Adding new enums/bits so they
do not change old numbers is usually quite easy.

> wouldn't be less usable if the auto-numbering procedure was removed.

IMO it was inevitable that a protocol would come along that used YANG
but still wanted to minimize bytes on the wire. NETCONF WG's apparent
lack of concern for message count or message size would not be shared
by other WGs.

Andy

---

From: Per Hedeland <[email-masked]>
Date: Tue, 24 Feb 2015 20:56:44 +0100

> therefore it doesn't belong to the specification.

I most definitely consider it a language issue, as it is part of the
current language specification - the one we're supposed to be backwards
compatible with.

> be the same at the sending and receiving side.

No, the convenience is that the YANG specification guarantees that the
numbers are stable. Implementors can of course choose whatever they want
regardless of whether the specification includes a numbering scheme or
not.

> has the highest priority. And if the numbers are bogus, then they just add noise.

You are raising points that I already addressed in my original message,
see below. Readability can't realistically be considered important for a
module that has hundreds of auto-generated enum statements as its only
content. And for "normal" modules, with enumeration types that have a
handful of enums, observing the section 10 requirement in the cases
where enums need to be added can't be considered difficult.

--Per

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 26 Feb 2015 10:06:50 +0100

> It will be a protocol issue soon.

I don't think it is such a great idea, but if we allow an encoding to
use the numbers rather than strings in the protocol, then of course this
discussion becomes moot.

Lada