Subject: [netconf] List Pagination Open Issue #2: Zero vs Unknown

From: Qin Wu <[email-masked]>
Date: Wed, 22 Dec 2021 12:10:08 +0000

Hi, All:
One of issues we brought up in IETF 112 is about usage of The 'remaining 'annotation.
The 'remaining 'annotation defined in our drafts is used to return the number of elements not included in a result set after a 'limit' or 'sublist-limit' operation.
The current draft (i.e., draft-wwlh-netconf-list-pagination) states that:
"If no elements were removed, this annotation MUST NOT appear.
The minimum value (0), which never occurs in normal operation, is reserved to represent 'unknown'. "

But one best practice proposed by our design team member is:
* No more entries ---> Return zero
* Unknown ---> Not return the "remaining" annotation at all

Talking with design team members, we believe that when NO entries are returned in the RPC-reply, NO annotation can be returned (because RFC 7952 says the annotation must be in the first element of the list,
but there would be no first element.)
The question is whether the "remaining" annotation should be always present or whether there is a case which it MAY not appear. If we allow it to NOT appear in those cases, it would only be reasonable to do so when there are no more elements, as that would similar to existing list retrievals (i.e. you get everything and there is no "remaining" annotation).

Here is our proposed solution to address this issue.
1.Change 'MUST' into 'May' in the draft-wwlh-netconf-list-pagination as follows:
OLD TEXT:
"
If no elements were removed, this annotation MUST NOT appear.
"
NEW TEXT:
"
If no elements were removed, this annotation MAY NOT appear.
"
Add 'none' enumeration as follows
     md:annotation remaining {
       type union {
         type uint32;
         type enumeration {
           enum "none" {
             description
               "Indicates that there are no entries that were not
                 Included in the result set, due to a 'limit' or
                 'sublist-limit' operation..";
           }
           enum "unknown" {
             description
               "Indicates that number of remaining entries is unknown
                to the server in case, e.g., the server has determined
                that counting would be prohibitively expensive.";
           }
         }
       }
       description
         "This annotation contains the number of elements not included
          in the result set due to a 'limit' or 'sublist-limit' operation.
          If no elements were removed, either the annotation MAY be
          missing or MUST have the value '0' or 'none'.  If it is unknown
          to the server how many entries may be returned, the value
          'unknown' MUST be returned.  The maximum value (2^32-1) is
          reserved to represent any value greater than or equal to
          2^32-1 elements.";
     }
Comments and suggestions are welcome!

-Qin (On behalf of authors)

---

From: William Lupton <[email-masked]>
Date: Tue, 28 Dec 2021 14:07:08 +0000

I noticed the proposed use of "MAY NOT", which I think is best avoided
(arguably "may not" means the same as "must not", and I note that it's not
called out by RFC 2119).

Perhaps you could use:

OLD TEXT:

“

”

NEW TEXT:

“

If no elements were removed, this annotation MAY be absent.

”

On Wed, 22 Dec 2021 at 12:10, Qin Wu <bill.wu=[email-masked]>
wrote:

> Hi, All:
>
> One of issues we brought up in IETF 112 is about usage of The ‘remaining
> 'annotation.
>
> The ‘remaining 'annotation defined in our drafts is used to return the
> number of elements not included in a result set after a 'limit' or
> 'sublist-limit' operation.
>
> “If no elements were removed, this annotation MUST NOT appear.
>
> The minimum value (0), which never occurs in normal operation, is reserved
> to represent 'unknown'. ”
>
>
>
> • No more entries ---> Return zero
>
> • Unknown ---> Not return the "remaining" annotation at all
>
>
>
> Talking with design team members, we believe that when NO entries are
> returned in the RPC-reply, NO annotation can be returned (because RFC 7952
> says the annotation must be in the first element of the list,
>
> The question is whether the “remaining” annotation should be always
> present or whether there is a case which it MAY not appear. If we allow it
> to NOT appear in those cases, it would only be reasonable to do so when
> there are no more elements, as that would similar to existing list
> retrievals (i.e. you get everything and there is no “remaining” annotation).
>
>
>
> 1.Change ‘MUST’ into ‘May’ in the draft-wwlh-netconf-list-pagination as
> follows:
>
> OLD TEXT:
>
> “
>
> ”
> “
> ”
> Add ‘none’ enumeration as follows
>
>            enum “none" {
>           in the result set due to a 'limit’ or 'sublist-limit’ operation.
>
>           missing or MUST have the value ‘0’ or ‘none’.  If it is unknown
>
>           ‘unknown’ MUST be returned.  The maximum value (2^32-1) is
>
> _______________________________________________
> netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>