YANG list pagination: a cursor is not a snapshot

Summary

Revision 13 defines a clear query sequence—filter, sort, locale, direction, offset or cursor, and page limits—and lets servers describe constrained, indexed and cursor-capable nodes.
The resulting receipts prove how a page was requested and continued. They do not prove that successive pages share one authorization view, one collation implementation, one operational-data snapshot or one complete nested result.

A cursor is reassuring because it arrives from the server. It looks less fragile than an offset and more deliberate than “give me the next hundred”. In draft-ietf-netconf-list-pagination-13, that confidence has a legitimate basis: the cursor is opaque to the client, represents an underlying-system index or key, and carries a request into the next or previous page without asking the client to reconstruct the position.

But a position and a moment are different things. A train ticket can preserve a seat number while the passengers change. A database key can still identify a boundary while objects are inserted before it, deleted after it, reclassified by access policy, or reordered by an updated collation rule. The central operational question is therefore not whether the cursor is valid. It is what remained invariant while the cursor was used.

Revision 13 was posted on 6 July 2026. The IETF Datatracker lists it as an active NETCONF Working Group Internet-Draft intended for the Standards Track, with Working Group state In WG Last Call, a Revised I-D Needed - Issue raised by WGLC tag and IESG state I-D Exists. Its current YANG-validation panel reports three errors; the visible pyang and yanglint messages point around the same escaped line wrapping in the module text. That is evidence about the document and the tools examining it. It is not evidence that a server implementation, a deployment or a returned page is broken.

The request has an order

The draft’s most useful discipline is its processing sequence. A server first evaluates where, then applies sort-by; locale supplies the collation context. It then applies direction together with either offset or cursor, and finally limit. sublist-limit has a different job: it constrains descendant lists and leaf-lists rather than the target collection itself.

Each parameter answers a different question. where establishes membership under an XPath 1.0 expression. sort-by chooses a YANG child as the primary key. locale tells the server which linguistic ordering context applies. direction chooses forward or backward traversal. offset skips a number of entries; cursor resumes from an opaque position. limit caps the top-level page. sublist-limit prevents one returned object from bringing an unbounded nested collection with it.

Revision 13 sharpens cursor initialization. where, sort-by and locale are supplied when the cursor value is first. The server’s continuation links preserve that initial query, and later cursor requests may vary only limit and sublist-limit. This blocks a client from quietly changing the predicate or ordering halfway through a cursor traversal and still calling the result one sequence.

That is query-context integrity. It is not dataset immutability. The draft does not define a read timestamp, snapshot identifier, transaction number, revision vector or barrier across contributing backends. The next request can repeat the same query faithfully against a changed world.

Sorting can be precise without being total

Sorting exposes another boundary. If sort-by is absent, the YANG list’s own ordering applies. If it is present, entries with no value for the selected child come after entries that have one. locale is invalid without sort-by; when the client omits a locale, the server selects one and returns the choice as YANG metadata. That gives an evidence system something concrete to record instead of silently inheriting a machine default.

Yet the draft does not define sub-sorts. Two interfaces can share the same name, two routes can share the same metric, or two inventory records can have equal timestamps. A page boundary that falls inside those ties needs an implementation-specific discriminator. If that discriminator changes after a restart, differs between shards, or is not returned to the client, “sorted by name” does not prove a stable total order.

Locale adds a second source of movement. A reported BCP 47 language tag identifies the collation context, but it does not identify the collation library, Unicode data version, normalization choices or tie-breaking behavior. Federated systems can accept the same locale and still order equivalent-looking strings differently. To reproduce the result, an operator may need the backend identities and their concrete collation versions, not just the language tag.

Capability metadata is a declaration

For config false lists, cost and volatility matter. Revision 13 lets a server use the RFC 9196 system-capabilities model to mark a node constrained, identify indexed children and say whether cursor-supported is available. On a constrained list, arbitrary XPath handling can be disabled; filtering and sorting are limited to indexed nodes, and expressions cannot descend through sublists.

This is good negotiation. A client can avoid an expensive query that the server has declared it cannot support. It can choose a cursor only where that capability is advertised. It can bind a request to the RFC 8525 YANG Library content identity and the capability set it observed.

None of those records proves that the runtime used the advertised index, that the index was current, or that every data source feeding the operational view had reached the same point. RFC 9196 itself allows capabilities to depend on runtime circumstances such as hardware or licensing. RFC 8525’s content-id identifies the content of the YANG Library; it is not a snapshot identifier for the data represented by those modules.

The distinction is simple but consequential: a schema says what can be represented; a capability says what a server says it can do; a request log says what was asked; a response says what was returned. None can silently substitute for the others.

Authorization changes the population

RFC 8341 NACM can restrict the operations and data visible to a principal. The same where expression can therefore operate over different populations for different users. More subtly, the same user can see a different population on page two if group membership, rules or object permissions change between requests.

The published BTW article on RFC 9865 SCIM cursor pagination owns the specific security question of whether possession of a cursor preserves authorization. This YANG case has a different center. Even when every continuation is freshly authorized, a changed NACM view can add or remove records relative to the cursor boundary. A valid, authorized second page may be individually correct while the union of pages is not a coherent inventory.

Evidence must bind each request to the authenticated principal, the effective NACM policy identity and the resulting view. If the policy changes, the honest description is “pages observed under two views”, not “one complete list”. That is not an argument for freezing permission changes. It is an argument for preventing a reporting system from hiding them.

Operational data does not wait for the reader

The strongest challenge appears in config false data. RFC 8342’s operational datastore includes applied configuration and system state, potentially assembled from multiple origins. Interfaces flap, counters advance, routes converge, leases expire, and topology records arrive at different times. Pagination makes that moving surface manageable; it does not stop it moving.

Suppose page one ends at sort key m. Before page two begins, an object originally before m changes its key to z. It can appear again. An object after m can change to a and disappear from the traversal. A deletion can make an offset skip too far; an insertion can make it repeat an entry. A cursor tied to a stable object key can reduce some offset pathologies, but it cannot freeze unrelated objects or guarantee that a federated operational view shares a common observation time.

The RESTCONF companion makes the boundary especially clear: the server does not retain stateful information about the next or previous cursor or page. The link preserves a continuation instruction, not a reserved result set. This statelessness is operationally attractive, but it removes any excuse to treat the link itself as a snapshot receipt.

A page can be complete while its objects are truncated

limit and sublist-limit should never be collapsed. The former limits entries in the target collection. The latter limits descendant collections returned inside each entry. A server can annotate remaining with a positive count or unknown; descendant lists can carry their own remaining annotations.

A client might therefore retrieve every top-level device while receiving only the first ten interfaces per device. If it stores “device page complete” and discards the descendant continuation, the data product is incomplete even though top-level pagination succeeded. remaining: unknown is also a truthful statement of uncertainty, not a disguised zero.

Nested evidence needs a tree rather than a single chain. Each truncated child collection requires its own parent identity, query context, cursor lineage, response hash and reconciliation result. A top-level cursor cannot attest for every branch below it.

What a defensible evidence envelope contains

An operator can strengthen this mechanism without pretending the draft already requires a snapshot service. For each request, retain the principal and NACM-policy identity; datastore; YANG Library content identity; capability-set identity; exact where, sort-by, locale, direction, positioning parameter, limit and sublist-limit; request and response hashes; cursor lineage; returned object keys and sort values; remaining annotations; server time; contributing backend identities; and every error.

Then create a separate assembly record. It should detect repeated keys, unexpected gaps and boundary inversions; record capability or policy changes; compare the last ordering tuple of one page with the first of the next; preserve any backend revision or snapshot identifiers that do exist; and state whether the result is a frozen snapshot, a bounded-consistency read or a traversal over changing observations.

This recommendation does not turn every changing list into a failure. Real-time operational data often cannot or should not be frozen. The purpose is semantic honesty. A route inventory observed over forty seconds can still be useful if the evidence describes the interval, origin and reconciliation method. It becomes dangerous when a polished export labels that interval as one instantaneous and complete state.

The cursor’s achievement is narrower and more valuable than the overclaim. It knows where the next request should continue under a preserved query context. It does not know whether the world on the other side is the same world the previous request saw.

Primary sources

The Cursor Knew the Position. It Did Not Know the Moment

Why it matters

Summary

The request has an order

Sorting can be precise without being total

Capability metadata is a declaration

Authorization changes the population

Operational data does not wait for the reader

A page can be complete while its objects are truncated

What a defensible evidence envelope contains

Primary sources

Deeper Profile Context

Strategic Circle

Leadership Alliance

Strategic Circle Briefing

Leadership Alliance Briefing