]> List Pagination for YANG-driven Protocols Watsen Networks
kent+ietf@watsen.net
Huawei Technologies
bill.wu@huawei.com
Netgate
olof@hagsand.se
Hewlett Packard Enterprise
flycoolman@gmail.com
Cisco Systems
perander@cisco.com
OPS Area NETCONF Working Group In some circumstances, instances of YANG modeled "list" and "leaf-list" nodes may contain numerous entries. Retrieval of all the entries can lead to inefficiencies in the server, the client, and the network in between. This document defines a model for list pagination that can be implemented by YANG-driven management protocols such as NETCONF and RESTCONF. The model supports paging over optionally filtered and/or sorted entries. The solution additionally enables servers to constrain query expressions on some "config false" lists or leaf-lists.
Introduction YANG modeled "list" and "leaf-list" nodes may contain a large number of entries. For instance, there may be thousands of entries in the configuration for network interfaces or access control lists. And time-driven logging mechanisms, such as an audit log or a traffic log, can contain millions of entries. Retrieval of all the entries can lead to inefficiencies in the server, the client, and the network in between. For instance, consider the following:
  • A client may need to filter and/or sort list entries in order to, e.g., present the view requested by a user.
  • A server may need to iterate over many more list entries than needed by a client.
  • A network may need to convey more data than needed by a client.
Optimal global resource utilization is obtained when clients are able to cherry-pick just that which is needed to support the application-level business logic. This document defines a generic model for list pagination that can be implemented by YANG-driven management protocols such as NETCONF and RESTCONF . Details for how such protocols are updated are outside the scope of this document. The model presented in this document supports paging over optionally filtered and/or sorted entries. Server-side filtering and sorting is ideal as servers can leverage indexes maintained by a backend storage layer to accelerate queries.
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 when, and only when, they appear in all capitals, as shown here. The following terms are defined in and are not redefined here: client, data model, data tree, feature, extension, module, leaf, leaf-list, and server.
Conventions Various examples used in this document use a placeholder value for binary data that has been base64 encoded (e.g., "BASE64VALUE="). This placeholder value is used as real base64 encoded structures are often many lines long and hence distracting to the example being presented.
Adherence to the NMDA This document is compliant with the Network Management Datastore Architecture (NMDA) . The "ietf-list-pagination" module only defines a YANG extension and augments a couple leafs into a "config false" node defined by the "ietf-system-capabilities" module.
Solution Overview The solution presented in this document broadly entails a client sending a query to a server targeting a specific list or leaf-list including optional parameters guiding which entries should be returned. A secondary aspect of this solution entails a client sending a query parameter to a server guiding how descendent lists and leaf-lists should be returned. This parameter may be used on any target node, not just "list" and "leaf-list" nodes. Clients detect a server's support for list pagination via an entry for the "ietf-list-pagination" module (defined in ) in the server's YANG Library response. Relying on client-provided query parameters ensures servers remain backward compatible with legacy clients.
Solution Details This section is composed of the following subsections:
  • defines five query parameters clients may use to page through the entries of a single list or leaf-list in a data tree.
  • defines one query parameter that clients may use to affect the content returned for descendant lists and leaf-lists.
  • defines per schema-node tags enabling servers to indicate which "config false" lists are constrained and how they may be interacted with.
Query Parameters for a Targeted List or Leaf-List The five query parameters presented this section are listed in processing order. This processing order is logical, efficient, and matches the processing order implemented by database systems, such as SQL. The order is as follows: a server first processes the "where" parameter (see ), then the "sort-by" parameter (see ), then the "direction" parameter (see ), and either a combination of the "offset" parameter (see ) or the "cursor" parameter (see ), and lastly "the "limit" parameter (see ).
The "where" Query Parameter
Description
The "where" query parameter specifies a filter expression that result-set entries must match.
Default Value
If this query parameter is unspecified, then no entries are filtered from the working result-set.
Allowed Values
The allowed values are XPath 1.0 expressions. It is an error if the XPath expression references a node identifier that does not exist in the schema, is optional or conditional in the schema or, for constrained "config false" lists and leaf-lists (see ), if the node identifier does not point to a node having the "indexed" extension statement applied to it (see ).
Conformance
The "where" query parameter MUST be supported for all "config true" lists and leaf-lists and SHOULD be supported for "config false" lists and leaf-lists. Servers MAY disable the support for some or all "config false" lists and leaf-lists as described in .
The "sort-by" Query Parameter
Description
The "sort-by" query parameter indicates the node in the working result-set (i.e., after the "where" parameter has been applied) that entries should be sorted by. Sorts are in ascending order (e.g., '1' before '9', 'a' before 'z', etc.). Missing values are sorted to the end (e.g., after all nodes having values). Sub-sorts are not supported.
Default Value
If this query parameter is unspecified, then the list or leaf-list's default order is used, per the YANG "ordered-by" statement (see ).
Allowed Values
The allowed values are node identifiers. It is an error if the specified node identifier does not exist in the schema, is optional or conditional in the schema or, for constrained "config false" lists and leaf-lists (see ), if the node identifier does not point to a node having the "indexed" extension statement applied to it (see ).
Conformance
The "sort-by" query parameter MUST be supported for all "config true" lists and leaf-lists and SHOULD be supported for "config false" lists and leaf-lists. Servers MAY disable the support for some or all "config false" lists and leaf-lists as described in .
The "direction" Query Parameter
Description
The "direction" query parameter indicates how the entries in the working result-set (i.e., after the "sort-by" parameter has been applied) should be traversed.
Default Value
If this query parameter is unspecified, the default value is "forwards".
Allowed Values
The allowed values are:
forwards
Return entries in the forwards direction. Also known as the "default" or "ascending" direction.
backwards
Return entries in the backwards direction. Also known as the "reverse" or "descending" direction
Conformance
The "direction" query parameter MUST be supported for all lists and leaf-lists.
The "offset" Query Parameter
Description
The "offset" query parameter indicates the number of entries in the working result-set (i.e., after the "direction" parameter has been applied) that should be skipped over when preparing the response.
Default Value
If this query parameter is unspecified, then no entries in the result-set are skipped, same as when the offset value '0' is specified.
Allowed Values
The allowed values are unsigned integers. It is an error for the offset value to exceed the number of entries in the working result-set, and the "offset-out-of-range" identity SHOULD be produced in the error output when this occurs.
Conformance
The "offset" query parameter MUST be supported for all lists and leaf-lists.
The "cursor" Query Parameter
Description
The "cursor" query parameter indicates where to start the working result-set (i.e., after the "direction" parameter has been applied), the elements before the cursor are skipped over when preparing the response. Furthermore the result-set is annotated with attributes for the next and previous cursors following a result-set constrained with the "limit" query parameter.
Default Value
If this query parameter is unspecified, then no entries in the result-set are skipped.
Allowed Values
The allowed values are base64 encoded positions interpreted by the server to index an element in the list. It is an error to supply an unkown cursor for the working result-set, and the "cursor-not-found" identity SHOULD be produced in the error output when this occurs.
Conformance
The "cursor" query parameter MUST be supported for all lists.
The "limit" Query Parameter
Description
The "limit" query parameter limits the number of entries returned from the working result-set (i.e., after the "offset" parameter has been applied). Any list or leaf-list that is limited includes, somewhere in its encoding, a metadata value called "remaining", a positive integer indicating the number of elements that were not included in the result-set by the "limit" operation, or the value "unknown" in case, e.g., the server determines that counting would be prohibitively expensive.
Default Value
If this query parameter is unspecified, the number of entries that may be returned is unbounded.
Allowed Values
The allowed values are positive integers.
Conformance
The "limit" query parameter MUST be supported for all lists and leaf-lists.
Query Parameter for Descendant Lists and Leaf-Lists Whilst this document primarily regards pagination for a list or leaf-list, it begs the question for how descendant lists and leaf-lists should be handled, which is addressed by the "sublist-limit" query parameter described in this section.
The "sublist-limit" Query Parameter
Description
The "sublist-limit" parameter limits the number of entries returned for descendent lists and leaf-lists. Any descendent list or leaf-list limited by the "sublist-limit" parameter includes, somewhere in its encoding, a metadata value called "remaining", a positive integer indicating the number of elements that were not included by the "sublist-limit" parameter, or the value "unknown" in case, e.g., the server determines that counting would be prohibitively expensive. When used on a list node, it only affects the list's descendant nodes, not the list itself, which is only affected by the parameters presented in .
Default Value
If this query parameter is unspecified, the number of entries that may be returned for descendent lists and leaf-lists is unbounded.
Allowed Values
The allowed values are positive integers.
Conformance
The "sublist-limit" query parameter MUST be supported for all conventional nodes, including a datastore's top-level node (i.e., '/').
Constraints on "where" and "sort-by" for "config false" Lists Some "config false" lists and leaf-lists may contain an enormous number of entries. For instance, a time-driven logging mechanism, such as an audit log or a traffic log, can contain millions of entries. In such cases, "where" and "sort-by" expressions will not perform well if the server must bring each entry into memory in order to process it. The server's best option is to leverage query-optimizing features (e.g., indexes) built into the backend database holding the dataset. However, arbitrary "where" expressions and "sort-by" node identifiers into syntax supported by the backend database and/or query-optimizers may prove challenging, if not impossible, to implement. Thusly this section introduces mechanisms whereby a server can:
  1. Identify which "config false" lists and leaf-lists are constrained.
  2. Identify what node-identifiers and expressions are allowed for the constrained lists and leaf-lists.
Identifying Constrained "config false" Lists and Leaf-Lists Identification of which lists and leaf-lists are constrained occurs in the schema tree, not the data tree. However, as server abilities vary, it is not possible to define constraints in YANG modules defining generic data models. In order to enable servers to identify which lists and leaf-lists are constrained, the solution presented in this document augments the data model defined by the "ietf-system-capabilities" module presented in . Specifically, the "ietf-list-pagination" module (see ) augments an empty leaf node called "constrained" into the "per-node-capabilities" node defined in the "ietf-system-capabilities" module. The "constrained" leaf MAY be specified for any "config false" list or leaf-list. When a list or leaf-list is constrained:
  • All parts of XPath 1.0 expressions are disabled unless explicitly enabled by .
  • Node-identifiers used in "where" expressions and "sort-by" filters MUST have the "indexed" leaf applied to it (see ).
  • For lists only, node-identifiers used in "where" expressions and "sort-by" filters MUST NOT descend past any descendent lists. This ensures that only indexes relative to the targeted list are used. Further constraints on node identifiers MAY be applied in .
Indicating the Constraints for "where" Filters and "sort-by" Expressions This section identifies how constraints for "where" filters and "sort-by" expressions are specified. These constraints are valid only if the "constrained" leaf described in the previous section has been set on the immediate ancestor "list" node or, for "leaf-list" nodes, on itself.
Indicating Filterable/Sortable Nodes For "where" filters, an unconstrained XPath expressions may use any node in comparisons. However, efficient mappings to backend databases may support only a subset of the nodes. Similarly, for "sort-by" expressions, efficient sorts may only support a subset of the nodes. In order to enable servers to identify which nodes may be used in comparisons (for both "where" and "sort-by" expressions), the "ietf-list-pagination" module (see ) augments an empty leaf node called "indexed" into the "per-node-capabilities" node defined in the "ietf-system-capabilities" module (see ). When a "list" or "leaf-list" node has the "constrained" leaf, only nodes having the "indexed" node may be used in "where" and/or "sort-by" expressions. If no nodes have the "indexed" leaf, when the "constrained" leaf is present, then "where" and "sort-by" expressions are disabled for that list or leaf-list.
The "ietf-list-pagination" Module The "ietf-list-pagination" module is used by servers to indicate that they support pagination on YANG "list" and "leaf-list" nodes, and to provide an ability to indicate which "config false" list and/or "leaf-list" nodes are constrained and, if so, which nodes may be used in "where" and "sort-by" expressions.
Data Model Overview The following tree diagram illustrates the "ietf-list-pagination" module: Comments:
  • As shown, this module augments two optional leaves into the "node-selector" node of the "ietf-system-capabilities" module.
  • Not shown is that the module also defines an "md:annotation" statement named "remaining". This annotation may be present in a server's response to a client request containing either the "limit" () or "sublist-limit" parameters ().
Example Usage
Constraining a "config false" list The following example illustrates the "ietf-list-pagination" module's augmentations of the "system-capabilities" data tree. This example assumes the "example-social" module defined in the is implemented. ds:operational /es:audit-logs/es:audit-log /es:audit-logs/es:audit-log/es:timestamp /es:audit-logs/es:audit-log/es:member-id /es:audit-logs/es:audit-log/es:outcome ]]>
Indicating number remaining in a limited list FIXME: valid syntax for 'where'?
YANG Module This YANG module has normative references to and . <CODE BEGINS> file "ietf-list-pagination@2023-03-11.yang" "; description "This module is used by servers to 1) indicate they support pagination on 'list' and 'leaf-list' resources, 2) define a grouping for each list-pagination parameter, and 3) indicate which 'config false' lists have constrained 'where' and 'sort-by' parameters and how they may be used, if at all. Copyright (c) 2022 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 Revised 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 XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. 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."; revision 2023-03-11 { description "Initial revision."; reference "RFC XXXX: List Pagination for YANG-driven Protocols"; } // Annotations md:annotation remaining { type union { type uint32; type enumeration { 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 (a positive value) due to 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'. The maximum value (2^32-1) is reserved to represent any value greater than or equal to 2^32-1 elements."; } // Identities identity list-pagination-error { description "Base identity for list-pagination errors."; } identity offset-out-of-range { base list-pagination-error; description "The 'offset' query parameter value is greater than the number of instances in the target list or leaf-list resource."; } identity cursor-not-found { base list-pagination-error; description "The 'cursor' query parameter value is unknown for the target list."; } // Groupings grouping where-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf where { type union { type yang:xpath1.0; type enumeration { enum "unfiltered" { description "Indicates that no entries are to be filtered from the working result-set."; } } } default "unfiltered"; description "The 'where' parameter specifies a boolean expression that result-set entries must match. It is an error if the XPath expression references a node identifier that does not exist in the schema, is optional or conditional in the schema or, for constrained 'config false' lists and leaf-lists, if the node identifier does not point to a node having the 'indexed' extension statement applied to it (see RFC XXXX)."; } } grouping sort-by-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf sort-by { type union { type string { // An RFC 7950 'descendant-schema-nodeid'. pattern '([0-9a-fA-F]*:)?[0-9a-fA-F]*' + '(/([0-9a-fA-F]*:)?[0-9a-fA-F]*)*'; } type enumeration { enum "none" { description "Indicates that the list or leaf-list's default order is to be used, per the YANG 'ordered-by' statement."; } } } default "none"; description "The 'sort-by' parameter indicates the node in the working result-set (i.e., after the 'where' parameter has been applied) that entries should be sorted by. Sorts are in ascending order (e.g., '1' before '9', 'a' before 'z', etc.). Missing values are sorted to the end (e.g., after all nodes having values)."; } } grouping direction-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf direction { type enumeration { enum forwards { description "Indicates that entries should be traversed from the first to last item in the working result set."; } enum backwards { description "Indicates that entries should be traversed from the last to first item in the working result set."; } } default "forwards"; description "The 'direction' parameter indicates how the entries in the working result-set (i.e., after the 'sort-by' parameter has been applied) should be traversed."; } } grouping cursor-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf cursor { type string; description "The 'cursor' parameter indicates where to start the working result-set (i.e. after the 'direction' parameter has been applied), the elements before the cursor are skipped over when preparing the response. Furthermare the result-set is annotated with attributes for the next and previous cursors following a result-set constrained with the 'limit' query parameter."; } } grouping offset-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf offset { type uint32; default 0; description "The 'offset' parameter indicates the number of entries in the working result-set (i.e., after the 'direction' parameter has been applied) that should be skipped over when preparing the response."; } } grouping limit-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf limit { type union { type uint32 { range "1..max"; } type enumeration { enum "unbounded" { description "Indicates that the number of entries that may be returned is unbounded."; } } } default "unbounded"; description "The 'limit' parameter limits the number of entries returned from the working result-set (i.e., after the 'offset' parameter has been applied). Any result-set that is limited includes, somewhere in its encoding, the metadata value 'remaining' to indicate the number entries not included in the result set."; } } grouping sublist-limit-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf sublist-limit { type union { type uint32 { range "1..max"; } type enumeration { enum "unbounded" { description "Indicates that the number of entries that may be returned is unbounded."; } } } default "unbounded"; description "The 'sublist-limit' parameter limits the number of entries for descendent lists and leaf-lists. Any result-set that is limited includes, somewhere in its encoding, the metadata value 'remaining' to indicate the number entries not included in the result set."; } } // Protocol-accessible nodes augment // FIXME: ensure datastore == "/sysc:system-capabilities/sysc:datastore-capabilities" + "/sysc:per-node-capabilities" { description "Defines some leafs that MAY be used by the server to describe constraints imposed of the 'where' filters and 'sort-by' parameters used in list pagination queries."; leaf constrained { type empty; description "Indicates that 'where' filters and 'sort-by' parameters on the targeted 'config false' list node are constrained. If a list is not 'constrained', then full XPath 1.0 expressions may be used in 'where' filters and all node identifiers are usable by 'sort-by'."; } leaf indexed { type empty; description "Indicates that the targeted descendent node of a 'constrained' list (see the 'constrained' leaf) may be used in 'where' filters and/or 'sort-by' parameters. If a descendent node of a 'constrained' list is not 'indexed', then it MUST NOT be used in 'where' filters or 'sort-by' parameters."; } } } ]]> <CODE ENDS>
IANA Considerations
The "IETF XML" Registry This document registers one URI in the "ns" subregistry of the IETF XML Registry maintained at . Following the format in , the following registration is requested:
The "YANG Module Names" Registry This document registers one YANG module in the YANG Module Names registry maintained at . Following the format defined in , the below registration is requested:
Security Considerations
Regarding the "ietf-list-pagination" YANG Module Pursuant the template defined in ...FIXME
References Normative References Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The IETF XML Registry This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. The YANG 1.1 Data Modeling Language YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). Defining and Using Metadata with YANG This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK] Network Configuration Protocol (NETCONF) The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] RESTCONF Protocol This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). YANG Tree Diagrams This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language. Network Management Datastore Architecture (NMDA) Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. YANG Library This document describes a YANG library that provides information about the YANG modules, datastores, and datastore schemas used by a network management server. Simple caching mechanisms are provided to allow clients to minimize retrieval of this information. This version of the YANG library supports the Network Management Datastore Architecture (NMDA) by listing all datastores supported by a network management server and the schema that is used by each of these datastores.
Vector Tests This normative appendix section illustrates every notable edge condition conceived during this document's production. Test inputs and outputs are provided in a manner that is both generic and concise. Management protocol specific documents need only reproduce as many of these tests as necessary to convey pecularities presented by the protocol. Implementations are RECOMMENDED to implement the tests presented in this document, in addition to any tests that may be presented in protocol specific documents.
Example YANG Module The vector tests assume the "example-social" YANG module defined in this section. This module has been specially crafted to cover every notable edge condition, especially with regards to the types of the data nodes. Following is the tree diagram for the "example-social" module: /members/member/member-id | +--rw posts | | +--rw post* [timestamp] | | +--rw timestamp yang:date-and-time | | +--rw title? string | | +--rw body string | +--rw favorites | | +--rw uint8-numbers* uint8 | | +--rw uint64-numbers* uint64 | | +--rw int8-numbers* int8 | | +--rw int64-numbers* int64 | | +--rw decimal64-numbers* decimal64 | | +--rw bits* bits | +--ro stats | +--ro joined yang:date-and-time | +--ro membership-level enumeration | +--ro last-activity? yang:date-and-time +--ro audit-logs +--ro audit-log* [] +--ro timestamp yang:date-and-time +--ro member-id string +--ro source-ip inet:ip-address +--ro request string +--ro outcome boolean ]]> Following is the YANG for the "example-social" module:
Example Data Set The examples assume the server's operational state as follows. The data is provided in JSON only for convenience and, in particular, has no bearing on the "generic" nature of the tests themselves.
Example Queries The following sections are presented in reverse query-parameters processing order. Starting with the simplest (limit) and ending with the most complex (where). All the vector tests are presented in a protocol-independent manner. JSON is used only for its conciseness.
The "limit" Parameter Noting that "limit" must be a positive number, the edge condition values are '1', '2', num-elements-1, num-elements, and num-elements+1. These vector tests assume the target "/example-social:members/member=alice/favorites/uint8-numbers", which has six values, thus the edge condition "limit" values are: '1', '2', '5', '6', and '7'.
limit=1 REQUEST RESPONSE
limit=2 REQUEST RESPONSE
limit=5 REQUEST RESPONSE
limit=6 REQUEST RESPONSE
limit=7 REQUEST RESPONSE
The "offset" Parameter Noting that "offset" must be an unsigned number less than or equal to the num-elements, the edge condition values are '0', '1', '2', num-elements-1, num-elements, and num-elements+1. These vector tests again assume the target "/example-social:members/member=alice/favorites/uint8-numbers", which has six values, thus the edge condition "limit" values are: '0', '1', '2', '5', '6', and '7'.
offset=0 REQUEST RESPONSE
offset=1 REQUEST RESPONSE
offset=2 REQUEST RESPONSE
offset=5 REQUEST RESPONSE
offset=6 REQUEST RESPONSE
offset=7 REQUEST RESPONSE
The "cursor" Parameter Noting that "cursor" must be an base64 encoded opaque value which addresses an element in a list. These vector tests assume the target "/example-social:members/member" which has five members.
cursor=&limit=2 REQUEST RESPONSE
cursor="YWxpY2U="&limit=2 REQUEST RESPONSE
cursor="am9l"&limit=2 REQUEST RESPONSE
The "direction" Parameter Noting that "direction" is an enumeration with two values, the edge condition values are each defined enumeration. These vector tests again assume the target "/example-social:members/member=alice/favorites/uint8-numbers". The number of elements is relevant to the edge condition values.
direction=forwards REQUEST RESPONSE
direction=backwards REQUEST RESPONSE
The "sort-by" Parameter Noting that the "sort-by" parameter is a node identifier, there is not so much "edge conditions" as there are "interesting conditions". This section provides examples for some interesting conditions.
the target node's type The section provides three examples, one for a "leaf-list" and two for a "list", with one using a direct descendent and the other using an indirect descendent.
type is a "leaf-list" This example illustrates when the target node's type is a "leaf-list". Note that a single period (i.e., '.') is used to represent the nodes to be sorted. This test again uses the target "/example-social:members/member=alice/favorites/uint8-numbers", which is a leaf-list. REQUEST RESPONSE
type is a "list" and sort-by node is a direct descendent This example illustrates when the target node's type is a "list" and a direct descendent is the "sort-by" node. This vector test uses the target "/example-social:members/member", which is a "list", and the sort-by descendent node "member-id", which is the "key" for the list. REQUEST RESPONSE
type is a "list" and sort-by node is an indirect descendent This example illustrates when the target node's type is a "list" and an indirect descendent is the "sort-by" node. This vector test uses the target "/example-social:members/member", which is a "list", and the sort-by descendent node "stats/joined", which is a "config false" descendent leaf. Due to "joined" being a "config false" node, this request would have to target the "member" node in the <operational> datastore. REQUEST RESPONSE
handling missing entries The section provides one example for when the "sort-by" node is not present in the data set. FIXME: need to finish this section...
The "where" Parameter The "where" is an XPath 1.0 expression, there are numerous edge conditions to consider, e.g., the types of the nodes that are targeted by the expression.
match of leaf-list's values FIXME
match on descendent string containing a substring This example selects members that have an email address containing "@example.com". REQUEST RESPONSE
match on decendent timestamp starting with a substring This example selects members that have a posting whose timestamp begins with the string "2020". REQUEST RESPONSE
The "sublist-limit" Parameter The "sublist-limit" parameter may be used on any target node.
target is a list entry This example uses the target node '/example-social:members/member=alice' in the <intended> datastore. This example sets the sublist-limit value '1', which returns just the first entry for all descendent lists and leaf-lists. Note that, in the response, the "remaining" metadata value is set on the first element of each descendent list and leaf-list having more than one value. REQUEST Target: /example-social:members/member=alice Sublist-limit: 1 Pagination Parameters: Where: - Sort-by: - Direction: - Offset: - Limit: - ]]> RESPONSE
target is a datastore This example uses the target node <intended>. This example sets the sublist-limit value '1', which returns just the first entry for all descendent lists and leaf-lists. Note that, in the response, the "remaining" metadata value is set on the first element of each descendent list and leaf-list having more than one value. REQUEST Target: / Sublist-limit: 1 Pagination Parameters: Where: - Sort-by: - Direction: - Offset: - Limit: - ]]> RESPONSE
Combinations of Parameters
All six parameters at once REQUEST Target: /example-social:members/member Sublist-limit: 1 Pagination Parameters: Where: //stats//joined[starts-with(@timestamp,'2020')] Sort-by: member-id Direction: backwards Offset: 2 Limit: 2 ]]> RESPONSE
Acknowledgements The authors would like to thank the following for lively discussions on list (ordered by first name): Andy Bierman, Martin Björklund, and Robert Varga.