Registration Data Access Protocol (RDAP) Query Parameters for Result Sorting and Paging
Extracted elements (30)
Query parameters were chosen over HTTP headers for sorting and paging because headers cannot be set directly from a web browser, conflate session state with resource identification, and require clients to have prior knowledge of the server implementation—a recognized REST anti-pattern.
Sorting properties are defined as short human-readable names (e.g., 'registrationDate', 'name') rather than JSONPath expressions because JSONPath is verbose and difficult to use in query strings; the 'jsonPath' field in sorting_metadata provides the mapping for clients that need it.
The 'cursor' parameter is defined as an opaque, server-defined string so that RDAP providers can choose (or change) their pagination method—offset or keyset—according to their needs, access levels, and query type, without announcing changes to clients.
The specification adopts forward-only pagination in 'paging_metadata' links because forward traversal alone is sufficient to scroll the entire result set, keeping the pagination model simple and avoiding the complexity of bidirectional keyset navigation.
Servers must signal support for paging or sorting via the rdapConformance array ('paging' or 'sorting' string literals), following the extension conformance mechanism established by RFC 7483 for RDAP JSON responses.
The new 'count', 'sort', and 'cursor' parameters are OPTIONAL extensions of existing RDAP search path segments defined in RFC 7482; servers not supporting them remain compliant with the base RDAP specification.
A trueValue in the 'count' parameter means the server MUST provide the total number of objects in the 'totalCount' field of 'paging_metadata'. A falseValue means the server MUST NOT provide this number.
An RDAP server MUST define only one default sorting property for each object class, indicated by the 'default' boolean in each AvailableSort object.
An RDAP server MUST NOT use the defined sorting properties with a meaning other than that described in Table 1 of the specification.
An RDAP server SHOULD use the 'links' array of the 'paging_metadata' element to provide a ready-made RFC 8288 reference to the next page of the result set.
Each request including an invalid parameter value SHOULD produce an HTTP 400 (Bad Request). This also applies when the client provides an unsupported or object-mismatched sort property, or an invalid cursor value.
For domain and nameserver name sorting, if unicodeName is present it MUST be used; when unavailable, ldhName MUST be used. The jCard 'sort-as' parameter MUST be ignored for the sorting capability described in this document.
For multivalued entity sorting properties, sorting MUST be applied to the preferred value identified by pref="1". If the 'pref' parameter is missing, sorting MUST be applied to the first value.
If a 'sort' parameter presents an allowed sorting property, it MUST be provided in the 'currentSort' field of the 'sorting_metadata' element.
If the sort direction is absent in a sort parameter, an ascending sort MUST be applied. 'a' mandates ascending and 'd' mandates descending sort.
In sorting links, the 'value', 'rel', and 'href' JSON values MUST be specified. All other JSON values are OPTIONAL.
RDAP servers are NOT RECOMMENDED to obfuscate the 'cursor' value through mere base64 encoding, as this provides only superficial obfuscation.
RDAP servers implementing these query parameters SHOULD provide 'sorting_metadata' and 'paging_metadata' response elements so clients can discover available sorting criteria and pagination links without prior server knowledge.
Servers MUST implement sorting according to JSON value type: strings MUST be sorted lexicographically, numbers numerically, dates and times in chronological order, and IP address strings MUST be sorted by their numeric conversion.
Servers returning the 'paging_metadata' element MUST include the string literal 'paging' in the rdapConformance array. Servers returning 'sorting_metadata' MUST include 'sorting'.
The 'totalCount' field MUST be provided if and only if the query string contains the 'count' parameter. 'pageSize' and 'pageNumber' MUST be provided if and only if the total number of objects exceeds the page size.
When multiple events with a given action exist on an object, sorting MUST be applied to the most recent event. When a nameserver has multiple addresses per IP version, sorting MUST be applied to the first value.
The 'count' query parameter allows a client to request the total number of objects matching a search pattern. It accepts trueValue ('true', 'yes', '1') or falseValue ('false', 'no', '0'). ABNF: count = "count=" ( trueValue / falseValue ).
The 'cursor' parameter is an opaque string representing a pointer to a specific fixed-size portion of the result set, enabling pagination. ABNF: cursor = "cursor=" 1*( ALPHA / DIGIT / "/" / "=" / "-" / "_" ). Its internal encoding is server-defined.
The 'paging_metadata' response element contains 'totalCount' (numeric, conditional), 'pageSize' (numeric, conditional), 'pageNumber' (numeric, conditional), and 'links' (optional Link array with RFC 8288 references to the next page and optionally first/last/prev).
The 'sort' query parameter allows a client to specify one or more properties and sort directions for the result set. ABNF: sort = "sort=" sortItem *( "," sortItem ); sortItem = property-ref [":" ( "a" / "d" )]. 'a' indicates ascending, 'd' descending.
The 'sorting_metadata' response element contains 'currentSort' (optional string) and 'availableSorts' (optional array of AvailableSort objects). At least one of 'currentSort' or 'availableSorts' MUST be present. Each AvailableSort includes 'property' (required), 'default' (required boolean), 'jsonPath' (optional), and 'links' (optional).
IANA has registered two new values in the 'RDAP Extensions' registry: extension identifier 'paging' (for result set paging) and 'sorting' (for result set sorting), both applicable to any registry operator and defined by RFC 8977.
Search queries require significantly more server resources than lookup queries, increasing the risk of resource exhaustion and denial of service. Mitigation strategies include restricting search functionality, rate-limiting, and truncating results.
The 'count', 'sort', and 'cursor' parameters collectively reduce inefficiency risks from large result sets: 'count' lets clients evaluate response completeness, 'sort' surfaces the most relevant results first, and 'cursor' enables controlled traversal within server-acceptable query limits.