Diff: rfc8977xml2.original.xml

	rfc8977xml2.original.xml	rfc8977.xml
	<?xml version="1.0" encoding="UTF-8"?>	<?xml version="1.0" encoding="UTF-8"?>

	<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd"
	[
	<!ENTITY RFC2119 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
	<!ENTITY RFC5234 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml'>
	<!ENTITY RFC5890 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml'>
	<!ENTITY RFC6350 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6350.xml'>
	<!ENTITY RFC6901 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6901.xml'>
	<!ENTITY RFC7095 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7095.xml'>
	<!ENTITY RFC7230 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml'>
	<!ENTITY RFC7231 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml'>
	<!ENTITY RFC7480 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7480.xml'>
	<!ENTITY RFC7481 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7481.xml'>
	<!ENTITY RFC7482 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7482.xml'>
	<!ENTITY RFC7483 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7483.xml'>
	<!ENTITY RFC7942 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.7942.xml'>
	<!ENTITY RFC8174 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml'>
	<!ENTITY RFC8259 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.8259.xml'>
	<!ENTITY RFC8288 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.8288.xml'>
	<!ENTITY RFC8605 PUBLIC ''
	'http://xml.resource.org/public/rfc/bibxml/reference.RFC.8605.xml'>
	<!ENTITY W3C.CR-xpath-31-20161213 PUBLIC ''
	'https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/reference.W3C.CR-xpath-31-
	20161213.xml'>
	]>
	<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>


	<?rfc toc="yes"?>	<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
	<?rfc tocompact="yes"?>
	<?rfc tocdepth="4"?>	<rfc xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en" submissionType="IE
	<?rfc compact="yes"?>	TF"
	<?rfc subcompact="yes"?>	category="std" consensus="true" docName="draft-ietf-regext-rdap-sorting-and-pagi
	<?rfc sortrefs="yes"?>	ng-20"
	<?rfc symrefs="yes"?>	number="8977" updates="" obsoletes="" ipr="trust200902" tocInclude="true" tocDep
	<?rfc iprnotified="no"?>	th="4"
		sortRefs="true" symRefs="true" version="3">


	<rfc category="std" docName="draft-ietf-regext-rdap-sorting-and-paging-20" ipr=" trust200902">
	<front>	<front>
	<title abbrev="RDAP Sorting and Paging">Registration Data Access Protocol (R DAP) Query Parameters for Result Sorting and Paging</title>	<title abbrev="RDAP Sorting and Paging">Registration Data Access Protocol (R DAP) Query Parameters for Result Sorting and Paging</title>

		<seriesInfo name="RFC" value="8977"/>
	<author fullname="Mario Loffredo" initials="M." surname="Loffredo">	<author fullname="Mario Loffredo" initials="M." surname="Loffredo">
	<organization>IIT-CNR/Registro.it</organization>	<organization>IIT-CNR/Registro.it</organization>
	<address>	<address>
	<postal>	<postal>
	<street>Via Moruzzi,1</street>	<street>Via Moruzzi,1</street>
	<city>Pisa</city>	<city>Pisa</city>

	<country>IT</country>	<country>Italy</country>
	<code>56124</code>	<code>56124</code>
	</postal>	</postal>
	<email>mario.loffredo@iit.cnr.it</email>	<email>mario.loffredo@iit.cnr.it</email>

	<uri>http://www.iit.cnr.it</uri>	<uri>https://www.iit.cnr.it</uri>
	</address>	</address>
	</author>	</author>


	<author fullname="Maurizio Martinelli" initials="M." surname="Martinelli">	<author fullname="Maurizio Martinelli" initials="M." surname="Martinelli">
	<organization>IIT-CNR/Registro.it</organization>	<organization>IIT-CNR/Registro.it</organization>
	<address>	<address>
	<postal>	<postal>
	<street>Via Moruzzi,1</street>	<street>Via Moruzzi,1</street>
	<city>Pisa</city>	<city>Pisa</city>

	<country>IT</country>	<country>Italy</country>
	<code>56124</code>	<code>56124</code>
	</postal>	</postal>
	<email>maurizio.martinelli@iit.cnr.it</email>	<email>maurizio.martinelli@iit.cnr.it</email>

	<uri>http://www.iit.cnr.it</uri>	<uri>https://www.iit.cnr.it</uri>
	</address>	</address>
	</author>	</author>


	<author initials="S." surname="Hollenbeck" fullname="Scott Hollenbeck">	<author initials="S." surname="Hollenbeck" fullname="Scott Hollenbeck">
	<organization>Verisign Labs</organization>	<organization>Verisign Labs</organization>
	<address>	<address>
	<postal>	<postal>
	<street>12061 Bluemont Way</street>	<street>12061 Bluemont Way</street>
	<city>Reston</city>	<city>Reston</city>
	<region>VA</region>	<region>VA</region>
	<code>20190</code>	<code>20190</code>

	<country>USA</country>	<country>United States of America</country>
	</postal>	</postal>
	<email>shollenbeck@verisign.com</email>	<email>shollenbeck@verisign.com</email>
	<uri>https://www.verisignlabs.com/</uri>	<uri>https://www.verisignlabs.com/</uri>
	</address>	</address>
	</author>	</author>

		<date year="2021" month="January" />
	<date/>
	<area>Applications and Real-Time</area>	<area>Applications and Real-Time</area>
	<workgroup>Registration Protocols Extensions</workgroup>	<workgroup>Registration Protocols Extensions</workgroup>
	<keyword>RDAP</keyword>	<keyword>RDAP</keyword>
	<keyword>Sorting</keyword>	<keyword>Sorting</keyword>
	<keyword>Paging</keyword>	<keyword>Paging</keyword>


	<abstract>	<abstract>
	<t>The Registration Data Access Protocol (RDAP) does not include core func tionality for clients to provide sorting and paging parameters for control of la rge result sets. This omission can lead to unpredictable server processing of q ueries and client processing of responses. This unpredictability can be greatly reduced if clients can provide servers with their preferences for managing larg e responses. This document describes RDAP query extensions that allow clients t o specify their preferences for sorting and paging result sets.</t>	<t>The Registration Data Access Protocol (RDAP) does not include core func tionality for clients to provide sorting and paging parameters for control of la rge result sets. This omission can lead to unpredictable server processing of q ueries and client processing of responses. This unpredictability can be greatly reduced if clients can provide servers with their preferences for managing larg e responses. This document describes RDAP query extensions that allow clients t o specify their preferences for sorting and paging result sets.</t>
	</abstract>	</abstract>
	</front>	</front>


	<middle>	<middle>

	<section title="Introduction">	<section>
		<name>Introduction</name>
	<t>The availability of functionality for result sorting and paging provide s benefits to both clients and servers in the implementation of RESTful services <xref target="REST"/>. These benefits include:</t>	<t>The availability of functionality for result sorting and paging provide s benefits to both clients and servers in the implementation of RESTful services <xref target="REST"/>. These benefits include:</t>

		<ul>
	<t><list style="symbols">	<li>reducing the server response bandwidth requirements</li>
	<t>reducing the server response bandwidth requirements;</t>	<li>improving server response time</li>
	<t>improving server response time;</t>	<li>improving query precision and, consequently, obtaining more relevant
	<t>improving query precision and, consequently, obtaining more relevant	results</li>
	results;</t>	<li>decreasing server query processing load</li>
	<t>decreasing server query processing load;</t>	<li>reducing client response processing time</li>
	<t>reducing client response processing time.</t>	</ul>
	</list></t>

	<t>Approaches to implementing features for result sorting and paging can b e grouped into two main categories:</t>	<t>Approaches to implementing features for result sorting and paging can b e grouped into two main categories:</t>

		<ol type="1"><li>
		<t>Sorting and paging are implemented through the introduction of addi
		tional parameters in the query string (e.g., the Open Data Protocol (ODATA) <xre
		f target="ODATA-PART1"/>).</t>


	<t><list style="numbers">	</li>
	<t>sorting and paging are implemented through the introduction of addit	<li>Information related to the number of results and the specific portio
	ional parameters in the query string (e.g. ODATA protocol <xref target="OData-Pa	n of the result set to be returned, in addition to a set of ready-made links for
	rt1"/>);<vspace blankLines='1' /></t>	the result set scrolling, are inserted in the HTTP header of the request/respon
	<t>information related to the number of results and the specific portio	se <xref target="RFC7231"/>.</li>
	n of the result set to be returned, in addition to a set of ready-made links for	</ol>
	the result set scrolling, are inserted in the HTTP header of the request/respon	<t>However, there are some drawbacks associated with the use of the HTTP h
	se <xref target="RFC7231"/>.</t>	eader. First, the header properties cannot be set directly from a web browser.
	</list></t>	Moreover, in an HTTP session, the information on the status (i.e., the session
		identifier) is usually inserted in the header or a cookie, while the information
		on the resource identification or the search type is included in the query stri
		ng. Finally, providing custom information through HTTP headers assumes the clie
		nt has prior knowledge of the server implementation, which is widely considered
		a Representational State Transfer (REST) design anti-pattern. As a result, this
		document describes a specification based on the use of query parameters.</t>
		<t>Currently, RDAP <xref target="RFC7482"/> defines two query types:</t>


	<t>However, there are some drawbacks associated with the use of the HTTP h eader. First, the header properties cannot be set directly from a web browser. Moreover, in an HTTP session, the information on the status (i.e. the session i dentifier) is usually inserted in the header or a cookie, while the information on the resource identification or the search type is included in the query strin g. Finally, providing custom information through HTTP headers assumes the clien t to have a prior knowledge of the server implementation which is widely conside red a REST design anti-pattern. As a result, this document describes a specific ation based on the use of query parameters.</t>	<dl>


	<t>Currently, the RDAP protocol <xref target="RFC7482"/> defines two query	<dt>lookup:
	types:</t>	</dt>
		<dd>the server returns only one object
		</dd>


	<t><list style="symbols">	<dt>search:
	<t>lookup: the server returns only one object;</t>	</dt>
	<t>search: the server returns a collection of objects.</t>	<dd>the server returns a collection of objects
	</list></t>	</dd>


	<t>While the lookup query does not raise issues regarding response size ma nagement, the search query can potentially generate a large result set that is o ften truncated according to server limits. Besides, it is not possible to obtai n the total number of objects found that might be returned in a search query res ponse <xref target="RFC7483"/>. Lastly, there is no way to specify sort criteri a to return the most relevant objects at the beginning of the result set. There fore, the client might traverse the whole result set to find the relevant object s or, due to truncation, might not find them at all.</t>	</dl>


	<t>The specification described in this document extends RDAP query capabil	<t>While the lookup query does not raise issues regarding response size ma
	ities to enable result sorting and paging, by adding new query parameters that c	nagement, the search query can potentially generate a large result set that is o
	an be applied to RDAP search path segments. The service is implemented using th	ften truncated according to server limits. Besides, it is not possible to obtai
	e Hypertext Transfer Protocol (HTTP) <xref target="RFC7230"/> and the convention	n the total number of objects found that might be returned in a search query res
	s described in <xref target="RFC7480"/>.</t>	ponse <xref target="RFC7483"/>. Lastly, there is no way to specify sort criteri
		a to return the most relevant objects at the beginning of the result set. There
		fore, the client might traverse the whole result set to find the relevant object
		s or, due to truncation, might not find them at all.</t>
		<t>The specification described in this document extends RDAP query capabil
		ities to enable result sorting and paging by adding new query parameters that ca
		n be applied to RDAP search path segments. The service is implemented using the
		Hypertext Transfer Protocol (HTTP) <xref target="RFC7230"/> and the conventions
		described in <xref target="RFC7480"/>.</t>
		<t>The implementation of the new parameters is technically feasible, as op
		erators for counting, sorting, and paging rows are currently supported by the ma
		jor relational database management systems.</t>
		<section>
		<name>Conventions Used in This Document</name>


	<t>The implementation of the new parameters is technically feasible, as op	<t>
	erators for counting, sorting and paging rows are currently supported by the maj	The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
	or relational database management systems.</t>	"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
		NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
		"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
		"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are
		to be interpreted as described in BCP 14 <xref target="RFC2119"/>
		<xref target="RFC8174"/> when, and only when, they appear in all capitals,
		as shown here.
		</t>


	<section title="Conventions Used in This Document">
	<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
	SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" i
	n this document are to be interpreted as described in BCP 14 <xref target="RFC21
	19"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals,
	as shown here.</t>
	</section>	</section>

	</section>	</section>
		<section anchor="rdap-query-parameter-specification">
		<name>RDAP Query Parameter Specification</name>
		<t>The new query parameters are <bcp14>OPTIONAL</bcp14> extensions of path
		segments defined in <xref target="RFC7482"/>. They are as follows:</t>


	<section anchor="rdap-query-parameter-specification" title="RDAP Query Parame ter Specification">	<dl>


	<t>The new query parameters are OPTIONAL extensions of path segments defin	<dt>"count":
	ed in <xref target="RFC7482"/>. They are as follows:</t>	</dt>
		<dd>a boolean value that allows a client to request the return of the total numb
		er of objects found
		</dd>


	<t><list style="symbols">	<dt>"sort":
	<t>"count": a boolean value that allows a client to request t	</dt>
	he return of the total number of objects found;<vspace blankLines='1'/></t>	<dd>a string value that allows a client to request a specific sort order for the
	<t>"sort": a string value that allows a client to request a s	result set
	pecific sort order for the result set;<vspace blankLines='1'/></t>	</dd>
	<t>"cursor": a string value representing a pointer to a specif
	ic fixed size portion of the result set.</t>	<dt>"cursor":
	</list></t>	</dt>
		<dd>a string value representing a pointer to a specific fixed-size portion of th
		e result set
		</dd>

		</dl>

	<t>Augmented Backus-Naur Form (ABNF) <xref target="RFC5234"/> is used in t he following sections to describe the formal syntax of these new parameters.</t>	<t>Augmented Backus-Naur Form (ABNF) <xref target="RFC5234"/> is used in t he following sections to describe the formal syntax of these new parameters.</t>

		<section anchor="sorting_and_paging_metadata">
		<name>Sorting and Paging Metadata</name>


	<section anchor="sorting_and_paging_metadata" title="Sorting and Paging Me	<t>According to most advanced principles in REST design, collectively
	tadata">	known as HATEOAS (Hypermedia as the Engine of Application State)
		<xref target="HATEOAS"/>, a client entering a REST application through
		an initial URI should use server-provided links to dynamically
		discover available actions and access the resources it needs. In this
		way, the client is neither required to have prior knowledge of the
		service nor, consequently, to hard code the URIs of different
		resources. This allows the server to make URI changes as the API
		evolves without breaking clients. Definitively, a REST service should
		be as self-descriptive as possible.</t>


	<t>According to most advanced principles in REST design, collectively known as H	<t>Therefore, servers implementing the query parameters described in thi
	ATEOAS (Hypermedia as the Engine of Application State) <xref target="HATEOAS"/>,	s specification <bcp14>SHOULD</bcp14> provide additional information in their re
	a client entering a REST application through an initial URI should use server-p	sponses about both the available sorting criteria and possible pagination. Such
	rovided links to dynamically discover available actions and access the resources	information is collected in two <bcp14>OPTIONAL</bcp14> response elements named
	it needs. In this way, the client is not required to have prior knowledge of t	"sorting_metadata" and "paging_metadata".</t>
	he service and, consequently, to hard code the URIs of different resources. Thi	<t>The "sorting_metadata" element contains the following properties:</t>
	s allows the server to make URI changes as the API evolves without breaking clie
	nts. Definitively, a REST service should be as self-descriptive as possible.</t
	>


	<t>Therefore, servers implementing the query parameters described in this specif ication SHOULD provide additional information in their responses about both the available sorting criteria and possible pagination. Such information is collect ed in two OPTIONAL response elements named "sorting_metadata" and &quo t;paging_metadata".</t>	<dl newline="true">


	<t>The "sorting_metadata" element contains the following prope	<dt>"currentSort": "String" (<bcp14>OPTIONAL</bcp14>)
	rties:</t>	</dt>
	<t><list style="symbols">	<dd>Either the value of the "sort" parameter as specified in the query string or
	<t>"currentSort": "String" (OPTIONAL) either the va	the sort applied by default, if any.
	lue of "sort" parameter as specified in the query string or the sort a	</dd>
	pplied by default, if any;<vspace blankLines='1'/></t>
	<t>"availableSorts": "AvailableSort[]" (OPTIONAL) a
	n array of objects, with each element describing an available sort criterion. T
	he AvailableSort object includes the following members:
	<list style="symbols">
	<t>"property": "String" (REQUIRED) the name that ca
	n be used by the client to request the sort criterion;</t>
	<t>"default": "Boolean" (REQUIRED) whether the sor
	t criterion is applied by default. An RDAP server MUST define only one default
	sorting property for each object class;</t>
	<t>"jsonPath": "String" (OPTIONAL) the JSONPath ex
	pression of the RDAP field corresponding to the property;</t>
	<t>"links": "Link[]" (OPTIONAL) an array of links a
	s described in <xref target="RFC8288"/> containing the query string that applies
	the sort criterion.</t>
	</list></t>
	</list></t>


	<t>At least one of the "currentSort" and "availableSorts" pr	<dt>"availableSorts": "AvailableSort[]" (<bcp14>OPTIONAL</bcp14>)
	operties MUST be present.</t>	</dt>


	<t>The "paging_metadata" element contains the following fields	<dd><t>An array of objects, with each element describing an available sort crite
	:</t>	rion. The AvailableSort object includes the following members:</t>
	<t><list style="symbols">
	<t>"totalCount": "Numeric" (OPTIONAL) a numeric val
	ue representing the total number of objects found. It MUST be provided if and o
	nly if the query string contains the "count" parameter;<vspace blankLi
	nes='1'/></t>
	<t>"pageSize": "Numeric" (OPTIONAL) a numeric value
	representing the number of objects that should have been returned in the curren
	t page. It MUST be provided if and only if the total number of objects exceeds
	the page size. This property is redundant for RDAP clients because the page siz
	e can be derived from the length of the search results array but, it can be help
	ful if the end user interacts with the server through a web browser;<vspace blan
	kLines='1'/></t>
	<t>"pageNumber": "Numeric" (OPTIONAL) a numeric val
	ue representing the number of the current page in the result set. It MUST be pr
	ovided if and only if the total number of objects found exceeds the page size;<v
	space blankLines='1'/></t>
	<t>"links": "Link[]" (OPTIONAL) an array of links a
	s described in <xref target="RFC8288"/> containing the reference to the next pag
	e. In this specification, only forward pagination is described because it is al
	l that is necessary to traverse the result set.</t>
	</list></t>


	<section anchor="rdap-conformance" title="RDAP Conformance">	<dl newline="true">
	<t>Servers returning the "paging_metadata" element in their resp
	onse MUST include the string literal "paging" in the rdapConformance a
	rray. Servers returning the "sorting_metadata" element MUST include t
	he string literal "sorting".</t>
	</section>


	</section>	<dt>"property": "String" (<bcp14>REQUIRED</bcp14>)
		</dt>
		<dd>The name that can be used by the client to request the sort criterion.
		</dd>


	<section anchor="count-parameter" title=""count" Parameter">	<dt>"default": "Boolean" (<bcp14>REQUIRED</bcp14>)
		</dt>
		<dd>Indicator of whether the sort criterion is applied by default. An RDAP serve
		r <bcp14>MUST</bcp14> define only one default sorting property for each object c
		lass.
		</dd>


	<t>Currently, the RDAP protocol does not allow a client to determine the	<dt>"jsonPath": "String" (<bcp14>OPTIONAL</bcp14>)
	total number of the results in a query response when the result set is truncated	</dt>
	. This is inefficient because the user cannot determine if the result set is co	<dd>The JSONPath expression of the RDAP field corresponding to the property.
	mplete.</t>	</dd>


	<t>The "count" parameter provides additional functionality that	<dt>"links": "Link[]" (<bcp14>OPTIONAL</bcp14>)
	allows a client to request information from the server that specifies the total	</dt>
	number of objects matching the search pattern.</t>	<dd>An array of links as described in <xref target="RFC8288"/> containing the
		query string that applies the sort criterion.
		</dd>


	<t>The following is an example of an RDAP query including the "coun t" parameter:</t>	</dl>


	<t>https://example.com/rdap/domains?name=example*.com&count=true</t>	</dd>


	<t>The ABNF syntax is the following:</t>	</dl>
	<t><list style="empty">
	<t>count = "count=" ( trueValue / falseValue )</t>
	<t>trueValue = ("true" / "yes" / "1&quot
	;)</t>
	<t>falseValue = ("false" / "no" / "0&quo
	t;)</t>
	</list></t>


	<t>A trueValue means that the server MUST provide the total number of the	<t>At least one of the "currentSort" and "availableSorts" properties
	objects in the "totalCount" field of the "paging_metadata"	<bcp14>MUST</bcp14> be present.</t>
	element (<xref target="count-in-response-example"/>). A falseValue means that t	<t>The "paging_metadata" element contains the following fields:</t>
	he server MUST NOT provide this number.</t>


	<figure anchor="count-in-response-example" title="Example of RDAP response	<dl newline="true">
	with "paging_metadata" element containing the "totalCount"
	field">	<dt>"totalCount": "Numeric" (<bcp14>OPTIONAL</bcp14>)
	<artwork xml:space="preserve">	</dt>
		<dd>A numeric value representing the total number of objects found. It
		<bcp14>MUST</bcp14> be provided if and only if the query string contains the
		"count" parameter.
		</dd>

		<dt>"pageSize": "Numeric" (<bcp14>OPTIONAL</bcp14>)
		</dt>
		<dd>A numeric value representing the number of objects that should have been
		returned in the current page. It <bcp14>MUST</bcp14> be provided if and only
		if the total number of objects exceeds the page size. This property is
		redundant for RDAP clients because the page size can be derived from the
		length of the search results array, but it can be helpful if the end user
		interacts with the server through a web browser.
		</dd>

		<dt>"pageNumber": "Numeric" (<bcp14>OPTIONAL</bcp14>)
		</dt>
		<dd>A numeric value representing the number of the current page in the result
		set. It <bcp14>MUST</bcp14> be provided if and only if the total number of
		objects found exceeds the page size.
		</dd>

		<dt>"links": "Link[]" (<bcp14>OPTIONAL</bcp14>)
		</dt>
		<dd>An array of links as described in <xref target="RFC8288"/> containing the
		reference to the next page. In this specification, only forward pagination is
		described because it is all that is necessary to traverse the result set.
		</dd>
		</dl>


		<section anchor="rdap-conformance">
		<name>RDAP Conformance</name>
		<t>Servers returning the "paging_metadata" element in their response
		<bcp14>MUST</bcp14> include the string literal "paging" in the
		rdapConformance array. Servers returning the "sorting_metadata"
		element <bcp14>MUST</bcp14> include the string literal
		"sorting".</t>
		</section>
		</section>
		<section anchor="count-parameter">
		<name>"count" Parameter</name>
		<t>Currently, RDAP does not allow a client to determine
		the total number of results in a query response when the result
		set is truncated. This is inefficient because the user cannot
		determine if the result set is complete.</t>
		<t>The "count" parameter provides additional functionality that allows
		a client to request information from the server that specifies the
		total number of objects matching the search pattern.</t>
		<t>The following is an example of an RDAP query including the "count" pa
		rameter:</t>
		<t>https://example.com/rdap/domains?name=example*.com&count=true
		</t>
		<t>The ABNF syntax is the following:</t>
		<sourcecode type="abnf">
		count = "count=" ( trueValue / falseValue )
		trueValue = ("true" / "yes" / "1")
		falseValue = ("false" / "no" / "0")
		</sourcecode>
		<t>A trueValue means that the server <bcp14>MUST</bcp14> provide the
		total number of objects in the "totalCount" field of the
		"paging_metadata" element (<xref
		target="count-in-response-example"/>). A falseValue means that the
		server <bcp14>MUST NOT</bcp14> provide this number.</t>
		<figure anchor="count-in-response-example">
		<name>Example of RDAP Response with "paging_metadata" Element Containi
		ng the "totalCount" Field</name>
		<sourcecode type="json">
	{	{
	"rdapConformance": [	"rdapConformance": [

	"rdap_level_0",	"rdap_level_0",
	"paging"	"paging"
	],	],
	...	...
	"paging_metadata": {	"paging_metadata": {
	"totalCount": 43	"totalCount": 43
	},	},
	"domainSearchResults": [	"domainSearchResults": [
	...	...
	]	]
	}	}

	</artwork>	</sourcecode>
	</figure>	</figure>
	</section>	</section>

		<section anchor="sort-parameter">
		<name>"sort" Parameter</name>
		<t>RDAP does not provide any capability to specify the result set sort c
		riteria. A server could implement a default sorting scheme according to the obj
		ect class, but this feature is not mandatory and might not meet user requirement
		s. Sorting can be addressed by the client, but this solution is rather ineffici
		ent. Sorting features provided by the RDAP server could help avoid truncation o
		f relevant results.</t>
		<t>The "sort" parameter allows the client to ask the server to sort the
		results according to the values of one or more properties and according to the s
		ort direction of each property. The ABNF syntax is the following:</t>
		<sourcecode type="abnf">
		sort = "sort=" sortItem *( "," sortItem )
		sortItem = property-ref [":" ( "a" / "d" ) ]
		property-ref = ALPHA *( ALPHA / DIGIT / "_" )
		</sourcecode>


	<section anchor="sort-parameter" title=""sort" Parameter">	<t>"a" means that an ascending sort <bcp14>MUST</bcp14> be applied; "d"
		means that a descending sort <bcp14>MUST</bcp14> be applied. If the sort direct
		ion is absent, an ascending sort <bcp14>MUST</bcp14> be applied.</t>
		<t>The following are examples of RDAP queries that include the "sort" pa
		rameter:</t>


	<t>The RDAP protocol does not provide any capability to specify the resul	<t>
	t set sort criteria. A server could implement a default sorting scheme accordin	https://example.com/rdap/domains?name=example*.com&sort=name
	g to the object class, but this feature is not mandatory and might not meet user	</t>
	requirements. Sorting can be addressed by the client, but this solution is rat	<t>
	her inefficient. Sorting features provided by the RDAP server could help avoid	https://example.com/rdap/
	truncation of relevant results.</t>	domains?name=example*.com&sort=registrationDate:d
		</t>
		<t>
		https://example.com/rdap/
		domains?name=example*.com&sort=lockedDate,name
		</t>
		<t>Except for sorting IP addresses and values denoting dates and times,
		servers <bcp14>MUST</bcp14> implement sorting according to the JSON value type o
		f the RDAP field the sorting property refers to. That is, JSON strings <bcp14>M
		UST</bcp14> be sorted lexicographically, and JSON numbers <bcp14>MUST</bcp14> be
		sorted numerically. Values denoting dates and times <bcp14>MUST</bcp14> be sor
		ted in chronological order. If IP addresses are represented as JSON strings, th
		ey <bcp14>MUST</bcp14> be sorted based on their numeric conversion.</t>


	<t>The "sort" parameter allows the client to ask the server to	<t>The conversion of an IPv4 address to a number is possible since each
	sort the results according to the values of one or more properties and according	dotted format IPv4 address is a representation of a number written in a 256-base
	to the sort direction of each property. The ABNF syntax is the following:</t>	d manner; for example, 192.168.0.1 means 1256^0 + 0256^1 + 168256^2 + 192256
		^3 = 3232235521. Similarly, an IPv6 address can be converted into a number by
		applying the base 65536. Therefore, the numerical representation of the IPv6 ad
		dress 2001:0db8:85a3:0:0:8a2e:0370:7334 is 4254076645264115407174021557775764357
		2. Built-in functions and libraries for converting IP addresses into numbers ar
		e available in most known programming languages and relational database manageme
		nt systems.</t>
		<t>If the "sort" parameter presents an allowed sorting property, it <bcp
		14>MUST</bcp14> be provided in the "currentSort" field of the "sorting_metadata"
		element.</t>
		<section anchor="sorting_properties">
		<name>Sorting Properties Declaration</name>
		<t>In the "sort" parameter ABNF syntax, the element named "property-re
		f" represents a reference to a property of an RDAP object. Such a reference cou
		ld be expressed by using a JSONPath expression (named "jsonpath" in the followin
		g).</t>
		<t>JSONPath is a syntax, originally based on the XML XPath notation <x
		ref target="W3C.CR-xpath-31-20170321"/>, which represents a path to select an el
		ement (or a set of elements) in a JSON document <xref target="RFC8259"/>. For e
		xample, the jsonpath to select the value of the ASCII name inside an RDAP domain
		lookup response is "$.ldhName", where $ identifies the root of the document obj
		ect model (DOM). Another way to select a value inside a JSON document is the JS
		ON Pointer <xref target="RFC6901"/>.</t>
		<t>While JSONPath and JSON Pointer are both commonly adopted
		notations to select any value inside JSON data, neither is
		particularly concise and easy to use
		(e.g., "$.domainSearchResults[*].events[?(@.eventAction='registration'
		)].eventDate"
		is the jsonpath of the registration date in an RDAP domain search
		response).</t>
		<t>Therefore, this specification defines the "property-ref" element in
		terms of names identifying RDAP properties. However, not all the RDAP properti
		es are suitable to be used in sort criteria. These properties include:</t>
		<ul>
		<li>
		<t>properties providing service information (e.g., links, notices,
		and remarks)</t>
		</li>
		<li>
		<t>multivalued properties (e.g., status, roles, and variants)</t>
		</li>
		<li>properties representing relationships to other objects (e.g., en
		tities)</li>
		</ul>
		<t>On the contrary, properties expressed as values of other
		properties (e.g., registration date) could be used in such a
		context.</t>
		<t>A list of properties an RDAP server <bcp14>MAY</bcp14> implement
		is defined. The properties are divided into two groups:
		object-common properties and object-specific properties.</t>


	<t><list style="empty">	<ul>
	<t>sort = "sort=" sortItem *( "," sortItem )</t>	<li><t>Object-common properties. Object-common properties are derive
	<t>sortItem = property-ref [":" ( "a" / "d"	d from merging the "eventAction" and the "eventDate" properties. The following v
	) ]</t>	alues of the "sort" parameter are defined:</t>
	<t>property-ref = ALPHA *( ALPHA / DIGIT / "_" ) </t>
	</list></t>


	<t>"a" means that an ascending sort MUST be applied, "d&qu ot; means that a descending sort MUST be applied. If the sort direction is abse nt, an ascending sort MUST be applied.</t>	<ul>


	<t>The following are examples of RDAP queries including the "sort"	<li>registrationDate
	parameter:</t>	</li>


	<t>https://example.com/rdap/domains?name=example*.com&sort=name</t>	<li>reregistrationDate
		</li>


	<t>https://example.com/rdap/domains?name=example*.com&sort=registrationD	<li>lastChangedDate
	ate:d</t>	</li>


	<t>https://example.com/rdap/domains?name=example*.com&sort=lockedDate,na	<li>expirationDate
	me</t>	</li>


	<t>Except for sorting IP addresses and values denoting dates and times, serv	<li>deletionDate
	ers MUST implement sorting according to the JSON value type of the RDAP field th	</li>
	e sorting property refers to. That is, JSON strings MUST be sorted lexicographi
	cally and JSON numbers MUST be sorted numerically. Values denoting dates and ti
	mes MUST be sorted in chronological order. If IP addresses are represented as J
	SON strings, they MUST be sorted based on their numeric conversion.</t>


	<t>The conversion of an IPv4 address to a number is possible since each dotted f	<li>reinstantiationDate
	ormat IPv4 address is a representation of a number written in a 256-based manner	</li>
	: 192.168.0.1 means 1256^0 + 0256^1 + 168256^2 + 192256^3 = 3232235521. Sim
	ilarly, an IPv6 address can be converted into a number by applying the base 655
	36. Therefore, the numerical representation of the IPv6 address 2001:0db8:85a3:
	0:0:8a2e:0370:7334 is 42540766452641154071740215577757643572. Builtin functions
	and libraries for converting IP addresses into numbers are available in most kn
	own programming languages and relational database management systems.</t>


	<t>If the "sort" parameter presents an allowed sorting property, i	<li>transferDate
	t MUST be provided in the "currentSort" field of the "sorting_met	</li>
	adata" element.</t>


	<section anchor="sorting_properties" title="Sorting Properties Declaration">	<li>lockedDate
	<t>In the "sort" parameter ABNF syntax, the element named "pr	</li>
	operty-ref" represents a reference to a property of an RDAP object. Such a
	reference could be expressed by using a JSONPath expression (named "jsonpath" i
	n the following).</t>
	<t>JSONPath is a syntax, originally based on the XML XPath notation <xref ta
	rget="W3C.CR-xpath-31-20161213"/>, which represents a path to select an element
	(or a set of elements) in a JSON document <xref target="RFC8259"/>. For example
	, the jsonpath to select the value of the ASCII name inside an RDAP domain looku
	p response is "$.ldhName", where $ identifies the root of the document
	object model (DOM). Another way to select a value inside a JSON document is th
	e JSON Pointer <xref target="RFC6901"/>.</t>
	<t>While JSONPath or JSON Pointer are both commonly adopted notations to sel
	ect any value inside JSON data, neither is particularly coincise and easy to use
	(e.g. "$.domainSearchResults[*].events[?(@.eventAction='registration&
	apos;)].eventDate" is the jsonpath of the registration date in an RDAP doma
	in search response).</t>


	<t>Therefore, this specification defines the "property-ref" ele	<li>unlockedDate
	ment in terms of names identifying RDAP properties. However, not all the RDAP p	</li>
	roperties are suitable to be used in sort criteria, such as:</t>


	<t><list style="symbols">	</ul>
	<t>properties providing service information (e.g. links, notices, remar
	ks);<vspace blankLines='1' /></t>
	<t>multivalued properties (e.g. status, roles, variants);<vspace blankL
	ines='1' /></t>
	<t>properties representing relationships to other objects (e.g. entitie
	s).</t>
	</list></t>


	<t>On the contrary, properties expressed as values of other properties (e .g. registration date) could be used in such a context.</t>	</li>


	<t>A list of properties an RDAP server MAY implement is defined. The proper	<li><t>Object-specific properties. Note that some of these properties are also d
	ties are divided into two groups: object common properties and object specific p	efined as query path segments. These properties include:</t>
	roperties.</t>	<ul>
		<li>Domain: name
		</li>


	<t><list style="symbols">	<li>Nameserver: name, ipv4, ipv6
	<t>Object common properties. Object common properties are derived from	</li>
	merging the "eventAction" and the "eventDate" properties.
	The following values of the "sort" parameter are defined:
	<list style="symbols">
	<t>registrationDate</t>
	<t>reregistrationDate</t>
	<t>lastChangedDate</t>
	<t>expirationDate</t>
	<t>deletionDate</t>
	<t>reinstantiationDate</t>
	<t>transferDate</t>
	<t>lockedDate</t>
	<t>unlockedDate</t>
	</list></t>
	</list></t>
	<t><list style="symbols">
	<t>Object specific properties. Note that some of these properties are
	also defined as query path segments. These properties include:
	<list style="symbols">
	<t>Domain: name</t>
	<t>Nameserver: name, ipv4, ipv6.</t>
	<t>Entity: fn, handle, org, email, voice, country, cc, city.</t>
	</list></t>
	</list></t>


	<t>The correspondence between these sorting properties and the RDAP object c	<li>Entity: fn, handle, org, email, voice, country, cc, city
	lasses is shown in <xref target="table_sorting_properties_definition"/>. Some o	</li>
	f the sorting properties defined for the RDAP entity class are related to jCard
	elements <xref target="RFC7095"/> but, being jCard the JSON format for vCard <xr
	ef target="RFC6350"/>, the corresponding definitions are included in vCard speci
	fication.</t>


	<t>An RDAP server MUST NOT use the defined sorting properties with a meaning other than the one described in <xref target="table_sorting_properties_definiti on"/>.</t>	</ul>


	<texttable anchor="table_sorting_properties_definition" title="Sorting prope	</li>
	rties definition">	</ul>
	<ttcol align="left">Object class</ttcol>
	<ttcol align="left">Sorting property</ttcol>
	<ttcol align="left">RDAP property</ttcol>
	<ttcol align="left">RFC 7483</ttcol>
	<ttcol align="left">RFC 6350</ttcol>
	<ttcol align="left">RFC 8605</ttcol>
	<c>Searchable objects</c><c>Common properties</c><c>eventAction values su
	ffixed by "Date"</c><c>4.5</c><c></c><c></c>
	<c></c><c></c><c></c><c></c><c></c><c></c>
	<c>Domain</c><c>name</c><c>unicodeName/ ldhName</c><c>5.3</c><c></c><c></
	c>
	<c></c><c></c><c></c><c></c><c></c><c></c>
	<c>Nameserver</c><c>name</c><c>unicodeName/ ldhName</c><c>5.2</c><c></c><
	c></c>
	<c></c><c>ipv4</c><c>v4 ipAddress</c><c>5.2</c><c></c><c></c>
	<c></c><c>ipv6</c><c>v6 ipAddress</c><c>5.2</c><c></c><c></c>
	<c></c><c></c><c></c><c></c><c></c><c></c>
	<c>Entity</c><c>handle</c><c>handle</c><c>5.1</c><c></c><c></c>
	<c></c><c>fn</c><c>jCard fn</c><c>5.1</c><c>6.2.1</c><c></c>
	<c></c><c>org</c><c>jCard org</c><c>5.1</c><c>6.6.4</c><c></c>
	<c></c><c>voice</c><c>jCard tel with type="voice"</c><c>5.1</c>
	<c>6.4.1</c><c></c>
	<c></c><c>email</c><c>jCard email</c><c>5.1</c><c>6.4.2</c><c></c>
	<c></c><c>country</c><c>country name in jCard adr</c><c>5.1</c><c>6.3.1</
	c><c></c>
	<c></c><c>cc</c><c>country code in jCard adr</c><c>5.1</c><c></c><c>3.1</
	c>
	<c></c><c>city</c><c>locality in jCard adr</c><c>5.1</c><c>6.3.1</c><c></
	c>
	</texttable>


	<t>Regarding the definitions in <xref target="table_sorting_properties_de	<t>The correspondence between these sorting properties and the RDAP
	finition"/>, some further considerations are needed to disambiguate some cases:<	object classes is shown in <xref
	/t>	target="table_sorting_properties_definition"/>. Some of the sorting
	<t><list style="symbols">	properties defined for the RDAP entity class are related to jCard
	<t>since the response to a search on either domains or nameservers might	elements <xref target="RFC7095"/>, but because jCard is the JSON forma
	include both A-labels and U-labels <xref target="RFC5890"/> in general, a consi	t
	stent sorting policy MUST treat the unicodeName and ldhName as two representatio	for vCard, the corresponding definitions
	ns of the same value. The unicodeName value MUST be used while sorting if it is	are included in the vCard specification <xref target="RFC6350"/>.</t>
	present; when the unicodeName is unavailable, the value of the ldhName MUST be	<t>An RDAP server <bcp14>MUST NOT</bcp14> use the defined sorting
	used instead;<vspace blankLines='1' /></t>	properties with a meaning other than that described in <xref
	<t>the jCard "sort-as" parameter MUST be ignored for the sorti	target="table_sorting_properties_definition"/>.</t>
	ng capability described in this document;<vspace blankLines='1' /></t>	<table anchor="table_sorting_properties_definition">
	<t>even if a nameserver can have multiple IPv4 and IPv6 addresses, the	<name>Definitions of Sorting Properties</name>
	most common configuration includes one address for each IP version. Therefore,	<thead>
	this specification makes the assumption that nameservers have a single IPv4 and/	<tr>
	or IPv6 value. When more than one address per IP version is presented, sorting	<th align="left">Object class</th>
	MUST be applied to the first value;<vspace blankLines='1' /></t>	<th align="left">Sorting property</th>
	<t>multiple events with a given action on an object might be returned. I	<th align="left">RDAP property</th>
	f this occurs, sorting MUST be applied to the most recent event;<vspace blankLin	<th align="left">RFC 7483</th>
	es='1' /></t>	<th align="left">RFC 6350</th>
	<t>except for handle values, all the sorting properties defined for entit	<th align="left">RFC 8605</th>
	y objects can be multivalued according to the definition of vCard as given in <x	</tr>
	ref target="RFC6350"/>. When more than one value is presented, sorting MUST be	</thead>
	applied to the preferred value identified by the parameter pref="1".	<tbody>
	If the pref parameter is missing, sorting MUST be applied to the first value.</t	<tr>
	>	<td align="left">Searchable objects</td>
	</list></t>	<td align="left">Common properties</td>
		<td align="left">eventAction values suffixed by "Date"</td>
		<td align="left"><xref target="RFC7483" section="4.5" sectionFor
		mat="bare"/></td>
		<td align="left"/>
		<td align="left"/>
		</tr>


	<t>The "jsonPath" field in the "sorting_metadata" el	<tr>
	ement is used to clarify the RDAP response field the sorting property refers to.	<td align="left">Domain</td>
	The mapping between the sorting properties and the jsonpaths of the RDAP respo	<td align="left">name</td>
	nse fields is shown below. The JSONPath operators used herein are described in	<td align="left">unicodeName/ ldhName</td>
	<xref target="jsonpath-operators"/>.</t>	<td align="left"><xref target="RFC7483" section="5.3" sectionFor
		mat="bare"/></td>
		<td align="left"/>
		<td align="left"/>
		</tr>


	<t><list style="symbols">	<tr>
	<t>Searchable objects	<td align="left">Nameserver</td>
	<list style="hanging">	<td align="left">name</td>
	<t hangText="registrationDate"><vspace blankLines='1' />$.domainSe	<td align="left">unicodeName/ ldhName</td>
	archResults[*].events[?(@.eventAction=="registration")].eventDate<vspa	<td align="left"><xref target="RFC7483" section="5.2" sectionFor
	ce blankLines='1' /></t>	mat="bare"/></td>
	<t hangText="reregistrationDate"><vspace blankLines='1' />$.domain	<td align="left"/>
	SearchResults[*].events[?(@.eventAction=="reregistration")].eventDate<	<td align="left"/>
	vspace blankLines='1' /></t>	</tr>
	<t hangText="lastChangedDate"><vspace blankLines='1' />$.domainSea	<tr>
	rchResults[*].events[?(@.eventAction=="last changed")].eventDate<vspac	<td align="left"/>
	e blankLines='1' /></t>	<td align="left">ipv4</td>
	<t hangText="expirationDate"><vspace blankLines='1' />$.domainSear	<td align="left">v4 ipAddress</td>
	chResults[*].events[?(@.eventAction=="expiration")].eventDate<vspace b	<td align="left"><xref target="RFC7483" section="5.2" sectionFor
	lankLines='1' /></t>	mat="bare"/></td>
	<t hangText="deletionDate"><vspace blankLines='1' />$.domainSearch	<td align="left"/>
	Results[*].events[?(@.eventAction=="deletion")].eventDate<vspace blank	<td align="left"/>
	Lines='1' /></t>	</tr>
	<t hangText="reinstantiationDate"><vspace blankLines='1' />$.domai	<tr>
	nSearchResults[*].events[?(@.eventAction=="reinstantiation")].eventDat	<td align="left"/>
	e<vspace blankLines='1' /></t>	<td align="left">ipv6</td>
	<t hangText="transferDate"><vspace blankLines='1' />$.domainSearch	<td align="left">v6 ipAddress</td>
	Results[*].events[?(@.eventAction=="transfer")].eventDate<vspace blank	<td align="left"><xref target="RFC7483" section="5.2" sectionFor
	Lines='1' /></t>	mat="bare"/></td>
	<t hangText="lockedDate"><vspace blankLines='1' />$.domainSearchRe	<td align="left"/>
	sults[*].events[?(@.eventAction=="locked")].eventDate<vspace blankLine	<td align="left"/>
	s='1' /></t>	</tr>
	<t hangText="unlockedDate"><vspace blankLines='1' />$.domainSearch
	Results[*].events[?(@.eventAction=="unlocked")].eventDate<vspace blank
	Lines='1' /></t>
	</list>
	</t>
	<t>Domain
	<list style="hanging">
	<t hangText="name"><vspace blankLines='1' />$.domainSearchResu
	lts[*].[unicodeName,ldhName]<vspace blankLines='1' /></t>
	</list>
	</t>
	<t>Nameserver
	<list style="hanging">
	<t hangText="name"><vspace blankLines='1' />$.nameserverSearch
	Results[*].[unicodeName,ldhName]<vspace blankLines='1' /></t>
	<t hangText="ipv4"><vspace blankLines='1' />$.nameserverSearch
	Results[*].ipAddresses.v4[0]<vspace blankLines='1' /></t>
	<t hangText="ipv6"><vspace blankLines='1' />$.nameserverSearch
	Results[*].ipAddresses.v6[0]<vspace blankLines='1' /></t>
	</list>
	</t>
	<t>Entity
	<list style="hanging">
	<t hangText="handle"><vspace blankLines='1' />$.entitySearchRe
	sults[*].handle<vspace blankLines='1' /></t>
	<t hangText="fn"><vspace blankLines='1' />$.entitySearchResult
	s[*].vcardArray[1][?(@[0]=="fn")][3]<vspace blankLines='1' /></t>
	<t hangText="org"><vspace blankLines='1' />$.entitySearchResul
	ts[*].vcardArray[1][?(@[0]=="org")][3]<vspace blankLines='1' /></t>
	<t hangText="voice"><vspace blankLines='1' />$.entitySearchRes
	ults[*].vcardArray[1][?(@[0]=="tel" && @[1].type=="voice&
	quot;)][3]<vspace blankLines='1' /></t>
	<t hangText="email"><vspace blankLines='1' />$.entitySearchRes
	ults[*].vcardArray[1][?(@[0]=="email")][3]<vspace blankLines='1' /></t
	>
	<t hangText="country"><vspace blankLines='1' />$.entitySearchR
	esults[*].vcardArray[1][?(@[0]=="adr")][3][6]<vspace blankLines='1' />
	</t>
	<t hangText="cc"><vspace blankLines='1' />$.entitySearchResult
	s[*].vcardArray[1][?(@[0]=="adr")][1].cc<vspace blankLines='1' /></t>
	<t hangText="city"><vspace blankLines='1' />$.entitySearchResu
	lts[*].vcardArray[1][?(@[0]=="adr")][3][3]<vspace blankLines='1' /></t
	>
	</list>
	</t>
	</list></t>


	<t>Additional notes on the provided jsonpaths:</t>	<tr>
	<t><list style="symbols">	<td align="left">Entity</td>
	<t>those related to the event dates are defined only for the "domain	<td align="left">handle</td>
	" object. To obtain the equivalent jsonpaths for "entity" and &q	<td align="left">handle</td>
	uot;nameserver", the path segment "domainSearchResults" must be r	<td align="left"><xref target="RFC7483" section="5.1" sectionFor
	eplaced with "entitySearchResults" and "nameserverSearchResults&q	mat="bare"/></td>
	uot; respectively;<vspace blankLines='1' /></t>	<td align="left"/>
	<t>those related to jCard elements are specified without taking into acco	<td align="left"/>
	unt the "pref" parameter. Servers that sort those values identified b	</tr>
	y the pref parameter SHOULD update a jsonpath by adding an appropriate filter.	<tr>
	For example, if the email values identified by pref="1" are considered	<td align="left"/>
	for sorting, the jsonpath of the "email" sorting property should be:	<td align="left">fn</td>
	$.entitySearchResults[*].vcardArray[1][?(@[0]=="email" && @[1]	<td align="left">jCard fn</td>
	.pref=="1")][3]</t>	<td align="left"><xref target="RFC7483" section="5.1" sectionFor
	</list></t>	mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.2.1" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">org</td>
		<td align="left">jCard org</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.6.4" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">voice</td>
		<td align="left">jCard tel with type="voice"</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.4.1" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">email</td>
		<td align="left">jCard email</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.4.2" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">country</td>
		<td align="left">country name in jCard adr</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.3.1" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">cc</td>
		<td align="left">country code in jCard adr</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"/>
		<td align="left"><xref target="RFC8605" section="3.1" sectionFor
		mat="bare"/></td>
		</tr>
		<tr>
		<td align="left"/>
		<td align="left">city</td>
		<td align="left">locality in jCard adr</td>
		<td align="left"><xref target="RFC7483" section="5.1" sectionFor
		mat="bare"/></td>
		<td align="left"><xref target="RFC6350" section="6.3.1" sectionF
		ormat="bare"/></td>
		<td align="left"/>
		</tr>
		</tbody>
		</table>
		<t>Regarding the definitions in <xref target="table_sorting_properties
		_definition"/>, some further considerations are needed to disambiguate some case
		s:</t>
		<ul>
		<li>
		<t>Since the response to a search on either domains or nameservers
		might include both A-labels and U-labels <xref target="RFC5890"/> in general, a
		consistent sorting policy <bcp14>MUST</bcp14> treat the unicodeName and ldhName
		as two representations of the same value. The unicodeName value <bcp14>MUST</b
		cp14> be used while sorting if it is present; when the unicodeName is unavailabl
		e, the value of the ldhName <bcp14>MUST</bcp14> be used instead.</t>
		</li>
		<li>
		<t>The jCard "sort-as" parameter <bcp14>MUST</bcp14> be ignored fo
		r the sorting capability described in this document.</t>
		</li>
		<li>
		<t>Even if a nameserver can have multiple IPv4 and IPv6 addresses,
		the most common configuration includes one address for each IP version. Theref
		ore, this specification makes the assumption that nameservers have a single IPv4
		and/or IPv6 value. When more than one address per IP version is presented, sor
		ting <bcp14>MUST</bcp14> be applied to the first value.</t>
		</li>
		<li>
		<t>Multiple events with a given action on an object might be retur
		ned. If this occurs, sorting <bcp14>MUST</bcp14> be applied to the most recent
		event.</t>


	</section>	</li>
	<section anchor="sorting_links" title="Representing Sorting Links">	<li>Except for handle values, all the sorting properties defined for
	<t>An RDAP server MAY use the "links" array of the "sortin	entity objects can be multivalued according to the definition of vCard as given
	g_metadata" element to provide ready-made references <xref target="RFC8288"	in <xref target="RFC6350"/>. When more than one value is presented, sorting <b
	/> to the available sort criteria (<xref target="sort-link-in-response-example"/	cp14>MUST</bcp14> be applied to the preferred value identified by the parameter
	>). Each link represents a reference to an alternate view of the results.</t>	pref="1". If the "pref" parameter is missing, sorting <bcp14>MUST</bcp14> be ap
		plied to the first value.</li>
		</ul>
		<t>The "jsonPath" field in the "sorting_metadata" element is used to c
		larify the RDAP response field the sorting property refers to. The mapping betw
		een the sorting properties and the jsonpaths of the RDAP response fields is show
		n below. The JSONPath operators used herein are described in <xref target="json
		path-operators"/>.</t>
		<ul >
		<li>
		<t>Searchable objects
		</t>
		<dl newline="true">
		<dt>registrationDate</dt>


	<t>The "value", "rel" and "href" JSON values MUST	<dd>
	be specified. All other JSON values are OPTIONAL.</t>	<t>$.domainSearchResults[*].events[?(@.eventAction=="registration")].eventDate</
		t>
		</dd>
		<dt>reregistrationDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="reregistr
		ation")].eventDate</t>


	<figure anchor="sort-link-in-response-example" title="Example of a "s	</dd>
	orting_metadata" instance to implement result sorting">	<dt>lastChangedDate</dt>
	<artwork xml:space="preserve"><![CDATA[	<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="last chan
		ged")].eventDate</t>


		</dd>
		<dt>expirationDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="expiratio
		n")].eventDate</t>

		</dd>
		<dt>deletionDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="deletion"
		)].eventDate</t>

		</dd>
		<dt>reinstantiationDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="reinstant
		iation")].eventDate</t>

		</dd>
		<dt>transferDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="transfer"
		)].eventDate</t>

		</dd>
		<dt>lockedDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="locked")]
		.eventDate</t>

		</dd>
		<dt>unlockedDate</dt>
		<dd>
		<t>$.domainSearchResults[*].events[?(@.eventAction=="unlocked"
		)].eventDate</t>

		</dd>
		</dl>
		</li>
		<li>
		<t>Domain
		</t>
		<dl newline="true">
		<dt>name</dt>
		<dd>
		<t>$.domainSearchResults[*].[unicodeName,ldhName]</t>

		</dd>
		</dl>
		</li>
		<li>
		<t>Nameserver
		</t>
		<dl newline="true">
		<dt>name</dt>
		<dd>
		<t>$.nameserverSearchResults[*].[unicodeName,ldhName]</t>

		</dd>
		<dt>ipv4</dt>
		<dd>
		<t>$.nameserverSearchResults[*].ipAddresses.v4[0]</t>

		</dd>
		<dt>ipv6</dt>
		<dd>
		<t>$.nameserverSearchResults[*].ipAddresses.v6[0]</t>

		</dd>
		</dl>
		</li>
		<li>
		<t>Entity
		</t>
		<dl newline="true">
		<dt>handle</dt>
		<dd>
		<t>$.entitySearchResults[*].handle</t>

		</dd>
		<dt>fn</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="fn")][3]</t
		>

		</dd>
		<dt>org</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="org")][3]</
		t>

		</dd>
		<dt>voice</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="tel" &&
		amp; @[1].type=="voice")][3]</t>

		</dd>
		<dt>email</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="email")][3]
		</t>

		</dd>
		<dt>country</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][6
		]</t>

		</dd>
		<dt>cc</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][1].c
		c</t>

		</dd>
		<dt>city</dt>
		<dd>
		<t>$.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][3
		]</t>

		</dd>
		</dl>
		</li>
		</ul>
		<t>Additional notes on the provided jsonpaths:</t>
		<ul>
		<li>
		<t>Those related to the event dates are defined only for the
		"domain" object. To obtain the equivalent jsonpaths for
		"entity" and "nameserver", the path segment
		"domainSearchResults" must be replaced with
		"entitySearchResults" and "nameserverSearchResults",
		respectively.</t>

		</li>
		<li>Those related to jCard elements are specified without taking
		into account the "pref" parameter. Servers that sort those values
		identified by the "pref" parameter <bcp14>SHOULD</bcp14> update a
		jsonpath by adding an appropriate filter. For example, if the
		email values identified by pref="1" are considered for sorting,
		the jsonpath of the "email" sorting property should be
		$.entitySearchResults[*].vcardArray[1][?(@[0]=="email" &&
		@[1].pref=="1")][3].</li>

		</ul>
		</section>

		<section anchor="sorting_links">
		<name>Representing Sorting Links</name>
		<t>An RDAP server <bcp14>MAY</bcp14> use the "links" array of the "sor
		ting_metadata" element to provide ready-made references <xref target="RFC8288"/>
		to the available sort criteria (<xref target="sort-link-in-response-example"/>)
		. Each link represents a reference to an alternate view of the results.</t>
		<t>The "value", "rel", and "href" JSON values <bcp14>MUST</bcp14> be s
		pecified. All other JSON values are <bcp14>OPTIONAL</bcp14>.</t>
		<figure anchor="sort-link-in-response-example">
		<name>Example of a "sorting_metadata" Instance to Implement Result S
		orting</name>

		<sourcecode type="json">
	{	{
	"rdapConformance": [	"rdapConformance": [
	"rdap_level_0",	"rdap_level_0",
	"sorting"	"sorting"
	],	],
	...	...
	"sorting_metadata": {	"sorting_metadata": {
	"currentSort": "name",	"currentSort": "name",
	"availableSorts": [	"availableSorts": [
	{	{
	"property": "registrationDate",	"property": "registrationDate",
	"jsonPath": "$.domainSearchResults[*]	"jsonPath": "$.domainSearchResults[*]
	.events[?(@.eventAction==\"registration\")].eventDate",	.events[?(@.eventAction==\"registration\")].eventDate",
	"default": false,	"default": false,
	"links": [	"links": [
	{	{
	"value": "https://example.com/rdap/domains?name=example*.com	"value": "https://example.com/rdap/domains?name=example*.com

	&sort=name",	&sort=name",
	"rel": "alternate",	"rel": "alternate",
	"href": "https://example.com/rdap/domains?name=example*.com	"href": "https://example.com/rdap/domains?name=example*.com

	&sort=registrationDate",	&sort=registrationDate",
	"title": "Result Ascending Sort Link",	"title": "Result Ascending Sort Link",
	"type": "application/rdap+json"	"type": "application/rdap+json"
	},	},
	{	{
	"value": "https://example.com/rdap/domains?name=example*.com	"value": "https://example.com/rdap/domains?name=example*.com

	&sort=name",	&sort=name",
	"rel": "alternate",	"rel": "alternate",
	"href": "https://example.com/rdap/domains?name=example*.com	"href": "https://example.com/rdap/domains?name=example*.com

	&sort=registrationDate:d",	&sort=registrationDate:d",
	"title": "Result Descending Sort Link",	"title": "Result Descending Sort Link",
	"type": "application/rdap+json"	"type": "application/rdap+json"
	}	}
	]	]
	},	},
	...	...
	]	]
	},	},
	"domainSearchResults": [	"domainSearchResults": [
	...	...
	]	]
	}	}

	]]></artwork>	</sourcecode>
	</figure>	</figure>
	</section>	</section>
		</section>
	</section>	<section anchor="cursor-parameter">
		<name>"cursor" Parameter</name>
	<section anchor="cursor-parameter" title=""cursor" Parameter">

	<t>The cursor parameter defined in this specification can be used to enco
	de information about any pagination method. For example, in the case of a simpl
	e implementation of the cursor parameter to represent offset pagination informat
	ion, the cursor value "b2Zmc2V0PTEwMCxsaW1pdD01MA==" is the Base64 enc
	oding of "offset=100,limit=50". Likewise, in a simple implementation
	to represent keyset pagination information, the cursor value "ZXhhbXBsZS1OL
	mNvbQ==" represents the Base64 encoding of "key=example-N.com" wh
	ereby the key value identifies the last row of the current page.</t>

	<t>Note that this specification uses a Base64 encoding for cursor obfuscatio
	n just for example. RDAP servers are NOT RECOMMENDED to obfuscate a cursor valu
	e through a mere Base64 encoding.</t>


	<t>This solution lets RDAP providers implement a pagination method accord	<t>The "cursor" parameter defined in this specification can be used to
	ing to their needs, a user's access level, and the submitted query. Besides, se	encode information about any pagination method. For example, in the
	rvers can change the method over time without announcing anything to clients. T	case of a simple implementation of the "cursor" parameter to represent
	he considerations that have led to this solution are described in more detail in	offset pagination information, the "cursor" value
	<xref target="approaches-to-result-pagination"/>.</t>	"b2Zmc2V0PTEwMCxsaW1pdD01MA==" is the base64 encoding of
		"offset=100,limit=50". Likewise, in a simple implementation to
		represent keyset pagination information, the "cursor" value
		"ZXhhbXBsZS1OLmNvbQ==" represents the base64 encoding of
		"key=example-N.com" whereby the key value identifies the last row of
		the current page.</t>


	<t>The ABNF syntax of the cursor parameter is the following:</t>	<t>Note that this specification uses a base64 encoding for cursor
	<t><list style="empty">	obfuscation just for example. RDAP servers are <bcp14>NOT
	<t>cursor = "cursor=" 1*( ALPHA / DIGIT / "/"	RECOMMENDED</bcp14> to obfuscate the "cursor" value through a mere
	/ "=" / "-" / "_" )</t>	base64 encoding.</t>
	</list></t>


	<t>The following is an example of an RDAP query including the "cursor	<t>This solution lets RDAP providers implement a pagination method
	" parameter:</t>	according to their needs, a user's access level, and the submitted
		query. Besides, servers can change the method over time without
		announcing anything to clients. The considerations that have led to
		this solution are described in more detail in <xref
		target="approaches-to-result-pagination"/>.</t>


	<t>https://example.com/rdap/domains?name=example*.com	<t>The ABNF syntax of the "cursor" parameter is the following:</t>
		<sourcecode type="abnf">
		cursor = "cursor=" 1*( ALPHA / DIGIT / "/" / "=" / "-" / "_" )
		</sourcecode>
		<t>The following is an example of an RDAP query including the "cursor" p
		arameter:</t>
		<t>https://example.com/rdap/domains?name=example*.com
	&cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=	&cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=

	</t>	</t>
		<section anchor="cursor_paging_links">
	<section anchor="cursor_paging_links" title="Representing Paging Links">	<name>Representing Paging Links</name>
		<t>An RDAP server <bcp14>SHOULD</bcp14> use the "links" array of the "
	<t>An RDAP server SHOULD use the "links" array of the "pag	paging_metadata" element to provide a ready-made reference <xref target="RFC8288
	ing_metadata" element to provide a ready-made reference <xref target="RFC82	"/> to the next page of the result set (<xref target="cursor-pagination-link-in-
	88"/> to the next page of the result set (<xref target="cursor-pagination-link-i	response-example"/>). Examples of additional "rel" values a server <bcp14>MAY</
	n-response-example"/>). Examples of additional "rel" values a server	bcp14> implement are "first", "last", and "prev".</t>
	MAY implement are "first", "last", and "prev".</t>	<figure anchor="cursor-pagination-link-in-response-example">
		<name>Example of a "paging_metadata" Instance to Implement Cursor Pa
	<figure anchor="cursor-pagination-link-in-response-example" title="Example	gination</name>
	of a "paging_metadata" instance to implement cursor pagination">	<sourcecode type="json">
	<artwork xml:space="preserve"><![CDATA[

	{	{
	"rdapConformance": [	"rdapConformance": [
	"rdap_level_0",	"rdap_level_0",
	"paging"	"paging"
	],	],
	...	...
	"notices": [	"notices": [
	{	{
	"title": "Search query limits",	"title": "Search query limits",
	"type": "result set truncated due to excessive load",	"type": "result set truncated due to excessive load",

	skipping to change at line 496 ¶	skipping to change at line 818 ¶
	],	],
	"paging_metadata": {	"paging_metadata": {
	"totalCount": 73,	"totalCount": 73,
	"pageSize": 50,	"pageSize": 50,
	"pageNumber": 1,	"pageNumber": 1,
	"links": [	"links": [
	{	{
	"value": "https://example.com/rdap/domains?name=example*.com",	"value": "https://example.com/rdap/domains?name=example*.com",
	"rel": "next",	"rel": "next",
	"href": "https://example.com/rdap/domains?name=example*.com	"href": "https://example.com/rdap/domains?name=example*.com

	&cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=",	&cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=",
	"title": "Result Pagination Link",	"title": "Result Pagination Link",
	"type": "application/rdap+json"	"type": "application/rdap+json"
	}	}
	]	]
	},	},
	"domainSearchResults": [	"domainSearchResults": [
	...	...
	]	]
	}	}

	]]></artwork>	</sourcecode>
	</figure>	</figure>
		</section>
	</section>	</section>
		</section>
	</section>	<section anchor="negative-answers">
		<name>Negative Answers</name>
	</section>


	<section anchor="negative-answers" title="Negative Answers">	<t>The constraints for the values of parameters are defined by their ABNF
	<t>The constraints for the parameters values are defined by their ABNF syn	syntax. Therefore, each request that includes an invalid value for a
	tax. Therefore, each request that includes an invalid value for a parameter SHO	parameter <bcp14>SHOULD</bcp14> produce an HTTP 400 (Bad Request)
	ULD produce an HTTP 400 (Bad Request) response code. The same response SHOULD b	response code. The same response <bcp14>SHOULD</bcp14> be returned in
	e returned in the following cases:	the following cases:


	<list style="symbols">	</t>
	<t>if in both single and multi sort the client provides an unsupported value for	<ul>
	the "sort" parameter, as well as a value related to an object propert
	y not included in the response;<vspace blankLines='1' /></t>
	<t>if the client submits an invalid value for the "cursor" parameter.<
	/t>
	</list></t>


	<t>Optionally, the response MAY include additional information regarding	<li>
	either the supported sorting properties or the correct cursor values in the HTTP	<t>if sorting by either single or multiple properties, the client provides an
	entity body (<xref target="sorting-property-error"/>).</t>	unsupported value for the "sort" parameter, as well as a value related to an
		object property not included in the response
		</t>


	<figure anchor="sorting-property-error" title="Example of RDAP error respo	</li>
	nse due to an invalid domain sorting property included in the request">	<li>if the client submits an invalid value for the "cursor" parameter</l
	<artwork xml:space="preserve">	i>
		</ul>
		<t>Optionally, the response <bcp14>MAY</bcp14> include additional informat
		ion regarding either the supported sorting properties or the correct "cursor" va
		lue in the HTTP entity body (<xref target="sorting-property-error"/>).</t>


		<figure anchor="sorting-property-error">
		<name>Example of RDAP Error Response Due to an Invalid Domain Sorting Pr
		operty Included in the Request</name>
		<sourcecode type="json">
	{	{
	"errorCode": 400,	"errorCode": 400,

	"title": "Domain sorting property 'unknownproperty' is not valid",	"title": "Domain sorting property 'unknown' is not valid",
	"description": [	"description": [

	"Supported domain sorting properties are: 'aproperty', 'anotherproperty'	"Supported domain sorting properties are:"
	."	"'aproperty', 'anotherproperty'"
	]	]

	}	}

	</artwork>	</sourcecode>
	</figure>	</figure>
	</section>	</section>
		<section anchor="implementation-considerations">
		<name>Implementation Considerations</name>
		<t>Implementation of the new parameters is technically feasible, as
		operators for counting, sorting, and paging are currently supported by
		the major relational database management systems. Similar operators are
		completely or partially supported by the most well-known NoSQL databases
		(e.g., MongoDB, CouchDB, HBase, Cassandra, Hadoop, etc.). Additional
		implementation notes are included in <xref
		target="additional-implementation-notes"/>.</t>
		</section>
		<section anchor="IANA-considerations">
		<name>IANA Considerations</name>


	<section anchor="implementation-considerations" title="Implementation Conside	<t>IANA has registered the following values in the "RDAP Extensions"
	rations">	registry:</t>
	<t>Implementation of the new parameters is technically feasible, as operat
	ors for counting, sorting and paging are currently supported by the major relati
	onal database management systems. Similar operators are completely or partially
	supported by the most well-known NoSQL databases (e.g. MongoDB, CouchDB, HBase,
	Cassandra, Hadoop). Additional implementation notes are included in <xref targ
	et="additional-implementation-notes"/>.</t>
	</section>


	<section anchor="IANA-considerations" title="IANA Considerations">	<dl spacing="compact">


	<t>IANA is requested to register the following values in the RDAP Extensi	<dt>Extension identifier:
	ons Registry:</t>	</dt>
		<dd>paging
		</dd>


	<t><list style="none">	<dt>Registry operator:
	<t>Extension identifier: paging</t>	</dt>
	<t>Registry operator: Any</t>	<dd>Any
	<t>Published specification: This document.</t>	</dd>
	<t>Contact: IETF <iesg@ietf.org></t>
	<t>Intended usage: This extension describes best practice for result set p
	aging.</t>
	</list></t>


	<t><list style="none">	<dt>Published specification:
	<t>Extension identifier: sorting</t>	</dt>
	<t>Registry operator: Any</t>	<dd>RFC 8977
	<t>Published specification: This document.</t>	</dd>
	<t>Contact: IETF <iesg@ietf.org></t>
	<t>Intended usage: This extension describes best practice for result set s
	orting.</t>
	</list></t>


	</section>	<dt>Contact:
		</dt>
		<dd>IETF <iesg@ietf.org>
		</dd>


	<section anchor="impl-status" title="Implementation Status">	<dt>Intended usage:
	<t>NOTE: Please remove this section and the reference to RFC 7942 prior to	</dt>
	publication as an RFC.</t>	<dd>This extension describes a best practice for result set paging.
		</dd>


	<t>This section records the status of known implementations of the protoco l defined by this specification at the time of posting of this Internet-Draft, a nd is based on a proposal described in <xref target="RFC7942"/>. The descriptio n of implementations in this section is intended to assist the IETF in its decis ion processes in progressing drafts to RFCs. Please note that the listing of an y individual implementation here does not imply endorsement by the IETF. Furthe rmore, no effort has been spent to verify the information presented here that wa s supplied by IETF contributors. This is not intended as, and must not be const rued to be, a catalog of available implementations or their features. Readers a re advised to note that other implementations may exist.</t>	</dl>


	<t>According to RFC 7942, "this will allow reviewers and working grou ps to assign due consideration to documents that have the benefit of running cod e, which may serve as evidence of valuable experimentation and feedback that hav e made the implemented protocols more mature. It is up to the individual workin g groups to use this information as they see fit".</t>	<dl spacing="compact">


	<section anchor="iit-cnr-registro-it" title="IIT-CNR/Registro.it">	<dt>Extension identifier:
	<t><list style="none">	</dt>
	<t>Responsible Organization: Institute of Informatics and Telematics of	<dd>sorting
	the National Research Council (IIT-CNR)/Registro.it</t>	</dd>
	<t>Location: https://rdap.pubtest.nic.it/</t>
	<t>Description: This implementation includes support for RDAP queries u
	sing data from .it public test environment.</t>
	<t>Level of Maturity: This is an "alpha" test implementation.</t>
	<t>Coverage: This implementation includes all of the features described
	in this specification.</t>
	<t>Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it</t>
	</list></t>
	</section>


	<section anchor="apnic" title="APNIC">	<dt>Registry operator:
	<t><list style="none">	</dt>
	<t>Responsible Organization: Asia-Pacific Network Information Centre</t	<dd>Any
	>	</dd>
	<t>Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/sorting-an
	d-paging</t>
	<t>Description: A proof-of-concept for RDAP mirroring.</t>
	<t>Level of Maturity: This is a proof-of-concept implementation.</t>
	<t>Coverage: This implementation includes all of the features described
	in the specification except for nameserver sorting and unicodeName sorting.</t>
	<t>Contact Information: Tom Harrison, tomh@apnic.net</t>
	</list></t>
	</section>


	</section>	<dt>Published specification:
		</dt>
		<dd>RFC 8977
		</dd>


	<section anchor="security-considerations" title="Security Considerations">	<dt>Contact:
	<t>Security services for the operations specified in this document are des	</dt>
	cribed in <xref target="RFC7481"/>.</t>	<dd>IETF <iesg@ietf.org>
		</dd>


	<t>A search query typically requires more server resources (such as memory	<dt>Intended usage:
	, CPU cycles, and network bandwidth) when compared to a lookup query. This incr	</dt>
	eases the risk of server resource exhaustion and subsequent denial of service.	<dd>This extension describes a best practice for result set sorting.
	This risk can be mitigated by either restricting search functionality or limitin	</dd>
	g the rate of search requests. Servers can also reduce their load by truncating
	the results in a response. However, this last security policy can result in a
	higher inefficiency or risk due to acting on incomplete information if the RDAP
	server does not provide any functionality to return the truncated results.</t>


	<t>The new parameters presented in this document provide RDAP operators wi	</dl>
	th a way to implement a server that reduces inefficiency risks. The "count
	" parameter gives the client the ability to evaluate the completeness of a	</section>
	response. The "sort" parameter allows the client to obtain the most r
	elevant information at the beginning of the result set. This can reduce the num
	ber of unnecessary search requests. Finally, the "cursor" parameter e
	nables the user to scroll the result set by submitting a sequence of sustainable
	queries within server-acceptable limits.</t>
	</section>


		<section anchor="security-considerations">
		<name>Security Considerations</name>
		<t>Security services for the operations specified in this document are des
		cribed in <xref target="RFC7481"/>.</t>
		<t>A search query typically requires more server resources (such as memory
		, CPU cycles, and network bandwidth) when compared to a lookup query. This incr
		eases the risk of server resource exhaustion and subsequent denial of service.
		This risk can be mitigated by either restricting search functionality or limitin
		g the rate of search requests. Servers can also reduce their load by truncating
		the results in a response. However, this last security policy can result in a
		higher inefficiency or risk due to acting on incomplete information if the RDAP
		server does not provide any functionality to return the truncated results.</t>
		<t>The new parameters presented in this document provide RDAP operators wi
		th a way to implement a server that reduces inefficiency risks. The "count" par
		ameter gives the client the ability to evaluate the completeness of a response.
		The "sort" parameter allows the client to obtain the most relevant information
		at the beginning of the result set. This can reduce the number of unnecessary s
		earch requests. Finally, the "cursor" parameter enables the user to scroll the
		result set by submitting a sequence of sustainable queries within server-accepta
		ble limits.</t>
		</section>
	</middle>	</middle>
	<back>	<back>

	<references title="Normative References">
	&RFC2119;
	&RFC5234;
	&RFC5890;
	&RFC6350;
	&RFC7095;
	&RFC7230;
	&RFC7231;
	&RFC7480;
	&RFC7481;
	&RFC7482;
	&RFC7483;
	&RFC7942;
	&RFC8174;
	&RFC8259;
	&RFC8288;
	&RFC8605;
	</references>


	<references title="Informative References">	<references>
	<reference anchor='CURSOR' target='https://www.sitepoint.com/paginating-real	<name>References</name>
	-time-data-cursor-based-pagination/'>	<references>
	<front>	<name>Normative References</name>
	<title>Paginating Real-Time Data with Keyset Pagination</title>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<author initials='R.' surname='Nimesh' fullname='Rakhitha Nimesh'	FC.2119.xml"/>
	>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	</author>	FC.5234.xml"/>
	<date year='2014' month='July' />	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	</front>	FC.5890.xml"/>
	</reference>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<reference anchor='CURSOR-API1' target='https://developers.facebook.com/docs	FC.6350.xml"/>
	/graph-api/using-graph-api'>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<front>	FC.7095.xml"/>
	<title>facebook for developers - Using the Graph API</title>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<author>	FC.7230.xml"/>
	<organization>facebook.com</organization>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	</author>	FC.7231.xml"/>
	<date year='2017' month='July' />	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	</front>	FC.7480.xml"/>
	</reference>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<reference anchor='CURSOR-API2' target='https://developer.twitter.com/en/doc	FC.7481.xml"/>
	s/ads/general/guides/pagination.html'>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<front>	FC.7482.xml"/>
	<title>Pagination</title>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
	<author>	FC.7483.xml"/>
	<organization>twitter.com</organization>
		<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
		FC.8174.xml"/>
		<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
		FC.8259.xml"/>
		<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
		FC.8288.xml"/>
		<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
		FC.8605.xml"/>
		</references>
		<references>
		<name>Informative References</name>

		<reference anchor="CURSOR" target="https://www.sitepoint.com/paginating-
		real-time-data-cursor-based-pagination/">
		<front>
		<title>Paginating Real-Time Data with Cursor Based Pagination</title
		>
		<author initials="R." surname="Nimesh" fullname="Rakhitha Nimesh">
	</author>	</author>

	<date year='2017'/>	<date year="2014" month="July"/>
	</front>	</front>
	</reference>	</reference>
	<reference anchor='GOESSNER-JSON-PATH' target='http://goessner.net/artic
	les/JsonPath/'>	<reference anchor="CURSOR-API1" target="https://developers.facebook.com/
	<front>	docs/graph-api/using-graph-api">
	<title>JSONPath - XPath for JSON</title>	<front>
	<author initials='S.' surname='Goessner' fullname='Stefan Goessn	<title>Facebook for Developers -- Using the Graph API</title>
	er'>	<author>
		<organization>Facebook</organization>
		</author>
		<date />
		</front>
		</reference>

		<reference anchor="CURSOR-API2" target="https://developer.twitter.com/en
		/docs/twitter-ads-api">
		<front>
		<title>Twitter Ads API</title>
		<author>
		<organization>Twitter</organization>
		</author>
		<date />
		</front>
		</reference>

		<reference anchor="GOESSNER-JSON-PATH" target="https://goessner.net/arti
		cles/JsonPath/">
		<front>
		<title>JSONPath - XPath for JSON</title>
		<author initials="S." surname="Goessner" fullname="Stefan Goessner">
	</author>	</author>

	<date year='2007'/>	<date year="2007" month="February"/>
	</front>	</front>
	</reference>	</reference>

	<reference anchor='HATEOAS' target='https://www.e4developer.com/2018/02/16/h
	ateoas-simple-explanation/'>	<reference anchor="HATEOAS" target="https://www.e4developer.com/2018/02/
	<front>	16/hateoas-simple-explanation/">
	<title>HATEOAS - a simple explanation</title>	<front>
	<author initials='B.' surname='Jedrzejewski' fullname='Bartosz Je	<title>HATEOAS - a simple explanation</title>
	drzejewski'>	<author initials="B." surname="Jedrzejewski" fullname="Bartosz Jedrz
	</author>	ejewski">
	<date year='2018'/>
	</front>
	</reference>
	<reference anchor='JSONPATH-COMPARISON' target='https://cburgmer.github.io/j
	son-path-comparison/'>
	<front>
	<title>JSONPath Comparison</title>
	<author/>
	<date year='2020'/>
	</front>
	</reference>
	<reference anchor='JSONPATH-WG' target='https://datatracker.ietf.org/wg/json
	path/documents/'>
	<front>
	<title>JSON Path (jsonpath)</title>
	<author/>
	<date year='2020'/>
	</front>
	</reference>
	<reference anchor='OData-Part1' target='http://docs.oasis-open.org/odata/od
	ata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protoc
	ol-complete.pdf'>
	<front>
	<title>OData Version 4.0. Part 1: Protocol Plus Errata 03</title>
	<author initials='M.' surname='Pizzo' fullname='Michael Pizzo'>
	</author>
	<author initials='R.' surname='Handl' fullname='Ralf Handl'>
	</author>	</author>

	<author initials='M.' surname='Zurmuehl' fullname='Martin Zurmueh	<date year="2018" month="February"/>
	l'>	</front>
		</reference>

		<reference anchor="JSONPATH-COMPARISON" target="https://cburgmer.github.
		io/json-path-comparison/">
		<front>
		<title>JSONPath Comparison</title>
		<author/>
		<date />
		</front>
		</reference>

		<reference anchor="JSONPATH-WG" target="https://datatracker.ietf.org/wg/
		jsonpath/about/">
		<front>
		<title>JSON Path (jsonpath)</title>
		<author><organization>IETF</organization></author>
		<date/>
		</front>
		</reference>

		<reference anchor="ODATA-PART1" target="https://docs.oasis-open.org/odat
		a/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-pr
		otocol-complete.pdf">
		<front>
		<title>OData Version 4.0. Part 1: Protocol Plus Errata 03</title>
		<author initials="M." surname="Pizzo" fullname="Michael Pizzo">
	</author>	</author>

	<date year='2016' month='June' />	<author initials="R." surname="Handl" fullname="Ralf Handl">
	</front>
	</reference>
	<reference anchor='REST' target='http://www.ics.uci.edu/~fielding/pubs/disse
	rtation/fielding_dissertation.pdf'>
	<front>
	<title>Architectural Styles and the Design of Network-based Softw
	are Architectures</title>
	<author initials='R.' surname='Fielding' fullname='Roy Thomas Fie
	lding'>
	<organization>PH.D. DISSERTATION, UNIVERSITY OF CALIFORNIA, IRVI
	NE</organization>
	</author>	</author>

	<date year='2000'/>	<author initials="M." surname="Zurmuehl" fullname="Martin Zurmuehl">
	</front>
	</reference>
	&RFC6901;
	<reference anchor='SEEK' target='https://www.eversql.com/faster-pagination-i
	n-mysql-why-order-by-with-limit-and-offset-is-slow/'>
	<front>
	<title>Faster Pagination in Mysql - Why Order By With Limit and O
	ffset is Slow?</title>
	<author>
	<organization>EverSQL.com</organization>
	</author>	</author>

	<date year='2017' month='July' />	<date year="2016" month="June"/>
	</front>	</front>
	</reference>	</reference>
	&W3C.CR-xpath-31-20161213;
	</references>


	<section anchor="jsonpath-operators" title="JSONPath operators">	<reference anchor="REST" target="https://www.ics.uci.edu/~fielding/pubs/
		dissertation/fielding_dissertation.pdf">
		<front>
		<title>Architectural Styles and the Design of Network-based Software
		Architectures</title>
		<author initials="R." surname="Fielding" fullname="Roy Thomas Fieldi
		ng">
		<organization>PH.D. DISSERTATION, UNIVERSITY OF CALIFORNIA, IRVINE
		</organization>
		</author>
		<date year="2000"/>
		</front>
		</reference>


	<t>The jsonpaths used in this document are provided according to the Goessner v. 0.8.0 proposal <xref target="GOESSNER-JSON-PATH"/>.</t>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R FC.6901.xml"/>


	<t>Such specification requires that implementations support a set of "basic	<reference anchor="SEEK" target="https://www.eversql.com/faster-paginati
	operators". These operators are used to access the elements of a JSON str	on-in-mysql-why-order-by-with-limit-and-offset-is-slow/">
	ucture like objects and arrays, and their subelements, respectively, object memb	<front>
	ers and array items. No operations are defined for retrieving parent or sibling	<title>Faster Pagination in Mysql - Why Order By With Limit and Offs
	elements of a given element. The root element is always referred to as $ regar	et is Slow?</title>
	dless of it being an object or array.</t>	<author>
		<organization>EverSQL</organization>
		</author>
		<date year="2017" month="July"/>
		</front>
		</reference>


	<t>Additionally, the specification permits implementations to support arbitrary	<reference anchor="W3C.CR-xpath-31-20170321" target="https://www.w3.org/
	script expressions. These can be used to index into an object or array, or to f	TR/2017/REC-xpath-31-20170321/">
	ilter elements from an array. While script expression behavior is implementatio	<front>
	n-defined, most implementations support the basic relational and logical operato	<title>XML Path Language (XPath) 3.1</title>
	rs, as well as both object member and array item access, sufficiently similar fo	<author initials="J." surname="Robie" fullname="Jonathan Robie">
	r the purpose of this document. Commonly-supported operators/functions divided	<organization/>
	into "top-level operators" and "filter operators" are docume	</author>
	nted in <xref target="table_json_path_top_level_operators"/> and <xref target="t	<author initials="M." surname="Dyck" fullname="Michael Dyck">
	able_json_path_filter_operators"/> respectively.</t>	<organization/>
		</author>
		<author initials="J." surname="Spiegel" fullname="Josh Spiegel">
		<organization/>
		</author>
		<date month="March" year="2017"/>
		</front>
		<refcontent>World Wide Web Consortium Recommendation REC-xpath-31-2017
		0321</refcontent>
		</reference>
		</references>


	<t>For more information on implementation interoperability issues, see [JSONPATH -COMPARISON]. As at the time of writing, work is beginning on a standardization effort, too: see [JSONPATH-WG].</t>	</references>


	<texttable anchor="table_json_path_top_level_operators" title="JSONPath T	<section anchor="jsonpath-operators">
	op-Level Operators">	<name>JSONPath Operators</name>
	<ttcol align="left">Operator</ttcol>	<t>The jsonpaths used in this document are provided according to the Goess
	<ttcol align="left">Description</ttcol>	ner proposal <xref target="GOESSNER-JSON-PATH"/>.</t>
	<c>$</c><c>Root element</c>	<t>Such specification requires that implementations support a set of
	<c>.<name></c><c>Object member access (dot-notation)</c>	"basic operators". These operators are used to access the elements of a
	<c>['<name>']</c><c>Object member access (bracket-notation)</c>	JSON structure like objects and arrays, as well as their subelements
	<c>[<number>]</c><c>Array item access</c>	(object members and array items, respectively). No operations are
	<c>*</c><c>All elements within the specified scope</c>	defined for retrieving parent or sibling elements of a given element.
	<c>[?(<expression>)]</c><c>Filter expression</c>	The root element is always referred to as $ regardless of it being an
	</texttable>	object or array.</t>
		<t>Additionally, the specification permits implementations to support
		arbitrary script expressions. These can be used to index into an object
		or array, or to filter elements from an array. While script expression
		behavior is implementation-defined, most implementations support the
		basic relational and logical operators as well as both object member and
		array item access, sufficiently similar for the purpose of this
		document. Commonly supported operators/functions divided into
		"top-level operators" and "filter operators" are documented in Tables <xre
		f
		target="table_json_path_top_level_operators" format="counter"/> and <xref
		target="table_json_path_filter_operators" format="counter"/>, respectively
		.</t>
		<t>For more information on implementation interoperability issues, see
		<xref target="JSONPATH-COMPARISON" format="default"/>. At the time
		of writing, work is beginning on a standardization effort too (see
		<xref target="JSONPATH-WG" format="default"/>).</t>
		<table anchor="table_json_path_top_level_operators">
		<name>JSONPath Top-Level Operators</name>
		<thead>
		<tr>
		<th align="left">Operator</th>
		<th align="left">Description</th>
		</tr>
		</thead>
		<tbody>
		<tr>
		<td align="left">$</td>
		<td align="left">Root element</td>
		</tr>
		<tr>
		<td align="left">.<name></td>
		<td align="left">Object member access (dot-notation)</td>
		</tr>
		<tr>
		<td align="left">['<name>']</td>
		<td align="left">Object member access (bracket-notation)</td>
		</tr>
		<tr>
		<td align="left">[<number>]</td>
		<td align="left">Array item access</td>
		</tr>
		<tr>
		<td align="left">*</td>
		<td align="left">All elements within the specified scope</td>
		</tr>
		<tr>
		<td align="left">[?(<expression>)]</td>
		<td align="left">Filter expression</td>
		</tr>
		</tbody>
		</table>
		<table anchor="table_json_path_filter_operators">
		<name>JSONPath Filter Operators</name>
		<thead>
		<tr>
		<th align="left">Operator</th>
		<th align="left">Description</th>
		</tr>
		</thead>
		<tbody>
		<tr>
		<td align="left">@</td>
		<td align="left">Current element being processed</td>
		</tr>
		<tr>
		<td align="left">.<name></td>
		<td align="left">Object member access</td>
		</tr>
		<tr>
		<td align="left">.[<name1>,<name2>]</td>
		<td align="left">Union of object members</td>
		</tr>
		<tr>
		<td align="left">[<number>]</td>
		<td align="left">Array item access</td>
		</tr>
		<tr>
		<td align="left">==</td>
		<td align="left">Left is equal to right</td>
		</tr>
		<tr>
		<td align="left">!=</td>
		<td align="left">Left is not equal to right</td>
		</tr>
		<tr>
		<td align="left"><</td>
		<td align="left">Left is less than right</td>
		</tr>
		<tr>
		<td align="left"><=</td>
		<td align="left">Left is less than or equal to right</td>
		</tr>
		<tr>
		<td align="left">></td>
		<td align="left">Left is greater than right</td>
		</tr>
		<tr>
		<td align="left">>=</td>
		<td align="left">Left is greater than or equal to right</td>
		</tr>
		<tr>
		<td align="left">&&</td>
		<td align="left">Logical conjunction</td>
		</tr>
		<tr>
		<td align="left">\|\|</td>
		<td align="left">Logical disjunction</td>
		</tr>
		</tbody>
		</table>
		</section>
		<section anchor="approaches-to-result-pagination">


	<texttable anchor="table_json_path_filter_operators" title="JSONPath Filt	<name>Approaches to Result Pagination</name>
	er Operators">	<t>An RDAP query could return a response with hundreds, even thousands, of
	<ttcol align="left">Operator</ttcol>	objects, especially when partial matching is used. For this reason, the "curso
	<ttcol align="left">Description</ttcol>	r" parameter addressing result pagination is defined to make responses easier to
	<c>@</c><c>Current element being processed</c>	handle.</t>
	<c>.<name></c><c>Object member access</c>	<t>Presently, the most popular methods to implement pagination in a REST A
	<c>.[<name1>,<name2>]</c><c>Union of object members</c>	PI include offset pagination and keyset pagination. Neither pagination method r
	<c>[<number>]</c><c>Array item access</c>	equires the server to handle the result set in a storage area across multiple re
	<c>==</c><c>Left is equal to right</c>	quests since a new result set is generated each time a request is submitted. Th
	<c>!=</c><c>Left is not equal to right</c>	erefore, they are preferred to any other method requiring the management of a RE
	<c><</c><c>Left is less than right</c>	ST session.</t>
	<c><=</c><c>Left is less than or equal to right</c>	<t>Using limit and offset operators represents the traditionally used meth
	<c>></c><c>Left is greater than right</c>	od to implement result pagination. Both of them can be used individually:
	<c>>=</c><c>Left is greater than or equal to right</c>	</t>
	<c>&&</c><c>Logical conjunction</c>	<dl>
	<c>\|\|</c><c>Logical disjunction</c>
	</texttable>


	</section>	<dt>"limit=N":
		</dt>
		<dd>means that the server returns the first N objects of the result set
		</dd>


	<section anchor="approaches-to-result-pagination" title="Approaches to Result Pa	<dt>"offset=N":
	gination">	</dt>
		<dd>means that the server skips the first N objects and returns objects starting
		from position N+1
		</dd>


	<t>An RDAP query could return a response with hundreds, even thousands, o f objects, especially when partial matching is used. For this reason, the curso r parameter addressing result pagination is defined to make responses easier to handle.</t>	</dl>


	<t>Presently, the most popular methods to implement pagination in a REST API inc	<t>When limit and offset are used together, they provide the ability to id
	lude offset pagination and keyset pagination. Neither pagination method require	entify a specific portion of the result set. For example, the pair "offset=100,
	s the server to handle the result set in a storage area across multiple requests	limit=50" returns the first 50 objects starting from position 101 of the result
	since a new result set is generated each time a request is submitted. Therefor	set.</t>
	e, they are preferred to any other method requiring the management of a REST ses	<t>Though easy to implement, offset pagination also includes drawbacks:
	sion.</t>	</t>
		<ul>
		<li>
		<t>When offset has a very high value, scrolling the result set could t
		ake some time.</t>


	<t>Using limit and offset operators represents the traditionally used method	</li>
	to implement result pagination. Both of them can be used individually:	<li>
	<list style="symbols">	<t>It always requires fetching all rows before dropping as many rows a
	<t>"limit=N": means that the server returns the first N objec	s specified by offset.</t>
	ts of the result set;<vspace blankLines='1' /></t>
	<t>"offset=N": means that the server skips the first N object
	s and returns objects starting from position N+1.</t>
	</list></t>


	<t>When limit and offset are used together, they provide the ability to identify	</li>
	a specific portion of the result set. For example, the pair "offset=100,l	<li>It may return inconsistent pages when data are frequently updated (i
	imit=50" returns the first 50 objects starting from position 101 of the res	.e., real-time data).</li>
	ult set.</t>	</ul>
		<t>Keyset pagination <xref target="SEEK"/> adds a query condition that ena
		bles the selection of the only data not yet returned. This method has been take
		n as the basis for the implementation of a "cursor" parameter <xref target="CURS
		OR"/> by some REST API providers <xref target="CURSOR-API1"/> <xref target="CURS
		OR-API2"/>. The cursor is a URL-safe string opaque to the client and representi
		ng a logical pointer to the first result of the next page.</t>


	<t>Though easy to implement, offset pagination also includes drawbacks:	<t>Nevertheless, even keyset pagination can be troublesome:
	<list style="symbols">	</t>
	<t>when offset has a very high value, scrolling the result set could	<ul>
	take some time;<vspace blankLines='1' /></t>	<li>
	<t>it always requires fetching all rows before dropping as many rows	<t>It needs at least one key field.</t>
	as specified by offset;<vspace blankLines='1' /></t>
	<t>it may return inconsistent pages when data are frequently updated (
	i.e. real-time data).</t>
	</list></t>


	<t>Keyset pagination <xref target="SEEK"/> adds a query condition that enables t	</li>
	he selection of the only data not yet returned. This method has been taken as t	<li>
	he basis for the implementation of a "cursor" parameter <xref target="	<t>It does not allow sorting simply by any field because the sorting
	CURSOR"/> by some REST API providers <xref target="CURSOR-API1"/> <xref target="	criterion must contain a key.</t>
	CURSOR-API2"/>. The cursor is an opaque to client URL-safe string representing
	a logical pointer to the first result of the next page.</t>


	<t>Nevertheless, even keyset pagination can be troublesome:	</li>
	<list style="symbols">	<li>
	<t>it needs at least one key field;<vspace blankLines='1' /></t>
	<t>it does not allow sorting simply by any field because the sorting cr
	iterion must contain a key;<vspace blankLines='1' /></t>
	<t>it works best with full composite values support by data base mana
	gement systems (i.e. [x,y]>[a,b]), emulation is possible but inelegant and less
	efficient;<vspace blankLines='1' /></t>
	<t>it does not allow direct navigation to arbitrary pages because the
	result set must be scrolled in sequential order starting from the initial page;
	<vspace blankLines='1' /></t>
	<t>implementing bi-directional navigation is tedious because all comp
	arison and sort operations have to be reversed.</t>
	</list></t>


	<section anchor="pagination-in-rdap" title="Specific Issues Raised by RDAP">	<t>It works best with full composite values supported by database
	<t>Some additional considerations can be made in the RDAP context:	management systems (i.e., [x,y]>[a,b]); emulation is possible but
	<list style="symbols">	inelegant and less efficient.</t>
	<t>an RDAP object is a conceptual aggregation of information generall
	y collected from more than one data structure (e.g. table) and this makes it eve
	n harder to implement keyset pagination, a task that is already quite difficult.
	For example, the entity object can include information from different data str
	uctures (registrars, registrants, contacts, resellers), each one with its key fi
	eld mapping the RDAP entity handle;<vspace blankLines='1' /></t>
	<t>depending on the number of page results as well as the number and
	the complexity of the properties of each RDAP object in the response, the time r
	equired by offset pagination to skip the previous pages could be much faster tha
	n the processing time needed to build the current page. In fact, RDAP objects a
	re usually formed by information belonging to multiple data structures and conta
	ining multivalued properties (i.e. arrays) and, therefore, data selection might
	therefore be a time consuming process. This situation occurs even though the se
	lection is supported by indexes;<vspace blankLines='1' /></t>
	<t>depending on the access levels defined by each RDAP operator, the
	increase in complexity and the decrease in flexibility of keyset pagination in c
	omparison to offset pagination could be considered impractical.</t>
	</list></t>


	<t>Ultimately, both pagination methods have benefits and drawbacks.</t>	</li>
		<li>
		<t>It does not allow direct navigation to arbitrary pages because
		the result set must be scrolled in sequential order starting from
		the initial page.</t>


	</section>	</li>
	</section>	<li>Implementing bidirectional navigation is tedious because all
		comparison and sort operations have to be reversed.</li>
		</ul>
		<section anchor="pagination-in-rdap">
		<name>Specific Issues Raised by RDAP</name>
		<t>Some additional considerations can be made in the RDAP context:
		</t>
		<ul>
		<li>
		<t>An RDAP object is a conceptual aggregation of information
		generally collected from more than one data structure (e.g.,
		table), and this makes it even harder to implement keyset
		pagination, a task that is already quite difficult. For example,
		the entity object can include information from different data
		structures (registrars, registrants, contacts, resellers), each
		one with its key field mapping the RDAP entity handle.</t>


	<section anchor="additional-implementation-notes" title="Additional Implem	</li>
	entation Notes">	<li>
	<t>This section contains an overview of the main choices made during the	<t>Depending on the number of page results as well as the number
	implementation of the capabilities defined above in the RDAP public test server	and the complexity of the properties of each RDAP object in the
	of Registro.it at the Institute of Informatics and Telematics of the National R	response, the time required by offset pagination to skip the
	esearch Counci (IIT-CNR). The content of this section can represent a guidance	previous pages could be much faster than the processing time
	for those implementers who plan to provide RDAP users with those capabilities.	needed to build the current page. In fact, RDAP objects are
	The RDAP public test server can be accessed at https://rdap.pubtest.nic.it/. Fu	usually formed by information belonging to multiple data
	rther documentation about the server features is available at https://rdap.pubte	structures and containing multivalued properties (i.e., arrays);
	st.nic.it/doc/README.html.</t>	therefore, data selection might be a time-consuming
		process. This situation occurs even though the selection is
		supported by indexes.</t>


	<section title="Sorting">	</li>
	<t>If no sort criterion is specified in the query string, the resu	<li>Depending on the access levels defined by each RDAP operator,
	lts are sorted by a default property: "name" for domains and nameserve	the increase in complexity and the decrease in flexibility of keyset
	rs, "handle" for entities. The server supports multiple property sort	pagination in comparison to offset pagination could be considered
	ing but the "sorting_metadata" object includes only the links to alter	impractical.</li>
	native result set views sorted by a single property just to show the list of sor	</ul>
	ting properties allowed for each searchable object. The server supports all the	<t>Ultimately, both pagination methods have benefits and
	object specific sorting properties described in the specification except for na	drawbacks.</t>
	meserver sorting based on unicodeName, that is, the "name" sorting pro	</section>
	perty is mapped onto the "ldhName" response field. Regarding the obje	</section>
	ct common properties, the sorting by registrationDate, expirationDate, lastChang	<section anchor="additional-implementation-notes">
	edDate and transferDate is supported.</t>
	</section>


	<section title="Counting">	<name>Implementation Notes</name>
	<t>The counting operation is implemented through a separate query.
	Some relational database management systems support custom operators to get th
	e total count together with the rows, but the resulting query can be considerabl
	y more expensive than that performed without the total count. Therefore, as &qu
	ot;totalCount" is an optional response information, fetching always the tot
	al number of rows has been considered an inefficient solution. Furthermore, to
	avoid the processing of unnecessary queries, when the "count" paramete
	r is included in the submitted query, it is not also repeated in the query strin
	gs of the "links" array provided in both "paging_metadata" a
	nd "sorting_metadata" objects.</t>
	</section>


	<section title="Paging">	<t>This section contains an overview of the main choices made during the
	<t>The server implements the cursor pagination through the keyset pagi	implementation of the capabilities defined in this document in the RDAP pu
	nation when sorting by a unique property is requested or the default sort is app	blic test
	lied, through offset pagination otherwise. As most of the relational database m	server of Registro.it at the Institute of Informatics and Telematics of
	anagement systems don't support the comparison of full composite values natively	the National Research Council (IIT-CNR). The content of this section
	, the implementation of full keyset pagination seem to be troublesome so, at lea	can represent guidance for implementers who plan to provide RDAP
	st initially, a selective applicability of keyset pagination is advisable. More	users with those capabilities. The RDAP public test server can be
	over, the "cursor" value encodes not only information about pagination	accessed at <eref target="https://rdap.pubtest.nic.it/"
	but also about the search pattern and the other query parameters in order to ch	brackets="angle"/>. Further documentation about the server features is
	eck the consistency of the entire query string. If the "cursor" value	available at <eref target="https://rdap.pubtest.nic.it/doc/README.html"
	is inconsistent with the rest of the query string, the server returns an error	brackets="angle"/>.</t>
	response.</t>
		<section>
		<name>Sorting</name>
		<t>If no sort criterion is specified in the query string, the results ar
		e sorted by a default property: "name" for domains and nameservers, and "handle"
		for entities. The server supports multiple property sorting but the "sorting_m
		etadata" object includes only the links to alternative result set views sorted b
		y a single property just to show the list of sorting properties allowed for each
		searchable object. The server supports all the object-specific sorting propert
		ies described in the specification except for nameserver sorting based on unicod
		eName, that is, the "name" sorting property is mapped onto the "ldhName" respons
		e field. Regarding the object-common properties, sorting by registrationDate, e
		xpirationDate, lastChangedDate, and transferDate is supported.</t>
	</section>	</section>

		<section>
		<name>Counting</name>


		<t>The counting operation is implemented through a separate query. Some relational database management systems support custom operators to get the tota l count together with the rows, but the resulting query can be considerably more expensive than that performed without the total count. Therefore, as "totalCou nt" is an optional response information, always fetching the total number of row s has been considered an inefficient solution. Furthermore, to avoid the proces sing of unnecessary queries, when the "count" parameter is included in the submi tted query, it is not also repeated in the query strings of the "links" array pr ovided in both "paging_metadata" and "sorting_metadata" objects.</t>
	</section>	</section>

		<section>
		<name>Paging</name>


	<section title="Acknowledgements" numbered="no">	<t>The server implements the cursor pagination through the keyset
	<t>The authors would like to acknowledge Brian Mountford, Tom Harrison, Ka	pagination when sorting by a unique property is requested or the
	rl Heinz Wolf, Jasdip Singh, Erik Kline, Éric Vyncke, Benjamin Kaduk and Roman D	default sort is applied. Otherwise, it implements the cursor
	anyliw for their contribution to the development of this document.</t>	pagination through the offset pagination. As most relational database
		management systems don't support the comparison of full composite
		values natively, the implementation of full keyset pagination seem to
		be troublesome so, at least initially, a selective applicability of
		keyset pagination is advisable. Moreover, the "cursor" value encodes
		not only information about pagination but also about the search
		pattern and the other query parameters in order to check the
		consistency of the entire query string. If the "cursor" value is
		inconsistent with the rest of the query string, the server returns an
		error response.</t>
		</section>
	</section>	</section>

		<section numbered="false">
	<section title="Change Log" numbered="no">	<name>Acknowledgements</name>
	<t>	<t>The authors would like to acknowledge <contact fullname="Brian Mountfor
	<list style="hanging">	d"/>, <contact fullname="Tom Harrison"/>, <contact fullname="Karl Heinz Wolf"/>,
	<t hangText="00:">Initial working group version ported from draft-loff	<contact fullname="Jasdip Singh"/>, <contact fullname="Erik Kline"/>, <contact
	redo-regext-rdap-sorting-and-paging-05</t>	fullname="Éric Vyncke"/>, <contact fullname="Benjamin Kaduk"/>, and <contact ful
	<t hangText="01:">Removed both "offset" and "nextOffse	lname="Roman Danyliw"/> for their contributions to the development of this docum
	t" to keep "paging_metadata" consistent between the pagination m	ent.</t>
	ethods. Renamed "Considerations about Paging Implementation" section
	in ""cursor" Parameter". Removed "FOR DISCUSSION"
	items. Provided a more detailed description of both "sorting_metadata&quo
	t; and "paging_metadata" objects.</t>
	<t hangText="02:">Removed both "offset" and "limit&quo
	t; parameters. Added ABNF syntax of the cursor parameter. Rearranged the layou
	t of some sections. Removed some items from "Informative References"
	section. Changed "IANA Considerations" section.</t>
	<t hangText="03:">Added "cc" to the list of sorting propert
	ies in "Sorting Properties Declaration" section. Added RFC8605 to the
	list of "Informative References".</t>
	<t hangText="04:">Replaced "ldhName" with "name"
	in the "Sorting Properties Declaration" section. Clarified the sortin
	g logic for the JSON value types and the sorting policy for multivalued fields.<
	/t>
	<t hangText="05:">Clarified the logic of sorting on IP addresses. Cl
	arified the mapping between the sorting properties and the RDAP response fields.
	Updated "Acknowledgements" section.</t>
	<t hangText="06:">Renamed "pageCount" to "pageSize&quo
	t; and added "pageNumber" in the "paging_metadata" object.</
	t>
	<t hangText="07:">Added "Paging Responses to POST Requests"
	section.</t>
	<t hangText="08:">Added "Approaches to Result Pagination" s
	ection to appendix. Added the case of requesting a sort on a property not inclu
	ded in the response to the errors listed in the "Negative Answers" sec
	tion.</t>
	<t hangText="09:">Updated the "Implementation Status" secti
	on to include APNIC implementation. Moved the "RDAP Conformance" sect
	ion up in the document. Removed the "Paging Responses to POST Requests&quo
	t; section. Updated the "Acknowledgements" section. Removed unused r
	eferences. In the "Sorting Properties Declaration" section:
	<list style="symbols">
	<t>clarified the logic of sorting on events;</t>
	<t>corrected the jsonpath of the "lastChanged" sorting proper
	ty;</t>
	<t>provided a JSONPath example taking into account the vCard "pref
	" parameter.</t>
	</list>
	</t>
	<t hangText="10:">Corrected the jsonpaths of both "fn" and
	"org" sorting properties in Table 2. Corrected JSON content in <xref
	target="sort-link-in-response-example"/>. Moved <xref target="W3C.CR-xpath-31-2
	0161213"/> and <xref target="RFC7942"/> to the "Normative References".
	Changed the rdapConformance tags "sorting_level_0" and "paging_
	level_0" to "sorting" and "paging" respectively.</t>
	<t hangText="11:">Added the "JSONPath operators" sectio
	n to appendix.</t>
	<t hangText="12:">Changed the content of "JSONPath operators
	" section.</t>
	<t hangText="13:">Minor pre-AD review edits.</t>
	<t hangText="14:">Additionl minor pre-AD review edits.</t>
	<t hangText="15:">In section ""sort" Parameter" adde
	d a paragraph providing conversions of IP addresses into their numerical represe
	ntations. In section "Sorting Properties Declaration" rearranged Tabl
	e 2 in a list to make the content more readable. Other minor edits due to AD re
	view.</t>
	<t hangText="16:">In section "Introduction" replaced "..
	. large result set that could be truncated ..." with "... large result
	set that is often truncated ..." as suggested by Gen-ART reviewer. Added
	<xref target="additional-implementation-notes"/>.</t>
	<t hangText="17:">Edits made:
	<list style="symbols">
	<t>in the "Sorting and Paging Metadata" section:
	<list style="symbols">
	<t>replaced "Members are:" with "The AvailableSort obje
	ct includes the following members:";</t>
	<t>clarified that an RDAP server MUST define only one default sorting
	property for each object class;</t>
	</list>
	</t>
	<t>in the "Negative Answers" section:
	<list style="symbols">
	<t>replaced the phrase "the response MAY include additional info
	rmation regarding the negative answer" with the phrase "the response M
	AY include additional information regarding either the supported sorting propert
	ies or the correct cursor value";</t>
	<t>added a new example;</t>
	</list>
	</t>
	<t>clarified the required members of a Link object in the "Represent
	ing Sorting Links" section;</t>
	<t>corrected the [REST] reference in the "Informative References&qu
	ot; section;</t>
	<t>replaced the phrase "and subsequent denial of service due to abu
	se" with the phrase "and subsequent denial of service" in "S
	ecurity Considerations" section.</t>
	</list>
	</t>

	<t hangText="18:">Edits made:
	<list style="symbols">
	<t>in the "Introduction" section:
	<list style="symbols">
	<t>revised the reasons for using query parameters in
	stead of HTTP headers;</t>
	</list>
	</t>
	<t>in the "Sorting and Paging Metadata" section:
	<list style="symbols">
	<t>replaced the phrase "number of objects retur
	ned in the current page" with the phrase "number of objects that shoul
	d have been returned in the current page" in the definition of the "pa
	geSize" field;</t>
	</list>
	</t>
	<t>in the ""sort" Parameter" section:
	<list style="symbols">
	<t>clarified the sorting logic for values denoting d
	ates and times;</t>
	<t>replaced the IPv6 address "2001:0db8:85a3:00
	00:0000:8a2e:0370:7334" with "2001:0db8:85a3:0:0:8a2e:0370:7334";
	</t>
	</list>
	</t>
	<t>in the "Sorting Properties Declaration" section
	:
	<list style="symbols">
	<t>replaced the sorting properties "ipV4"
	and "ipV6" with "ipv4" and "ipv6";</t>
	<t>replaced the sentence "Therefore, the assump
	tion of having a single IPv4 and/or IPv6 value for a nameserver cannot be consid
	ered too stringent." with the sentence "Therefore, this specification
	makes the assumption that nameservers have a single IPv4 and/or IPv6 value.&quot
	;</t>
	<t>clarified that the sorting properties MUST NOT be
	used with a with a meaning other than the one described this document;</t>
	<t>specified that JSONPath operators used in this se
	ction are those defined in "Appendix A";</t>
	</list>
	</t>
	<t>in the ""cursor" Parameter" section:
	<list style="symbols">
	<t>corrected the Base64 encoding of "offset=100
	,limit=50";</t>
	<t>clarified that RDAP servers are NOT RECOMMENDED t
	o obfuscate a cursor value through a mere Base64 encoding;</t>
	</list>
	</t>
	<t>changed last sentence of second paragraph of the "Se
	curity Considerations" section;</t>
	<t>updated the "Acknowledgements" section;</t>
	<t>in "Appendix A":
	<list style="symbols">
	<t>changed introductory paragraph;</t>
	<t>replaced "opaque URL-safe string" with
	"opaque to client URL-safe string";</t>
	</list>
	</t>
	<t>added JSONPath union operator in Table 2 of "Appendi
	x B"</t>
	<t>changed the explanation of offset and limit operators in
	"Appendix B";</t>
	<t>converted the figures containing only RDAP queries into t
	exts;</t>
	<t>changed the wildcard prefixed patterns into wildcard suff
	ixed in all the RDAP queries;</t>
	<t>cleaned the text.</t>
	</list>
	</t>
	<t hangText="19:">Replaced the words "encryption/encrypt"
	with "obfuscation/obfuscate" in the ""cursor" Parameter
	" section.</t>
	<t hangText="20:">Added a final paragraph to <xref target="jsonpath-
	operators"/> to reference the comparison between JSONPath operators and IETF JSO
	NPath WG web site.</t>
	</list>
	</t>
	</section>	</section>


	</back>	</back>
	</rfc>	</rfc>

End of changes. 153 change blocks.
	1113 lines changed or deleted	1348 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/