Subject: [yang-doctors] Style question from individuals working on IEEE YANG

From: Scott Mansfield <[email-masked]>
Date: Wed, 15 Jan 2020 12:15:19 +0000

This is an informal request to poll the YANG Doctors on a topic under
discussion

in the IEEE 802.1 working group.

The YANG people from IEEE 802.1 discovered a symmetric modelling issue
related

to YANG lists, and kindly request for feedback about the common practices in

YANG modules beyond those from IEEE 802.1.

Consider the following YANG code example:

01: leaf my-list-size {

02:   type uint32;

03:   config false;

04:   description "The number of elements in 'my-list'";

06: }

07: leaf-list my-list {

08:   type my-list-element-type;

09: }

The state value of leaf my-list-size (L01) needs to be consistent with the

number of elements in leaf-list my-list (L07). Therefore, IEEE 802.1 

identified the following options:

A)           Delete the size leaf (i.e., my-list-size).

B)            Formulate consistency requirements in IEEE standards documents

C)            Formulate consistency requirements in YANG description nodes
(e.g., L04).

D)           Formulate consistency requirements in YANG must statement(s)

E)            ???

The rationale of option A) is that a leaf-list implicitly provides the
number of

contained elements. NETCONF <get-config> or <get> operations can be used to

retrieve all list elements content from a server, and thus the number of

elements is also known to the client. A redundant size leaf is entirely
avoided. 

The main concern in this approach is the associated amount of data to be

transferred from server to client. As a practical example, a client
requiring

the number of entries in a Filtering Database (FDB) entries would read

potentially thousands of entries (IEEE 802.1Q does not specify a limit
here).

One might argue that clients don't have to know the number of elements in
the

FDB. However, the question whether there is a need or not is not the point,
it's

just an example, and there are several other, less commonly known, lists

specified by IEEE 802.1 standards for which monitoring the size information
is

inevitable in practical use. Coexisting size leafs like leaf my-list-size

appears more efficient for this purpose. 

As soon as a size leafs for list elements (or specific subsets, such as FDB

entries of a particular type) exist, it is required to ensure consistency

amongst a size leaf and the associated list in an unambiguous manner.
Network

equipment specified by IEEE 802(.1) standards is often configured by
machines.

For example, a centralized controller device might compute and upload

network-consistent configurations to all devices in the network. As a
result,

configuration of such networks is lacking human intelligence - unambiguous
and

deterministic behavior is required, and thus it is also required that the

relationship between lists and associated list size nodes is specified
cleanly.

Considering option B), such specification can (and is in many cases) be
located

in IEEE standards documents for the associated managed objects. However,
there

are concerns from IEEE 802.1 that implementers might accidentally oversee
such

statements (e.g., IEEE 802.1Q-2018 is a document with more than 2000 pages).
It

is better to locate such information in YANG.

Option C) sketches such a specification in the YANG code in a human readable

manner,  but it has some drawbacks. First, unambiguous normative verbal

formulation can become long, YANG files become large, such strong normative

specification is not helpful for client-side users and thus make the

descriptions more heavy-weight. Second, machines (e.g., YANG compilers)
cannot

interpret this specification.

Option D) appears to address these drawbacks: must statements allow machine

readable XPath expressions (and also readable by humans). Moreover, must

statements are separated from information in description nodes relevant for

client-side users. However, IEEE 802.1 is not fully aware of the
feasibility,

limitations, and implications of this option. IEEE 802.1 could not discover
such

a use of must statements in IETF's published YANG files, such that feedback
from

other SDOs on this option would be highly appreciated.

Opinions desired and appreciated!

Regards,

-scott.

Scott Mansfield

Ericsson

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Wed, 15 Jan 2020 12:55:40 +0000

On Wed, Jan 15, 2020 at 12:15:19PM +0000, Scott Mansfield wrote:
> 
> The YANG people from IEEE 802.1 discovered a symmetric modelling
> issue related to YANG lists, and kindly request for feedback about
> the common practices in YANG modules beyond those from IEEE 802.1.
> 

Looking at this from an NMDA perspective, the my-list-size leaf can
only report correctly the size of my-list in the <operational>
datastore, i.e., the applied config. The my-list that exists in lets
say the <running> datastore may have more or fewer entries.

For configuration datastores, I would rather not have such size leafs.
For the operation state datastore, they are easy to do and I would
define the requirements where the size leaf is defined, i.e., the YANG
description statement. Note that the operational state datastore
should return the true state of the device, i.e., YANG must statements
would not help you much since there is no configuration change
operation that can be rejected due to a must violation.

/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: Wed, 15 Jan 2020 13:59:07 +0100 (CET)

Hi,

It seems that (A) is not really an option.  I agree that the info
should be in the YANG model, so that leaves us with (C) or (D).

You have a config false node that has some semantics.  Since it is a
config false node, someone needs to write code to implement it, so it
is important that it is clear what the semantics are.  But it is also
important that other readers of the model understand what the node is
supposed to do.  Hence, I think taht you definitely should do (C),
i.e., document the semantics in clear prose.

A must expression (D) in general doesn't convey the same information
as plain text - you can define a constraint that must be true, but
that doesn't mean that it is clear to everyone *why* the constraint
must be true, or what an implementation is supposed to do in order to
produce a value that matches the constraint.  

[In your example it might be obvious, especially if you also take the
leaf's name into account:

     must '. = count(../my-list)';
]

/martin

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Wed, 15 Jan 2020 13:12:44 +0000

>      must '. = count(../my-list)';

This must expression may work for applied config but what about adding
an entry to my-list in <running> or <candidate>?

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 15 Jan 2020 14:17:17 +0100 (CET)

> an entry to my-list in <running> or <candidate>?

Right; as you noted, it works for the list in <operational> in an NMDA
server.

It will never count the entries in <candidate>.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 15 Jan 2020 14:17:17 +0100 (CET)

/martin

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Wed, 15 Jan 2020 14:24:28 +0000

Hi Martin, Juergen,

For clarification, are you saying that you think that all operational lists should have a corresponding size leaf?  Note - I agree that they are unneeded and unhelpful in configuration.

Or for operational lists that are likely to be small (e.g. perhaps less than a dozen entries) then omitting a size leaf may be appropriate, i.e. forcing the client to request and count the list entries if a count is required.

Thanks,
Rob

-----Original Message-----
From: yang-doctors <[email-masked]> On Behalf Of Martin Bjorklund
Sent: 15 January 2020 12:59
To: scott.mansfield=[email-masked]
Cc: [email-masked]
Subject: Re: [yang-doctors] Style question from individuals working on IEEE YANG

Hi,

It seems that (A) is not really an option.  I agree that the info should be in the YANG model, so that leaves us with (C) or (D).

You have a config false node that has some semantics.  Since it is a config false node, someone needs to write code to implement it, so it is important that it is clear what the semantics are.  But it is also important that other readers of the model understand what the node is supposed to do.  Hence, I think taht you definitely should do (C), i.e., document the semantics in clear prose.

A must expression (D) in general doesn't convey the same information as plain text - you can define a constraint that must be true, but that doesn't mean that it is clear to everyone *why* the constraint must be true, or what an implementation is supposed to do in order to produce a value that matches the constraint.  

[In your example it might be obvious, especially if you also take the leaf's name into account:

/martin

Scott Mansfield <scott.mansfield=[email-masked]> wrote:
> elements is also known to the client. A redundant size leaf is 
> entirely avoided.
> 
> One might argue that clients don't have to know the number of elements 
> in the
> 
> FDB. However, the question whether there is a need or not is not the 
> point, it's
> 
> specified by IEEE 802.1 standards for which monitoring the size 
> information is
> 
> configuration of such networks is lacking human intelligence - 
> unambiguous and
> 
> Considering option B), such specification can (and is in many cases) 
> be located
> 
> in IEEE standards documents for the associated managed objects. 
> However, there
> 
> are concerns from IEEE 802.1 that implementers might accidentally 
> oversee such
> 
> descriptions more heavy-weight. Second, machines (e.g., YANG 
> compilers) cannot
> 
> limitations, and implications of this option. IEEE 802.1 could not 
> discover such
> 
> a use of must statements in IETF's published YANG files, such that 
> feedback from
> 

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

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 15 Jan 2020 15:39:53 +0100 (CET)

"Rob Wilton (rwilton)" <[email-masked]> wrote:
> Hi Martin, Juergen,
> 
> For clarification, are you saying that you think that all operational
> lists should have a corresponding size leaf?

No!  My reply was to the question *if* this leaf is needed, how should
it be documented.

/martin

> Note - I agree that they
> are unneeded and unhelpful in configuration.
> 
> Or for operational lists that are likely to be small (e.g. perhaps
> less than a dozen entries) then omitting a size leaf may be
> appropriate, i.e. forcing the client to request and count the list
> entries if a count is required.
> 
> Thanks,
> Rob
> 
>

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Wed, 15 Jan 2020 21:18:45 +0000

On Wed, Jan 15, 2020 at 02:24:28PM +0000, Rob Wilton (rwilton) wrote:
> Hi Martin, Juergen,
> 
> For clarification, are you saying that you think that all operational lists should have a corresponding size leaf?

No. That was never my intention. If the size of a list is something
that is needed frequently, then we should create a generic query
mechanism, e.g., a get-leaf-count operation that returns the number of
leafs in a subtree or something like that. (Note that there is also a
subtle but important difference between leafs that exist and leafs
that are accessible; it should actually be the number of leafs
accessible; not sure this is what IEEE used to define).

> Note - I agree that they are unneeded and unhelpful in configuration.

It could also be helpful in configuration. I just wanted to make sure
that configuration sizes and operationally used sizes can differ.

> Or for operational lists that are likely to be small (e.g. perhaps less than a dozen entries) then omitting a size leaf may be appropriate, i.e. forcing the client to request and count the list ent…

Yes, it is a decision the modeler has to take. And this is why the
size leaf really gets into conflict with fine grained access control
since the result of retrieving foo-size and counting all of foo may
not be the same...

If such sizes are needed frequently, then having something like a
get-leaf-count operation is likely much less pain.

/js

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Thu, 16 Jan 2020 10:39:10 +0000

> From: Schönwälder, Jürgen <[email-masked]>
> Sent: 15 January 2020 21:19
> To: Rob Wilton (rwilton) <[email-masked]>
> Cc: Martin Bjorklund <[email-masked]>;
> scott.mansfield=[email-masked]; [email-masked]
> No. That was never my intention. If the size of a list is something that
> is needed frequently, then we should create a generic query mechanism,
> e.g., a get-leaf-count operation that returns the number of leafs in a
> subtree or something like that. (Note that there is also a subtle but
> important difference between leafs that exist and leafs that are
> accessible; it should actually be the number of leafs accessible; not sure
> this is what IEEE used to define).

The access control is an interesting consideration.

Another theoretical option would be a query parameter to add list size annotations.  This could seemingly work well for a CBOR or JSON encoding, but wouldn't necessarily work well for the XML encoding of YANG - in hindsight I wish that the XML encoding of YANG had included a tag to identify the entire list, rather than just tags for each element in the list.

> It could also be helpful in configuration. I just wanted to make sure that
> configuration sizes and operationally used sizes can differ.

For configuration, I didn't want the problem of clients potentially providing conflicting values for the list size vs the number of entries configured.  E.g. configuring that the list has 10 entries, but then only providing 9.  I.e. I think that the number of list entries is implicit by counting the configured entries.

> 
> > Or for operational lists that are likely to be small (e.g. perhaps less
> than a dozen entries) then omitting a size leaf may be appropriate, i.e.
> forcing the client to request and count the list entries if a count is
> required.
> 
> Yes, it is a decision the modeler has to take. And this is why the size
> leaf really gets into conflict with fine grained access control since the
> result of retrieving foo-size and counting all of foo may not be the
> same...
> 
> If such sizes are needed frequently, then having something like a get-
> leaf-count operation is likely much less pain.

My hunch is that that they are potentially useful for:
 - lists that could potentially hold a large number of entries
 - Potentially fast changing data structures (e.g. counts of entries in various routing/forwarding tables, interface counts, etc).
 - resource usage (hardware or software)

I.e. I think that they are probably the exception rather than the rule.

Thanks,
Rob