NETCONF Working Group                                          K. Watsen
Internet-Draft                                            Watsen Network
Intended status: Standards Track                                   Q. Wu
Expires: May 6, 2021                                              Huawei
                                                              O. Hagsand
                                                                 Netgate
                                                                   H. Li
                                                                     HPE
                                                        November 2, 2020


             NETCONF Extensions to Support List Pagination
                draft-wwlh-netconf-list-pagination-nc-01

Abstract

   In some circumstance, a server may contain many instances of a
   particular YANG list or leaf-list.  Retrieval of the entire list or
   leaf-list at once can be extremely inefficient.

   This document defines a YANG data model with "get-pageable-list" RPC
   to allow a client to iterate through a large list, in a manner that
   is most efficient for the application.

   The YANG data model in this document conforms to the Network
   Management Datastore Architecture defined in RFC 8342.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on May 6, 2021.








Watsen, et al.             Expires May 6, 2021                  [Page 1]


Internet-Draft         NETCONF Pagination Support          November 2020


Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  NETCONF operation . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.  The <get-list-pagination> operation . . . . . . . . . . .   4
   3.  YANG Module for List Pagination . . . . . . . . . . . . . . .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  13
     4.1.  The "IETF XML" Registry . . . . . . . . . . . . . . . . .  13
     4.2.  The "YANG Module Names" Registry  . . . . . . . . . . . .  13
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  14
     5.1.  The "ietf-netconf-list-pagination" YANG Module  . . . . .  14
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  14
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .  14
     6.2.  Informative References  . . . . . . . . . . . . . . . . .  15
   Appendix A.  Open Issues  . . . . . . . . . . . . . . . . . . . .  16
   Appendix B.  Example YANG Module  . . . . . . . . . . . . . . . .  16
     B.1.  "example-module" YANG Module  . . . . . . . . . . . . . .  17
     B.2.  Data-Set for example-module . . . . . . . . . . . . . . .  23
   Appendix C.  NETCONF YANG Collection Examples . . . . . . . . . .  27
     C.1.  "count" Parameter . . . . . . . . . . . . . . . . . . . .  28
     C.2.  "skip" Parameter  . . . . . . . . . . . . . . . . . . . .  28
     C.3.  "direction" Parameter . . . . . . . . . . . . . . . . . .  29
     C.4.  "sort" Parameter  . . . . . . . . . . . . . . . . . . . .  30
     C.5.  Combination of "where" and "count" Parameters . . . . . .  31
     C.6.  Combination of "where", "count" and "skip" Parameters . .  32
     C.7.  Combination of "where", "count","skip" and "sort"
           Parameters  . . . . . . . . . . . . . . . . . . . . . . .  33
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  34
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  35






Watsen, et al.             Expires May 6, 2021                  [Page 2]


Internet-Draft         NETCONF Pagination Support          November 2020


1.  Introduction

   There is a need for standard mechanisms to control the filtering,
   sorting, and retrieval of data from the server.  A server may contain
   many instances of a particular YANG list.  Retrieval of the entire
   list or leaf-list at once can be extremely inefficient.

   This document defines a YANG module for Pagination mechanisms which
   allow a client to iterate through a large list or leaf-list, in a
   manner that is most efficient for the application.

   While the pagination mechanism defined in this document is designed
   for the NETCONF protocol [RFC6241], the RPC MAY be used by the
   RESTCONF protocol [RFC8040] if the RESTCONF server implements the
   "ietf-yang-list-pagination" module.

   The YANG data model in this document conforms to the Network
   Management Datastore Architecture defined in [RFC8342]

1.1.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The following terms are defined in [RFC8342] [RFC7950] and are not
   redefined here:

   o  server

   o  startup configuration datastore

   o  candidate configuration datastore

   o  running configuration datastore

   o  intended configuration datastore

   o  operational state datastore

   o  conventional configuration datastore

   o  datastore schema

   o  RPC operation




Watsen, et al.             Expires May 6, 2021                  [Page 3]


Internet-Draft         NETCONF Pagination Support          November 2020


   The following terms are defined in this document as follows:

2.  NETCONF operation

   This document define a new operation -- <get-list-pagination> to
   support YANG based pagination.  This operation is similar to the
   <get-data> [RFC8526] in that it takes an input parameter to indicate
   the datastore that is the source of the data to be retrieved.

2.1.  The <get-list-pagination> operation

   The <get-pageable-list> operation uses enhanced filtering features to
   retrieve data from a specific NMDA datastore.  This operation is
   similar to <get-data> operation defined in [RFC8526] and have the
   flexibility to select the different source datastore.

    +---x get-pageable-list
       +---w input
       |  +---w datastore?     string
       |  +---w (filter-spec)?
       |  |  +--:(subtree-filter)
       |  |  |  +---w subtree-filter?          <anydata>
       |  |  +--:(xpath-filter)
       |  |     +---w xpath-filter?            yang:xpath1.0 {nc:xpath}?
       |  +---w config-filter?                 boolean
       |  +---w (origin-filters)? {origin}?
       |  |  +--:(origin-filter)
       |  |  |  +---w origin-filter*           or:origin-ref
       |  |  +--:(negated-origin-filter)
       |  |     +---w negated-origin-filter*   or:origin-ref
       |  +---w max-depth?                     union
       |  +---w with-origin?                   empty {origin}?
       |  +---w with-defaults?                 with-defaults-mode
       |  +---w list-target    string
       |  +---w count?         union
       |  +---w skip?          union
       |  +---w direction?     enumeration
       |  +---w sort?          string
       |  +---w where?         string
       +--ro output
          +--ro collection?   <anyxml>

   The "datastore" parameter indicates the datastore that is the source
   of the data to be retrieved.  This is a "datastore" identity.

   The <get-pageable-list> operation accepts a content filter parameter,
   similar to the "filter" parameter of <get-config>, but uses explicit
   nodes for list filtering or leaf-list filtering.



Watsen, et al.             Expires May 6, 2021                  [Page 4]


Internet-Draft         NETCONF Pagination Support          November 2020


   The "config-filter" parameter can be used to retrieve only "config
   true" or "config false" nodes.

   The "origin-filter" parameter, which can be present multiple times,
   selects nodes equal to or derived from any of the given values.  The
   "negated-origin-filter", which can be present multiple times, selects
   nodes that are not equal to or derived from any of the given values.
   The "origin-filter" and "negated-origin-filter" parameters cannot be
   used together.

   The "max-depth" parameter can be used by the client to limit the
   number of subtree levels that are returned in the reply.

   The "with-origin" parameter can be used to request the server to
   include "origin" metadata annotations in its response, as detailed in
   the NMDA.  The 'with-origin' parameter is only valid for an
   operational datastore.  See section 3.1.1.1 of [RFC8526] for the
   behavior of the "with-origin" parameter for <operational>.

   The "with-default"parameter can be used to control whether default
   data is returned by the server.  The 'with-default' parameter is only
   valid for an operational datastore.  See section 3.1.1.2 of [RFC8526]
   for the behavior of the "with-defaults" parameter for <operational>.

   The "list-target" parameter is used to specify that YANG list that
   will be retrieved.  This must be a path expression used to represent
   a list data node.

   The "count" parameter can be used to specify the maximum number of
   list entries to return.  The value of the "count" parameter is either
   an integer greater than or equal to 1, or the string "unbounded".
   The string "unbounded" is the default value.

   The "skip" parameter can be used to specify the first list item to
   return in response to NETCONF/Request requests on instances of a
   particular YANG list.  YANG list instances are numbered with
   consecutive integers from 1 to the number of YANG list instances.

   The value of the "skip" parameter is an integer greater than or equal
   to 1.  The default value is 1.

   If the "where" parameter is specified, the "skip" parameter MUST
   start with a set of selected list resources picked by using "where"
   parameter and specify the first list item resource to return.

   The "direction" parameter can be used to specify the direction
   relative to the 'sort' order through list or leaf-list.




Watsen, et al.             Expires May 6, 2021                  [Page 5]


Internet-Draft         NETCONF Pagination Support          November 2020


   The "sort" parameter is used to indicates how the entries in a list
   are to be sorted.  By default, the value of the "sort" is default,
   i.e., for 'ordered-by user' lists and leaf-lists, the default order
   is the user-configured order; for 'ordered-by system' lists and leaf-
   lists, the default order is specified by the system.

   The "where" parameter is used to specify the boolean filter to select
   data instances to return from the list or leaf-list target.  The
   filter element contains boolean XPATH expression.  The filter output
   is a set of selected list items.  The server determines which node
   instances are included (or potentially included) in the filter
   output, and which node instances are excluded (pruned) from the
   filter output.

   The selected list instances are numbered with consecutive integers
   from 1 to the number of list instances.

   The expected processing order: filter -> sort -> direction -> skip ->
   count.

3.  YANG Module for List Pagination

   The "ietf-netconf-list-pagination" module defines conceptual
   definitions within groupings, which are not meant to be implemented
   as datastore contents by a server.

   This module has normative references to [RFC6241], [RFC6243],
   [RFC6991], and [RFC8342].

<CODE BEGINS> file "ietf-netconf-list-pagination@2020-10-30.yang"
module ietf-netconf-list-pagination {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination";
  prefix ycoll;

  import ietf-netconf {
    prefix nc;
    reference
      "RFC 6241: Network Configuration Protocol (NETCONF)";
  }
  import ietf-netconf-with-defaults {
    prefix ncwd;
    reference
      "RFC 6243: With-defaults Capability for NETCONF";
  }
  import ietf-yang-types {
    prefix yang;
    reference



Watsen, et al.             Expires May 6, 2021                  [Page 6]


Internet-Draft         NETCONF Pagination Support          November 2020


      "RFC 6991: Common YANG Data Types";
  }
  import ietf-datastores {
    prefix ds;
    reference
      "RFC 8342: Network Management Datastore Architecture
       (NMDA)";
  }
  import ietf-origin {
    prefix or;
    reference
      "RFC 8342: Network Management Datastore Architecture
       (NMDA)";
  }

  organization
    "IETF NETCONF (Network Configuration) Working Group";
  contact
    "WG Web:   <http://tools.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>

     Editor:

     Editor:

     Editor:   ";
  description
    "This module define a new operation -- <get-collection>
     to support YANG based pagination.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2019 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Simplified BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC 8526; see
     the RFC itself for full legal notices.";



Watsen, et al.             Expires May 6, 2021                  [Page 7]


Internet-Draft         NETCONF Pagination Support          November 2020


  revision 2020-10-30 {
    description
      "Initial revision.";
    reference
      "RFC XXXX: YANG Based Pagination.";
  }

  feature origin {
    description
      "Indicates that the server supports the 'origin' annotation.";
    reference
      "RFC 8342: Network Management Datastore Architecture (NMDA)";
  }

  feature with-defaults {
    description
      "NETCONF :with-defaults capability.  If the server advertises
       the :with-defaults capability for a session, then this
       feature must also be enabled for that session.  Otherwise,
       this feature must not be enabled.";
    reference
      "RFC 6243: With-defaults Capability for NETCONF, Section 4; and
       RFC 8526: NETCONF Extensions to Support the Network Management
       Datastore Architecture, Section 3.1.1.2";
  }

  rpc get-pagable-list {
    description
      "Use enhanced filtering features to retrieve data from a
       specific NMDA datastore. The content returned by get-data
       must satisfy all filters, i.e., the filter criteria are
       logically ANDed.

       Any ancestor nodes (including list keys) of nodes selected by
       the filters are included in the response.

       The 'with-origin' parameter is only valid for an operational
       datastore.  If 'with-origin' is used with an invalid
       datastore, then the server MUST return an <rpc-error> element
       with an <error-tag> value of 'invalid-value'.

       The 'with-defaults' parameter only applies to the operational
       datastore if the NETCONF :with-defaults and
       :with-operational-defaults capabilities are both advertised.
       If the 'with-defaults' parameter is present in a request for
       which it is not supported, then the server MUST return an
       <rpc-error> element with an <error-tag> value of
       'invalid-value'.";



Watsen, et al.             Expires May 6, 2021                  [Page 8]


Internet-Draft         NETCONF Pagination Support          November 2020


    input {
      leaf datastore {
        type ds:datastore-ref;
        mandatory true;
        description
          "Datastore from which to retrieve data.

           If the datastore is not supported by the server, then
           the server MUST return an <rpc-error> element with an
           <error-tag> value of 'invalid-value'.";
      }
      choice filter-spec {
        description
          "The content filter specification for this request.";
        anydata subtree-filter {
          description
            "This parameter identifies the portions of the
             target datastore to retrieve.";
          reference
            "RFC 6241: Network Configuration Protocol (NETCONF),
                       Section 6";
        }
        leaf xpath-filter {
          if-feature "nc:xpath";
          type yang:xpath1.0;
          description
            "This parameter contains an XPath expression identifying
             the portions of the target datastore to retrieve.

             If the expression returns a node-set, all nodes in the
             node-set are selected by the filter.  Otherwise, if the
             expression does not return a node-set, then the
             <get-data> operation fails.

             The expression is evaluated in the following XPath
             context:

               o  The set of namespace declarations are those in
                  scope on the 'xpath-filter' leaf element.

               o  The set of variable bindings is empty.

               o  The function library is the core function library,
                  and the XPath functions are defined in Section 10
                  of RFC 7950.

               o  The context node is the root node of the target
                  datastore.";



Watsen, et al.             Expires May 6, 2021                  [Page 9]


Internet-Draft         NETCONF Pagination Support          November 2020


        }
      }
      leaf config-filter {
        type boolean;
        description
          "Filter for nodes with the given value for their 'config'
           property.  When this leaf is set to 'true', only 'config
           true' nodes are selected, and when set to 'false', only
           'config false' nodes are selected.  If this leaf is not
           present, no nodes are filtered.";
      }
      choice origin-filters {
        when 'derived-from-or-self(datastore, "ds:operational")';
        if-feature "origin";
        description
          "Filters configuration nodes based on the 'origin'
           annotation.  Configuration nodes that do not have an
           'origin' annotation are treated as if they have the
           'origin' annotation 'or:unknown'.

           System state nodes are not affected by origin-filters and
           thus not filtered.  Note that system state nodes can be
           filtered with the 'config-filter' leaf.";
        leaf-list origin-filter {
          type or:origin-ref;
          description
            "Filter based on the 'origin' annotation.  A
             configuration node matches the filter if its 'origin'
             annotation is derived from or equal to any of the given
             filter values.";
        }
        leaf-list negated-origin-filter {
          type or:origin-ref;
          description
            "Filter based on the 'origin' annotation.  A
             configuration node matches the filter if its 'origin'
             annotation is neither derived from nor equal to any of
             the given filter values.";
        }
      }
      leaf max-depth {
        type union {
          type uint16 {
            range "1..65535";
          }
          type enumeration {
            enum unbounded {
              description



Watsen, et al.             Expires May 6, 2021                 [Page 10]


Internet-Draft         NETCONF Pagination Support          November 2020


                "All descendant nodes are included.";
            }
          }
        }
        default "unbounded";
        description
          "For each node selected by the filters, this parameter
           selects how many conceptual subtree levels should be
           returned in the reply.  If the depth is 1, the reply
           includes just the selected nodes but no children.  If the
           depth is 'unbounded', all descendant nodes are included.";
      }
      leaf with-origin {
        when 'derived-from-or-self(../datastore, "ds:operational")';
        if-feature "origin";
        type empty;
        description
          "If this parameter is present, the server will return
           the 'origin' annotation for the nodes that have one.";
      }
      uses ncwd:with-defaults-parameters {
        if-feature "with-defaults";
      }
      leaf list-target {
        description
          "Identifies the list object that is being retrieved.
           This must be a path expression used to represent
           a list data node or leaf-list data node. ";
        mandatory true;
        type string;
      }
      leaf count {
        type union {
          type uint32;
          type string {
            pattern 'unbounded';
          }
        }
        default "unbounded";
        description
          "The maximum number of list entries to return. The
           value of the 'count' parameter is either an integer
           greater than or equal to 1, or the string 'unbounded'.
           The string 'unbounded' is the default value.";
      }
      leaf skip {
        type union {
          type uint32;



Watsen, et al.             Expires May 6, 2021                 [Page 11]


Internet-Draft         NETCONF Pagination Support          November 2020


          type string {
            pattern 'none';
          }
        }
        default "none";
        description
          "The first list item to return.
           the 'skip' parameter is either an integer greater than
           or equal to 1, or the string 'unbounded'.  The string
           'unbounded' is the default value.";
      }
      leaf direction {
        type enumeration {
          enum forward;
          enum reverse;
        }
        default "forward";
        description
          "Direction relative to the 'sort' order through list
           or leaf-list. It can be forward direction or reverse
           direction.";
      }
      leaf sort {
        type union {
          type string {
            length "1..max" {
              description
                "The name of a descendent node to sort on.  For
                 'Config false' lists and leaf-lists, the node SHOULD
                  have the 'TBD' extension indicating that it has been
                  indexed, enabling efficient sorts.";
            }
          }
          type enumeration {
            enum default {
              description
                "Indicates that the 'default' order is assumed.  For
                 'ordered-by user' lists and leaf-lists, the default order
                 is the user-configured order.  For 'ordered-by system'
                 lists and leaf-lists, the default order is specified by the
                 system.";
            }
          }
        }
        default "default";
        description
          "Indicates how the entries in a list are to be sorted.";
      }



Watsen, et al.             Expires May 6, 2021                 [Page 12]


Internet-Draft         NETCONF Pagination Support          November 2020


      leaf where {
        type yang:xpath1.0;
        description
          "The boolean filter to select data instances to return from
           the list or leaf-list target.  The Xpath expression MAY be
           constrained either server-wide, by datastore, by 'config'
           status, or per list or leaf-list.  Details regarding how
           constraints are communicated are TBD.  This parameter
           is optional; no filtering is applied when it is not
           specified.";
      }
    }
    output {
      anyxml pageable-list {
        description
          "Return the list entries that were requested and matched
           the filter criteria (if any). An empty data container
           indicates that the request did not produce any results.";
      }
    }
  }
}
<CODE ENDS>

4.  IANA Considerations

4.1.  The "IETF XML" Registry

   This document registers one URI in the "ns" subregistry of the IETF
   XML Registry [RFC3688] maintained at
   <https://www.iana.org/assignments/xml-registry/xml-
   registry.xhtml#ns>.  Following the format in [RFC3688], the following
   registration is requested:

     URI: urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination
     Registrant Contact: The IESG.
     XML: N/A, the requested URI is an XML namespace.

4.2.  The "YANG Module Names" Registry

   This document registers one YANG module in the YANG Module Names
   registry [RFC6020] maintained at <https://www.iana.org/assignments/
   yang-parameters/yang-parameters.xhtml>.  Following the format defined
   in [RFC6020], the below registration is requested:







Watsen, et al.             Expires May 6, 2021                 [Page 13]


Internet-Draft         NETCONF Pagination Support          November 2020


    name: ietf-restconf-list-pagination
    namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-list-pagination
    prefix: rlpg
    RFC: xxxx

5.  Security Considerations

5.1.  The "ietf-netconf-list-pagination" YANG Module

   The YANG module defined in this document extends the base operations
   for NETCONF [RFC6241] and RESTCONF [RFC8040].  The lowest NETCONF
   layer is the secure transport layer, and the mandatory-to-implement
   secure transport is Secure Shell (SSH) [RFC6242].  The lowest
   RESTCONF layer is HTTPS, and the mandatory-to-implement secure
   transport is TLS [RFC8446].

   The Network Configuration Access Control Model (NACM) [RFC8341]
   provides the means to restrict access for particular NETCONF users to
   a preconfigured subset of all available NETCONF protocol operations
   and content.

   The security considerations for the base NETCONF protocol operations
   (see Section 9 of [RFC6241] apply to the new <get-list-pagination>
   RPC operations defined in this document.

6.  References

6.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.




Watsen, et al.             Expires May 6, 2021                 [Page 14]


Internet-Draft         NETCONF Pagination Support          November 2020


   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
              <https://www.rfc-editor.org/info/rfc6242>.

   [RFC6243]  Bierman, A. and B. Lengyel, "With-defaults Capability for
              NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
              <https://www.rfc-editor.org/info/rfc6243>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/info/rfc8341>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

6.2.  Informative References

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8446]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
              <https://www.rfc-editor.org/info/rfc8446>.

   [RFC8526]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "NETCONF Extensions to Support the Network
              Management Datastore Architecture", RFC 8526,
              DOI 10.17487/RFC8526, March 2019,
              <https://www.rfc-editor.org/info/rfc8526>.






Watsen, et al.             Expires May 6, 2021                 [Page 15]


Internet-Draft         NETCONF Pagination Support          November 2020


Appendix A.  Open Issues

   Cursors (i.e.,stable result sets) are related to the topic of dynamic
   changing lists between two queries.  How cursors can be supported
   using "feature"?

Appendix B.  Example YANG Module

   The example YANG module used in this document is supposed to
   illustrate certain features and not supposed to be complete, valid
   YANG modules.

   YANG tree diagram for the "example-module" module:






































Watsen, et al.             Expires May 6, 2021                 [Page 16]


Internet-Draft         NETCONF Pagination Support          November 2020


   module: example-module
     +--rw admins
     |  +--rw admin* [name]
     |     +--rw name             string
     |     +--rw access?          enumeration
     |     +--rw email-address?   email-address
     |     +--rw password?        ianach:crypt-hash
     |     +--ro status*           string
     |     +--rw preference
     |     |  +--rw number*   uint8
     |     +--rw skill* [name]
     |        +--rw name    string
     |        +--rw rank?   uint8
     +--rw rulebase
     |  +--rw rule* [name]
     |     +--rw name      string
     |     +--rw match?    string
     |     +--rw action?   enumeration
     +--rw device-logs
     |  +--ro device-log* []
     |     +--ro device-id?        string
     |     +--ro time-received?    yang:timestamp
     |     +--ro time-generated?   yang:timestamp
     |     +--ro message?          string
     +--rw audit-logs
     |  +--ro audit-log* [log-creation]
     |     +--ro source-ip?      inet:ip-address
     |     +--ro log-creation?   yang:timestamp
     |     +--ro request?        string
     |     +--ro outcome?        boolean
     +--rw prefixes
        +--rw prefix-list* [ip-prefix masklength-lower masklength-upper]
           +--rw ip-prefix           inet:ip-prefix
           +--rw masklength-lower    uint8
           +--rw masklength-upper    uint8

B.1.  "example-module" YANG Module

module example-module {
  yang-version 1.1;
  namespace "http://example.com/ns/example-module";
  prefix exm;

  import iana-crypt-hash {
    prefix ianach;
  }
  import ietf-inet-types {
    prefix inet;



Watsen, et al.             Expires May 6, 2021                 [Page 17]


Internet-Draft         NETCONF Pagination Support          November 2020


  }
  import ietf-yang-types {
    prefix yang;
  }

  organization
    "Example, Inc.";
  contact
    "support at example.com";
  description
    "Example Data Model Module.";

  revision 2020-10-06 {
    description
      "Initial version.";
    reference
      "example.com document 1-4673.";
  }

  container admins {
    description
      "Admin Group configuration.";
    list admin {
      key "name";
      description
        "List of admins for admin group configuration.";
      ordered-by system;
      leaf name {
        type string {
          length "1 .. max";
        }
        description
          "The name of the admin.";
      }
      leaf access {
        type enumeration {
          enum permit {
            description
              "Permit access privilege.";
          }
          enum deny {
            description
              "Deny access privilege.";
          }
          enum limited {
            description
              "Limited access privilege.";
          }



Watsen, et al.             Expires May 6, 2021                 [Page 18]


Internet-Draft         NETCONF Pagination Support          November 2020


        }
        default "permit";
        description
          "The Access privilege type for this admin.";
      }
      leaf email-address {
        type inet:email-address;
        description
          "Contact email of the admin.";
      }
      leaf password {
        type ianach:crypt-hash;
        description
          "The password for this entry.";
      }
      leaf-list status {
        type string;
        config false;
        description
          "The status for this entry.";
      }
      container preference {
        leaf-list number {
          type uint8;
          description
            "Defines the perference numbers for the admin.";
        }
        description
          "Preference parameters.";
      }
      list skill {
        key "name";
        description
          "Represents one 'sill' resource within one
           'admin' resource.";
        leaf name {
          type string {
            length "1 .. max";
          }
          description
            "The name of the skill.";
        }
        leaf rank {
          type uint16;
          description
            "The rank identifying the rank on
             the skill.";
        }



Watsen, et al.             Expires May 6, 2021                 [Page 19]


Internet-Draft         NETCONF Pagination Support          November 2020


      }
    }
  }
  container rulebase {
    description
      "Rule base configuration";
    list rule {
      key "name";
      description
        "List of rules for rulebase.";
      ordered-by user;
      leaf name {
        type string {
          length "1 .. max";
        }
        description
          "The name of the rule.";
      }
      leaf match {
        type string {
          length "1 .. max";
        }
        description
          "The rules in this rulebase determine what fields will be
           matched upon before any action is taken on them.";
      }
      leaf action {
        type enumeration {
          enum forwarding {
            description
              "Specify forwarding behavior per rule entry.";
          }
          enum logging {
            description
              "Specify logging behavior per rule entry.";
          }
        }
        default "logging";
        description
          "Defintion of the action for this rule entry.";
      }
    }
  }
  container device-logs {
    description
      "Device log configuration";
    list device-log {
      description



Watsen, et al.             Expires May 6, 2021                 [Page 20]


Internet-Draft         NETCONF Pagination Support          November 2020


        "List of device logs.";
      config false;
      leaf device-id {
        type string;
        description
          "The device id of the device log.";
      }
      leaf time-received {
        type yang:date-and-time;
        description
          "The timestamp value at the time this
           log was received.";
      }
      leaf time-generated {
        type yang:date-and-time;
        description
          "The timestamp value at the time this
           log was generated.";
      }
      leaf message {
        type string;
        description
          "Message given at start of login session.";
      }
    }
  }
  container audit-logs {
    description
      "Audit log configuration";
    list audit-log {
      key "log-creation";
      description
        "List of audit logs.";
      config false;
      leaf source-ip {
        type inet:ip-address;
        description
          "The IP address of the targeted object.";
      }
      leaf log-creation {
        type yang:date-and-time;
        description
          "The timestamp value at the time this
           log was created.";
      }
      leaf request {
        type string;
        description



Watsen, et al.             Expires May 6, 2021                 [Page 21]


Internet-Draft         NETCONF Pagination Support          November 2020


          "Request type of audit log.";
      }
      leaf outcome {
        type boolean;
        default "true";
        description
          "Indicate the audit log is retrieved sucessfully or not.";
      }
    }
  }
  container prefixes {
    description
      "Enclosing container for the list of prefixes in a policy
       prefix list";
    list prefix-list {
      key "ip-prefix masklength-lower masklength-upper";
      description
        "List of prefixes in the prefix set";
      leaf ip-prefix {
        type inet:ip-prefix;
        mandatory true;
        description
          "The prefix member in CIDR notation -- while the
           prefix may be either IPv4 or IPv6, most
           implementations require all members of the prefix set
           to be the same address family.  Mixing address types in
           the same prefix set is likely to cause an error.";
      }
      leaf masklength-lower {
        type uint8;
        description
          "Masklength range lower bound.";
      }
      leaf masklength-upper {
        type uint8 {
          range "1..128";
        }
        must '../masklength-upper >= ../masklength-lower' {
          error-message "The upper bound should not be lessthan lower bound.";
        }
        description
          "Masklength range upper bound.

           The combination of masklength-lower and masklength-upper
           define a range for the mask length, or single 'exact'
           length if masklength-lower and masklenght-upper are equal.

           Example: 10.3.192.0/21 through 10.3.192.0/24 would be



Watsen, et al.             Expires May 6, 2021                 [Page 22]


Internet-Draft         NETCONF Pagination Support          November 2020


           expressed as prefix: 10.3.192.0/21,
                        masklength-lower=21,
                        masklength-upper=24

           Example: 10.3.192.0/21 (an exact match) would be
           expressed as prefix: 10.3.192.0/21,
                        masklength-lower=21,
                        masklength-upper=21";
      }
    }
  }
}

B.2.  Data-Set for example-module

     <admins xmlns="http://example.com/ns/example-module">
       <admin>
         <name>Alice</name>
         <access>permit</access>
         <email-address>alice@example.com</email-address>
         <password>$0$1543</password>
         <status>Available</status>
         <preference>
           <number>1</number>
           <number>2</number>
         </preference>
         <skill>
           <name>Customer Service</name>
           <rank>99</rank>
         </skill>
         <skill>
           <name>Problem Solving</name>
           <rank>90</rank>
         </skill>
       </admin>
       <admin>
         <name>Bob</name>
         <access>limited</access>
         <email-address>bob@example.com</email-address>
         <password>$0$2789</password>
         <status>Busy</status>
         <preference>
           <number>2</number>
           <number>3</number>
         </preference>
         <skill>
           <name>Problem Solving</name>
           <rank>98</rank>



Watsen, et al.             Expires May 6, 2021                 [Page 23]


Internet-Draft         NETCONF Pagination Support          November 2020


         </skill>
         <skill>
           <name>Conflict Resolution</name>
           <rank>93</rank>
         </skill>
       </admin>
       <admin>
         <name>Joe</name>
         <access>permit</access>
         <email-address>joe@example.com</email-address>
         <password>$0$6523</password>
         <status>Do Not Disturb</status>
         <preference>
           <number>1</number>
           <number>4</number>
         </preference>
         <skill>
           <name>Management</name>
           <rank>96</rank>
         </skill>
         <skill>
           <name>Collaboration</name>
           <rank>92</rank>
         </skill>
       </admin>
       <admin>
         <name>Frank</name>
         <access>deny</access>
         <email-address>frank@example.com</email-address>
         <password>$0$4030</password>
         <status>Offline</status>
         <preference>
           <number>5</number>
           <number>9</number>
         </preference>
         <skill>
           <name>Organization</name>
           <rank>90</rank>
         </skill>
         <skill>
           <name>Negotiation</name>
           <rank>80</rank>
         </skill>
       </admin>
       <admin>
         <name>Tom</name>
         <access>permit</access>
         <email-address>tom@example.com</email-address>



Watsen, et al.             Expires May 6, 2021                 [Page 24]


Internet-Draft         NETCONF Pagination Support          November 2020


         <password>$0$2376</password>
         <status>Do Not Disturb</status>
         <preference>
           <number>2</number>
           <number>5</number>
         </preference>
         <skill>
           <name>Adaptability.</name>
           <rank>98</rank>
         </skill>
         <skill>
           <name>Active Listening</name>
           <rank>85</rank>
         </skill>
       </admin>
     </admins>
     <rulebase  xmlns="http://example.com/ns/example-module">
       <rule>
         <name>SvrA-http</name>
         <match>92.0.2.0/24</match>
         <action>forwarding</action>
       </rule>
       <rule>
         <name>SvrA-ftp</name>
         <match>203.0.113.1/32</match>
         <action>forwarding</action>
       </rule>
       <rule>
         <name>p2p</name>
         <match>p2p</match>
         <action>logging</action>
       </rule>
       <rule>
         <name>any</name>
         <match>any</match>
         <action>logging</action>
       </rule>
       <rule>
         <name>SvrA-tcp</name>
         <match>80</match>
         <action>forwarding</action>
       </rule>
     </rulebase>
     <device-logs  xmlns="http://example.com/ns/example-module">
       <device-log>
         <device-id>Cloud-IoT-Device-A</device-id>
         <time-received>2020-07-08T12:38:32Z</time-received>
         <time-generated>2020-07-08T12:37:12Z</time-generated>



Watsen, et al.             Expires May 6, 2021                 [Page 25]


Internet-Draft         NETCONF Pagination Support          November 2020


         <message>Upload contains 6 datapoints</message>
       </device-log>
       <device-log>
         <device-id>Cloud-IoT-Device-B</device-id>
         <time-received>2020-07-08T16:20:54Z</time-received>
         <time-generated>2020-07-08T16:20:14Z</time-generated>
         <message>Upload successful</message>
       </device-log>
       <device-log>
         <device-id>Cloud-IoT-Device-C</device-id>
         <time-received>2020-07-08T17:30:34Z</time-received>
         <time-generated>2020-07-08T17:30:12Z</time-generated>
         <message>Receive a configuration update</message>
       </device-log>
       <device-log>
         <device-id>Cloud-IoT-Device-D</device-id>
         <time-received>2020-07-08T18:40:13Z</time-received>
         <time-generated>2020-07-08T18:40:00Z</time-generated>
         <message>Keep-alive ping sent to server</message>
       </device-log>
       <device-log>
         <device-id>Cloud-IoT-Device-E</device-id>
         <time-received>2020-07-08T19:48:34Z</time-received>
         <time-generated>2020-07-08T19:48:00Z</time-generated>
         <message>Uploading data to DataPoint</message>
       </device-log>
     </device-logs>
     <audit-logs  xmlns="http://example.com/ns/example-module">
       <audit-log>
         <source-ip>192.168.0.92</source-ip>
         <log-creation>2020-11-01T06:47:59Z</log-creation>
         <request>User-logged-out</request>
         <outcome>true</outcome>
       </audit-log>
       <audit-log>
         <source-ip>192.168.0.92</source-ip>
         <log-creation>2020-11-01T06:49:03Z</log-creation>
         <request>User-logged-in</request>
         <outcome>true</outcome>
       </audit-log>
       <audit-log>
         <source-ip>192.168.0.92</source-ip>
         <log-creation>2020-11-01T06:51:34Z</log-creation>
         <request>Patron-card-viewed</request>
         <outcome>false</outcome>
       </audit-log>
       <audit-log>
         <source-ip>192.168.0.92</source-ip>



Watsen, et al.             Expires May 6, 2021                 [Page 26]


Internet-Draft         NETCONF Pagination Support          November 2020


         <log-creation>2020-11-01T06:53:01Z</log-creation>
         <request>User-logged-out</request>
         <outcome>true</outcome>
       </audit-log>
       <audit-log>
         <source-ip>192.168.0.92</source-ip>
         <log-creation>2020-11-01T06:56:22Z</log-creation>
         <request>User-logged-in</request>
         <outcome>false</outcome>
       </audit-log>
     </audit-logs>
     <prefixes  xmlns="http://example.com/ns/example-module">
       <prefix-list>
         <ip-prefix>10.0.0.0 8</ip-prefix>
         <masklength-lower>17</masklength-lower>
         <masklength-upper>18</masklength-upper>
       </prefix-list>
       <prefix-list>
         <ip-prefix>2000:1::</ip-prefix>
         <masklength-lower>48</masklength-lower>
         <masklength-upper>48</masklength-upper>
       </prefix-list>
       <prefix-list>
         <ip-prefix>2000:2::</ip-prefix>
         <masklength-lower>48</masklength-lower>
         <masklength-upper>48</masklength-upper>
       </prefix-list>
       <prefix-list>
         <ip-prefix>2000:3::</ip-prefix>
         <masklength-lower>16</masklength-lower>
         <masklength-upper>16</masklength-upper>
       </prefix-list>
       <prefix-list>
         <ip-prefix>::</ip-prefix>
         <masklength-lower>0</masklength-lower>
         <masklength-upper>128</masklength-upper>
       </prefix-list>
     </prefixes>

Appendix C.  NETCONF YANG Collection Examples

   The examples within this document use the "example-module" YANG
   module defined in Appendix A.








Watsen, et al.             Expires May 6, 2021                 [Page 27]


Internet-Draft         NETCONF Pagination Support          November 2020


C.1.  "count" Parameter

   In this example, the client requests the first two "skill" resources
   for a given admin resource:

Request from NETCONF client
<netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
       <datastore>running</datastore>
       <list-target>admins/admin[name=Bob]/skill</list-target>
       <count>2</count>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.2.  "skip" Parameter

   In this example, the client requests the next two skills resource,
   i.e., two skills resource starting from two.














Watsen, et al.             Expires May 6, 2021                 [Page 28]


Internet-Draft         NETCONF Pagination Support          November 2020


    Request from NETCONF client
   <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
      <datastore>running</datastore>
     <list-target>admins/admin[name=Bob]/skill </list-target>
     <count>2</count>
     <skip>2</skip>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.3.  "direction" Parameter

   In this example, the client requests the first two "skill" resources
   in the forward direction for a given admin:


















Watsen, et al.             Expires May 6, 2021                 [Page 29]


Internet-Draft         NETCONF Pagination Support          November 2020


Request from NETCONF client
  <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
     <datastore>running</datastore>
     <list-target>admins/admin[name=Bob]/skill </list-target>
     <count>2</count>
     <direction>forward</direction>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.4.  "sort" Parameter

   In this example, the client requests the first 3 "skill" resources
   sorted by name for a given admin:


















Watsen, et al.             Expires May 6, 2021                 [Page 30]


Internet-Draft         NETCONF Pagination Support          November 2020


   Request from NETCONF client
    <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
       <datastore>running</datastore>
       <list-target>admins/admin[name=Bob]/skill </list-target>
       <count>2</count>
       <sort>name</sort>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
        <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.5.  Combination of "where" and "count" Parameters

   In this example, the client requests the first 2 "skill" resources
   from the selected skill resource list for a given admin:


















Watsen, et al.             Expires May 6, 2021                 [Page 31]


Internet-Draft         NETCONF Pagination Support          November 2020


   Request from NETCONF client
    <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <datastore>running</datastore>
       <list-target>admins/admin[name=Bob]/skill </list-target>
       <count>2</count>
       <where>position>=2 and position<=9</where>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
        <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.6.  Combination of "where", "count" and "skip" Parameters

   In this example, the client requests the first 2 "skill" resources
   from the selected "skill" resource list for a given admin:


















Watsen, et al.             Expires May 6, 2021                 [Page 32]


Internet-Draft         NETCONF Pagination Support          November 2020


   Request from NETCONF client
   <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
      <datastore>running</datastore>
       <list-target> admins/admin[name=Bob]/skill </list-target>
       <count>2</count>
       <skip>2</skip>
       <where>position>=2 and position<=9</where>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

C.7.  Combination of "where", "count","skip" and "sort" Parameters

   In this example, the client requests the first 2 "skill" resources
   from the selected skill resources list for a given admin:

















Watsen, et al.             Expires May 6, 2021                 [Page 33]


Internet-Draft         NETCONF Pagination Support          November 2020


   Request from NETCONF client
    <netconf:rpc netconf:message-id="101"
                xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
      <get-pageable-list
          xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
       <datastore>running</datastore>
       <list-target> admins/admin[name=Bob]/skill </list-target>
       <count>2</count>
       <skip>2</skip>
       <sort>name</sort>
       <where>[position>=2 and position<=9]</where>
      </get-pageable-list>
    </netconf:rpc>

   Response from NETCONF server
      <netconf:rpc-reply netconf:message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
        <pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
        <skill xmlns="http://example.com/ns/example-module">
          <name>Problem Solving</name>
          <rank>98</rank>
          ...
        </skill>
        <skill xmlns="http://example.com/ns/example-module">
          <name>Conflict Resolution</name>
          <rank>93</rank>
          ...
        </skill>
      </pageable-list>
     </netconf:rpc-reply>

Acknowledgements

   This work has benefited from the discussions of restconf resource
   collection over the years, in particular, [I-D.ietf-netconf-restconf-
   collection] which provides enhanced filtering features for the
   retrieval of data nodes with the GET method and [I-D.zheng-netconf-
   fragmentation] which document large size data handling challenge.
   The authors would like to thank the following for lively discussions
   on list:

   Andy Bierman
   Martin Bjoerklund
   Robert Varga







Watsen, et al.             Expires May 6, 2021                 [Page 34]


Internet-Draft         NETCONF Pagination Support          November 2020


Authors' Addresses

   Kent Watsen
   Watsen Network

   EMail: kent+ietf@watsen.net


   Qin Wu
   Huawei
   101 Software Avenue, Yuhua District
   Nanjing, Jiangsu  210012
   China

   EMail: bill.wu@huawei.com


   Olof Hagsand
   Netgate

   EMail: olof@hagsand.se


   Hongwei Li
   HPE

   EMail: flycoolman@gmail.com
























Watsen, et al.             Expires May 6, 2021                 [Page 35]