idnits 2.17.1 draft-ietf-regext-rdap-sorting-and-paging-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 10 characters in excess of 72. == There are 1 instance of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 18, 2020) is 1309 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 593 -- Looks like a reference, but probably isn't: '1' on line 594 -- Looks like a reference, but probably isn't: '3' on line 594 -- Looks like a reference, but probably isn't: '6' on line 563 == Unused Reference: 'RFC8605' is defined on line 923, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7482 (Obsoleted by RFC 9082) ** Obsolete normative reference: RFC 7483 (Obsoleted by RFC 9083) ** Downref: Normative reference to an Informational RFC: RFC 8605 Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Registration Protocols Extensions M. Loffredo 3 Internet-Draft M. Martinelli 4 Intended status: Standards Track IIT-CNR/Registro.it 5 Expires: March 22, 2021 S. Hollenbeck 6 Verisign Labs 7 September 18, 2020 9 Registration Data Access Protocol (RDAP) Query Parameters for Result 10 Sorting and Paging 11 draft-ietf-regext-rdap-sorting-and-paging-17 13 Abstract 15 The Registration Data Access Protocol (RDAP) does not include core 16 functionality for clients to provide sorting and paging parameters 17 for control of large result sets. This omission can lead to 18 unpredictable server processing of queries and client processing of 19 responses. This unpredictability can be greatly reduced if clients 20 can provide servers with their preferences for managing large 21 responses. This document describes RDAP query extensions that allow 22 clients to specify their preferences for sorting and paging result 23 sets. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on March 22, 2021. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 61 2. RDAP Query Parameter Specification . . . . . . . . . . . . . 4 62 2.1. Sorting and Paging Metadata . . . . . . . . . . . . . . . 4 63 2.1.1. RDAP Conformance . . . . . . . . . . . . . . . . . . 6 64 2.2. "count" Parameter . . . . . . . . . . . . . . . . . . . . 6 65 2.3. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 7 66 2.3.1. Sorting Properties Declaration . . . . . . . . . . . 8 67 2.3.2. Representing Sorting Links . . . . . . . . . . . . . 14 68 2.4. "cursor" Parameter . . . . . . . . . . . . . . . . . . . 16 69 2.4.1. Representing Paging Links . . . . . . . . . . . . . . 16 70 3. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 17 71 4. Implementation Considerations . . . . . . . . . . . . . . . . 18 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 73 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 19 74 6.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 19 75 6.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 78 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 79 8.2. Informative References . . . . . . . . . . . . . . . . . 22 80 Appendix A. JSONPath operators . . . . . . . . . . . . . . . . . 23 81 Appendix B. Approaches to Result Pagination . . . . . . . . . . 24 82 B.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 25 83 Appendix C. Additional Implementation Notes . . . . . . . . . . 26 84 C.1. Sorting . . . . . . . . . . . . . . . . . . . . . . . . . 26 85 C.2. Counting . . . . . . . . . . . . . . . . . . . . . . . . 27 86 C.3. Paging . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 88 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 91 1. Introduction 93 The availability of functionality for result sorting and paging 94 provides benefits to both clients and servers in the implementation 95 of RESTful services [REST]. These benefits include: 97 o reducing the server response bandwidth requirements; 98 o improving server response time; 99 o improving query precision and, consequently, obtaining more 100 reliable results; 101 o decreasing server query processing load; 102 o reducing client response processing time. 104 Approaches to implementing features for result sorting and paging can 105 be grouped into two main categories: 107 1. sorting and paging are implemented through the introduction of 108 additional parameters in the query string (e.g. ODATA protocol 109 [OData-Part1]); 111 2. information related to the number of results and the specific 112 portion of the result set to be returned, in addition to a set of 113 ready-made links for the result set scrolling, are inserted in 114 the HTTP header of the request/response. 116 However, there are some drawbacks associated with the use of the HTTP 117 header. First, the header properties cannot be set directly from a 118 web browser. Moreover, in an HTTP session, the information on the 119 status (i.e. the session identifier) is usually inserted in the 120 header or a cookie, while the information on the resource 121 identification or the search type is included in the query string. 122 The second approach is therefore not compliant with the HTTP standard 123 [RFC7230]. As a result, this document describes a specification 124 based on the use of query parameters. 126 Currently, the RDAP protocol [RFC7482] defines two query types: 128 o lookup: the server returns only one object; 129 o search: the server returns a collection of objects. 131 While the lookup query does not raise issues regarding response size 132 management, the search query can potentially generate a large result 133 set that is often truncated according to server limits. Besides, it 134 is not possible to obtain the total number of objects found that 135 might be returned in a search query response [RFC7483]. Lastly, 136 there is no way to specify sort criteria to return the most relevant 137 objects at the beginning of the result set. Therefore, the client 138 might traverse the whole result set to find the relevant objects or, 139 due to truncation, might not find them at all. 141 The specification described in this document extends RDAP query 142 capabilities to enable result sorting and paging, by adding new query 143 parameters that can be applied to RDAP search path segments. The 144 service is implemented using the Hypertext Transfer Protocol (HTTP) 145 [RFC7230] and the conventions described in [RFC7480]. 147 The implementation of the new parameters is technically feasible, as 148 operators for counting, sorting and paging rows are currently 149 supported by the major relational database management systems. 151 1.1. Conventions Used in This Document 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in BCP 156 14 [RFC2119] [RFC8174] when, and only when, they appear in all 157 capitals, as shown here. 159 2. RDAP Query Parameter Specification 161 The new query parameters are OPTIONAL extensions of path segments 162 defined in [RFC7482]. They are as follows: 164 o "count": a boolean value that allows a client to request the 165 return of the total number of objects found; 167 o "sort": a string value that allows a client to request a specific 168 sort order for the result set; 170 o "cursor": a string value representing a pointer to a specific 171 fixed size portion of the result set. 173 Augmented Backus-Naur Form (ABNF) [RFC5234] is used in the following 174 sections to describe the formal syntax of these new parameters. 176 2.1. Sorting and Paging Metadata 178 According to most advanced principles in REST design, collectively 179 known as HATEOAS (Hypermedia as the Engine of Application State) 180 [HATEOAS], a client entering a REST application through an initial 181 URI should use server-provided links to dynamically discover 182 available actions and access the resources it needs. In this way, 183 the client is not required to have prior knowledge of the service 184 and, consequently, to hard code the URIs of different resources. 185 This allows the server to make URI changes as the API evolves without 186 breaking clients. Definitively, a REST service should be as self- 187 descriptive as possible. 189 Therefore, servers implementing the query parameters described in 190 this specification SHOULD provide additional information in their 191 responses about both the available sorting criteria and possible 192 pagination. Such information is collected in two OPTIONAL response 193 elements named "sorting_metadata" and "paging_metadata". 195 The "sorting_metadata" element contains the following properties: 197 o "currentSort": "String" (OPTIONAL) either the value of sort 198 "parameter" as specified in the query string or the sort applied 199 by default, if any; 201 o "availableSorts": "AvailableSort[]" (OPTIONAL) an array of 202 objects, with each element describing an available sort criterion. 203 The AvailableSort object includes the following members: 205 * "property": "String" (REQUIRED) the name that can be used by 206 the client to request the sort criterion; 207 * "default": "Boolean" (REQUIRED) whether the sort criterion is 208 applied by default. An RDAP server MUST define only one 209 default sorting property for each object class; 210 * "jsonPath": "String" (OPTIONAL) the JSONPath of the RDAP field 211 corresponding to the property; 212 * "links": "Link[]" (OPTIONAL) an array of links as described in 213 [RFC8288] containing the query string that applies the sort 214 criterion. 216 At least one of the "currentSort" and "availableSorts" properties 217 MUST be present. 219 The "paging_metadata" element contains the following fields: 221 o "totalCount": "Numeric" (OPTIONAL) a numeric value representing 222 the total number of objects found. It MUST be provided if and 223 only if the query string contains the "count" parameter; 225 o "pageSize": "Numeric" (OPTIONAL) a numeric value representing the 226 number of objects returned in the current page. It MUST be 227 provided if and only if the total number of objects exceeds the 228 page size. This property is redundant for RDAP clients because 229 the page size can be derived from the length of the search results 230 array but, it can be helpful if the end user interacts with the 231 server through a web browser; 233 o "pageNumber": "Numeric" (OPTIONAL) a numeric value representing 234 the number of the current page in the result set. It MUST be 235 provided if and only if the total number of objects found exceeds 236 the page size; 238 o "links": "Link[]" (OPTIONAL) an array of links as described in 239 [RFC8288] containing the reference to the next page. In this 240 specification, only forward pagination is described because it is 241 all that is necessary to traverse the result set. 243 2.1.1. RDAP Conformance 245 Servers returning the "paging_metadata" element in their response 246 MUST include the string literal "paging" in the rdapConformance 247 array. Servers returning the "sorting_metadata" element MUST include 248 the string literal "sorting". 250 2.2. "count" Parameter 252 Currently, the RDAP protocol does not allow a client to determine the 253 total number of the results in a query response when the result set 254 is truncated. This is inefficient because the user cannot determine 255 if the result set is complete. 257 The "count" parameter provides additional functionality (Figure 1) 258 that allows a client to request information from the server that 259 specifies the total number of objects matching the search pattern. 261 https://example.com/rdap/domains?name=*nr.com&count=true 263 Figure 1: Example of RDAP query reporting the "count" parameter 265 The ABNF syntax is the following: 267 count = "count=" ( trueValue / falseValue ) 268 trueValue = ("true" / "yes" / "1") 269 falseValue = ("false" / "no" / "0") 271 A trueValue means that the server MUST provide the total number of 272 the objects in the "totalCount" field of the "paging_metadata" 273 element (Figure 2). A falseValue means that the server MUST NOT 274 provide this number. 276 { 277 "rdapConformance": [ 278 "rdap_level_0", 279 "paging" 280 ], 281 ... 282 "paging_metadata": { 283 "totalCount": 43 284 }, 285 "domainSearchResults": [ 286 ... 287 ] 288 } 290 Figure 2: Example of RDAP response with "paging_metadata" element 291 containing the "totalCount" field 293 2.3. "sort" Parameter 295 The RDAP protocol does not provide any capability to specify the 296 result set sort criteria. A server could implement a default sorting 297 scheme according to the object class, but this feature is not 298 mandatory and might not meet user requirements. Sorting can be 299 addressed by the client, but this solution is rather inefficient. 300 Sorting features provided by the RDAP server could help avoid 301 truncation of relevant results. 303 The "sort" parameter allows the client to ask the server to sort the 304 results according to the values of one or more properties and 305 according to the sort direction of each property. The ABNF syntax is 306 the following: 308 sort = "sort=" sortItem *( "," sortItem ) 309 sortItem = property-ref [":" ( "a" / "d" ) ] 310 property-ref = ALPHA *( ALPHA / DIGIT / "_" ) 312 "a" means that an ascending sort MUST be applied, "d" means that a 313 descending sort MUST be applied. If the sort direction is absent, an 314 ascending sort MUST be applied (Figure 3). 316 https://example.com/rdap/domains?name=*nr.com&sort=name 318 https://example.com/rdap/domains?name=*nr.com&sort=registrationDate:d 320 https://example.com/rdap/domains?name=*nr.com&sort=lockedDate,name 322 Figure 3: Examples of RDAP query reporting the "sort" parameter 324 Except for sorting IP addresses, servers MUST implement sorting 325 according to the JSON value type of the RDAP field the sorting 326 property refers to. That is, JSON strings MUST be sorted 327 lexicographically and JSON numbers MUST be sorted numerically. If IP 328 addresses are represented as JSON strings, they MUST be sorted based 329 on their numeric conversion. 331 The conversion of an IPv4 address to a number is possible since each 332 dotted format IPv4 address is a representation of a number written in 333 a 256-based manner: 192.168.0.1 means 1*256^0 + 0*256^1 + 168*256^2 + 334 192*256^3 = 3232235521. Similarly, an IPv6 address can be converted 335 into a number by applying the base 65536. Therefore, the numerical 336 representation of the IPv6 address 337 2001:0db8:85a3:0000:0000:8a2e:0370:7334 is 338 42540766452641154071740215577757643572. Builtin functions and 339 libraries for converting IP addresses into numbers are available in 340 most known programming languages and relational database management 341 systems. 343 If the "sort" parameter reports an allowed sorting property, it MUST 344 be provided in the "currentSort" field of the "sorting_metadata" 345 element. 347 2.3.1. Sorting Properties Declaration 349 In the "sort" parameter ABNF syntax, property-ref represents a 350 reference to a property of an RDAP object. Such a reference could be 351 expressed by using a JSONPath. The JSONPath in a JSON document 352 [RFC8259] is equivalent to the XPath [W3C.CR-xpath-31-20161213] in a 353 XML document. For example, the JSONPath to select the value of the 354 ASCII name inside an RDAP domain object is "$.ldhName", where $ 355 identifies the root of the document object model (DOM). Another way 356 to select a value inside a JSON document is the JSON Pointer 357 [RFC6901]. While JSONPath or JSON Pointer are both standard ways to 358 select any value inside JSON data, neither is particularly easy to 359 use (e.g. "$.events[?(@.eventAction='registration')].eventDate" is 360 the JSONPath expression of the registration date in an RDAP domain 361 object). 363 Therefore, this specification defines property-ref in terms of RDAP 364 properties. However, not all the RDAP properties are suitable to be 365 used in sort criteria, such as: 367 o properties providing service information (e.g. links, notices, 368 remarks); 370 o multivalued properties (e.g. status, roles, variants); 371 o properties representing relationships to other objects (e.g. 372 entities). 374 On the contrary, properties expressed as values of other properties 375 (e.g. registration date) could be used in such a context. The list 376 of properties an RDAP server MAY implement are divided into two 377 groups: object common properties and object specific properties. 379 o Object common properties. Object common properties are derived 380 from merging the "eventAction" and the "eventDate" properties. 381 The following values of the "sort" parameter are defined: 383 * registrationDate 384 * reregistrationDate 385 * lastChangedDate 386 * expirationDate 387 * deletionDate 388 * reinstantiationDate 389 * transferDate 390 * lockedDate 391 * unlockedDate 393 o Note that some of the object specific properties are also defined 394 as query paths. The object specific properties include: 396 * Domain: name 397 * Nameserver: name, ipV4, ipV6. 398 * Entity: fn, handle, org, email, voice, country, cc, city. 400 The correspondence between these sorting properties and the RDAP 401 object classes is shown in Table 1: 403 +------------+------------+-----------------+-------+-------+-------+ 404 | Object | Sorting | RDAP property | RFC | RFC | RFC | 405 | class | property | | 7483 | 6350 | 8605 | 406 +------------+------------+-----------------+-------+-------+-------+ 407 | Searchable | Common | eventAction | 4.5 | | | 408 | objects | properties | values suffixed | | | | 409 | | | by "Date" | | | | 410 | | | | | | | 411 | Domain | name | unicodeName/ | 5.3 | | | 412 | | | ldhName | | | | 413 | | | | | | | 414 | Nameserver | name | unicodeName/ | 5.2 | | | 415 | | | ldhName | | | | 416 | | ipV4 | v4 ipAddress | 5.2 | | | 417 | | ipV6 | v6 ipAddress | 5.2 | | | 418 | | | | | | | 419 | Entity | handle | handle | 5.1 | | | 420 | | fn | vcard fn | 5.1 | 6.2.1 | | 421 | | org | vcard org | 5.1 | 6.6.4 | | 422 | | voice | vcard tel with | 5.1 | 6.4.1 | | 423 | | | type="voice" | | | | 424 | | email | vcard email | 5.1 | 6.4.2 | | 425 | | country | country name in | 5.1 | 6.3.1 | | 426 | | | vcard adr | | | | 427 | | cc | country code in | 5.1 | | 3.1 | 428 | | | vcard adr | | | | 429 | | city | locality in | 5.1 | 6.3.1 | | 430 | | | vcard adr | | | | 431 +------------+------------+-----------------+-------+-------+-------+ 433 Table 1: Sorting properties definition 435 Regarding the definitions in Table 1, some further considerations are 436 needed to disambiguate some cases: 438 o Since the response to a search on either domains or nameservers 439 might include both A-labels and U-labels [RFC5890] in general, a 440 consistent sorting policy MUST treat the unicodeName and ldhName 441 as two representations of the same value. By default, the 442 unicodeName value MUST be used while sorting. When the 443 unicodeName is unavailable, the value of the ldhName MUST be used 444 instead; 446 o The jCard "sort-as" parameter MUST be ignored for the sorting 447 capability described in this document; 449 o Even if a nameserver can have multiple IPv4 and IPv6 addresses, 450 the most common configuration includes one address for each IP 451 version. Therefore, the assumption of having a single IPv4 and/or 452 IPv6 value for a nameserver cannot be considered too stringent. 453 When more than one address per IP version is reported, sorting 454 MUST be applied to the first value; 456 o Multiple events with a given action on an object might be 457 returned. If this occurs, sorting MUST be applied to the most 458 recent event; 460 o Except for handle values, all the sorting properties defined for 461 entity objects can be multivalued according to the definition of 462 vCard as given in [RFC6350]. When more than one value is 463 reported, sorting MUST be applied to the preferred value 464 identified by the parameter pref="1". If the pref parameter is 465 missing, sorting MUST be applied to the first value. 467 The "jsonPath" field in the "sorting_metadata" element is used to 468 clarify the RDAP field the sorting property refers to. The mapping 469 between the sorting properties and the JSONPaths of the RDAP fields 470 is shown below: 472 o Searchable objects 474 registrationDate 476 $.domainSearchResults[*].events[?(@.eventAction=="registration" 477 )].eventDate 479 reregistrationDate 481 $.domainSearchResults[*].events[?(@.eventAction=="reregistratio 482 n")].eventDate 484 lastChangedDate 486 $.domainSearchResults[*].events[?(@.eventAction=="last 487 changed")].eventDate 489 expirationDate 491 $.domainSearchResults[*].events[?(@.eventAction=="expiration")] 492 .eventDate 494 deletionDate 496 $.domainSearchResults[*].events[?(@.eventAction=="deletion")].e 497 ventDate 499 reinstantiationDate 501 $.domainSearchResults[*].events[?(@.eventAction=="reinstantiati 502 on")].eventDate 504 transferDate 506 $.domainSearchResults[*].events[?(@.eventAction=="transfer")].e 507 ventDate 509 lockedDate 511 $.domainSearchResults[*].events[?(@.eventAction=="locked")].eve 512 ntDate 514 unlockedDate 516 $.domainSearchResults[*].events[?(@.eventAction=="unlocked")].e 517 ventDate 519 o Domain 521 name 523 $.domainSearchResults[*].unicodeName 525 o Nameserver 527 name 529 $.domainSearchResults[*].unicodeName 531 ipV4 533 $.nameserverSearchResults[*].ipAddresses.v4[0] 535 ipV6 537 $.nameserverSearchResults[*].ipAddresses.v6[0] 539 o Entity 541 handle 543 $.entitySearchResults[*].handle 545 fn 546 $.entitySearchResults[*].vcardArray[1][?(@[0]=="fn")][3] 548 org 550 $.entitySearchResults[*].vcardArray[1][?(@[0]=="org")][3] 552 voice 554 $.entitySearchResults[*].vcardArray[1][?(@[0]=="tel" && 555 @[1].type=="voice")][3] 557 email 559 $.entitySearchResults[*].vcardArray[1][?(@[0]=="email")][3] 561 country 563 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][6] 565 cc 567 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][1].cc 569 city 571 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][3] 573 The JSONPaths are provided according to the Goessner v.0.8.0 574 specification [GOESSNER-JSON-PATH]. Further documentation about 575 JSONPath operators used in this specification is included in 576 Appendix A. 578 Additional notes on the reported JSONPaths: 580 o those related to the event dates are defined only for the "domain" 581 object. To obtain the equivalent JSONPaths for "entity" and 582 "nameserver", the path segment "domainSearchResults" must be 583 replaced with "entitySearchResults" and "nameserverSearchResults" 584 respectively; 586 o those related to vCard elements are specified without taking into 587 account the "pref" parameter. Servers that sort those values 588 identified by the pref parameter SHOULD update a JSONPath by 589 adding an appropriate filter. For example, if the email values 590 identified by pref="1" are considered for sorting, the JSONPath of 591 the "email" sorting property should be: 593 $.entitySearchResults[*].vcardArray[1][?(@[0]=="email" && 594 @[1].pref=="1")][3] 596 2.3.2. Representing Sorting Links 598 An RDAP server MAY use the "links" array of the "sorting_metadata" 599 element to provide ready-made references [RFC8288] to the available 600 sort criteria (Figure 4). Each link represents a reference to an 601 alternate view of the results. 603 The "value", "rel" and "href" JSON values MUST be specified. All 604 other JSON values are OPTIONAL. 606 { 607 "rdapConformance": [ 608 "rdap_level_0", 609 "sorting" 610 ], 611 ... 612 "sorting_metadata": { 613 "currentSort": "name", 614 "availableSorts": [ 615 { 616 "property": "registrationDate", 617 "jsonPath": "$.domainSearchResults[*] 618 .events[?(@.eventAction==\"registration\")].eventDate", 619 "default": false, 620 "links": [ 621 { 622 "value": "https://example.com/rdap/domains?name=*nr.com 623 &sort=name", 624 "rel": "alternate", 625 "href": "https://example.com/rdap/domains?name=*nr.com 626 &sort=registrationDate", 627 "title": "Result Ascending Sort Link", 628 "type": "application/rdap+json" 629 }, 630 { 631 "value": "https://example.com/rdap/domains?name=*nr.com 632 &sort=name", 633 "rel": "alternate", 634 "href": "https://example.com/rdap/domains?name=*nr.com 635 &sort=registrationDate:d", 636 "title": "Result Descending Sort Link", 637 "type": "application/rdap+json" 638 } 639 ] 640 }, 641 ... 642 ] 643 }, 644 "domainSearchResults": [ 645 ... 646 ] 647 } 649 Figure 4: Example of a "sorting_metadata" instance to implement 650 result sorting 652 2.4. "cursor" Parameter 654 The cursor parameter defined in this specification can be used to 655 encode information about any pagination method. For example, in the 656 case of a simple implementation of the cursor parameter to represent 657 offset pagination information, the cursor value 658 "b2Zmc2V0PTEwMCxsaW1pdD01MAo=" is the Base64 encoding of 659 "offset=100,limit=50". Likewise, in a simple implementation to 660 represent keyset pagination information, the cursor value 661 "a2V5PXRoZWxhc3Rkb21haW5vZnRoZXBhZ2UuY29t=" represents the Base64 662 encoding of "key=thelastdomainofthepage.com" whereby the key value 663 identifies the last row of the current page. 665 This solution lets RDAP providers implement a pagination method 666 according to their needs, a user's access level, and the submitted 667 query. Besides, servers can change the method over time without 668 announcing anything to clients. The considerations that have led to 669 this solution are reported in more detail in Appendix B. 671 The ABNF syntax of the cursor parameter is the following: 673 cursor = "cursor=" 1*( ALPHA / DIGIT / "/" / "=" / "-" / "_" ) 675 https://example.com/rdap/domains?name=*nr.com 676 &cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M= 678 Figure 5: An example of an RDAP query reporting the "cursor" 679 parameter 681 2.4.1. Representing Paging Links 683 An RDAP server SHOULD use the "links" array of the "paging_metadata" 684 element to provide a ready-made reference [RFC8288] to the next page 685 of the result set (Figure 6). Examples of additional "rel" values a 686 server MAY implement are "first", "last", and "prev". 688 { 689 "rdapConformance": [ 690 "rdap_level_0", 691 "paging" 692 ], 693 ... 694 "notices": [ 695 { 696 "title": "Search query limits", 697 "type": "result set truncated due to excessive load", 698 "description": [ 699 "search results for domains are limited to 50" 700 ] 701 } 702 ], 703 "paging_metadata": { 704 "totalCount": 73, 705 "pageSize": 50, 706 "pageNumber": 1, 707 "links": [ 708 { 709 "value": "https://example.com/rdap/domains?name=*nr.com", 710 "rel": "next", 711 "href": "https://example.com/rdap/domains?name=*nr.com 712 &cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=", 713 "title": "Result Pagination Link", 714 "type": "application/rdap+json" 715 } 716 ] 717 }, 718 "domainSearchResults": [ 719 ... 720 ] 721 } 723 Figure 6: Example of a "paging_metadata" instance to implement cursor 724 pagination 726 3. Negative Answers 728 The value constraints for the parameters are defined by their ABNF 729 syntax. Therefore, each request that includes an invalid value for a 730 parameter SHOULD produce an HTTP 400 (Bad Request) response code. 731 The same response SHOULD be returned in the following cases: 733 o If in both single and multi sort the client provides an 734 unsupported value for the "sort" parameter, as well as a value 735 related to an object property not included in the response; 737 o If the client submits an invalid value for the "cursor" parameter. 739 Optionally, the response MAY include additional information regarding 740 either the supported sorting properties or the correct cursor values 741 in the HTTP entity body (Figure 7). 743 { 744 "errorCode": 400, 745 "title": "Domain sorting property 'unknownproperty' is not valid", 746 "description": [ 747 "Supported domain sorting properties are: 'aproperty', 'anotherproperty'." 748 ] 750 } 752 Figure 7: Example of RDAP error response due to an invalid domain 753 sorting property included in the request 755 4. Implementation Considerations 757 Implementation of the new parameters is technically feasible, as 758 operators for counting, sorting and paging are currently supported by 759 the major relational database management systems. Similar operators 760 are completely or partially supported by the most well-known NoSQL 761 databases (e.g. MongoDB, CouchDB, HBase, Cassandra, Hadoop). 762 Additional implementation notes are included in Appendix C. 764 5. IANA Considerations 766 IANA is requested to register the following values in the RDAP 767 Extensions Registry: 769 Extension identifier: paging 770 Registry operator: Any 771 Published specification: This document. 772 Contact: IETF 773 Intended usage: This extension describes best practice for result 774 set paging. 776 Extension identifier: sorting 777 Registry operator: Any 778 Published specification: This document. 779 Contact: IETF 780 Intended usage: This extension describes best practice for result 781 set sorting. 783 6. Implementation Status 785 NOTE: Please remove this section and the reference to RFC 7942 prior 786 to publication as an RFC. 788 This section records the status of known implementations of the 789 protocol defined by this specification at the time of posting of this 790 Internet-Draft, and is based on a proposal described in [RFC7942]. 791 The description of implementations in this section is intended to 792 assist the IETF in its decision processes in progressing drafts to 793 RFCs. Please note that the listing of any individual implementation 794 here does not imply endorsement by the IETF. Furthermore, no effort 795 has been spent to verify the information presented here that was 796 supplied by IETF contributors. This is not intended as, and must not 797 be construed to be, a catalog of available implementations or their 798 features. Readers are advised to note that other implementations may 799 exist. 801 According to RFC 7942, "this will allow reviewers and working groups 802 to assign due consideration to documents that have the benefit of 803 running code, which may serve as evidence of valuable experimentation 804 and feedback that have made the implemented protocols more mature. 805 It is up to the individual working groups to use this information as 806 they see fit". 808 6.1. IIT-CNR/Registro.it 810 Responsible Organization: Institute of Informatics and Telematics 811 of the National Research Council (IIT-CNR)/Registro.it 812 Location: https://rdap.pubtest.nic.it/ 813 Description: This implementation includes support for RDAP queries 814 using data from .it public test environment. 815 Level of Maturity: This is an "alpha" test implementation. 816 Coverage: This implementation includes all of the features 817 described in this specification. 818 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 820 6.2. APNIC 822 Responsible Organization: Asia-Pacific Network Information Centre 823 Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/sorting- 824 and-paging 825 Description: A proof-of-concept for RDAP mirroring. 826 Level of Maturity: This is a proof-of-concept implementation. 827 Coverage: This implementation includes all of the features 828 described in the specification except for nameserver sorting and 829 unicodeName sorting. 830 Contact Information: Tom Harrison, tomh@apnic.net 832 7. Security Considerations 834 Security services for the operations specified in this document are 835 described in [RFC7481]. 837 A search query typically requires more server resources (such as 838 memory, CPU cycles, and network bandwidth) when compared to a lookup 839 query. This increases the risk of server resource exhaustion and 840 subsequent denial of service. This risk can be mitigated by either 841 restricting search functionality or limiting the rate of search 842 requests. Servers can also reduce their load by truncating the 843 results in a response. However, this last security policy can result 844 in a higher inefficiency if the RDAP server does not provide any 845 functionality to return the truncated results. 847 The new parameters presented in this document provide RDAP operators 848 with a way to implement a server that reduces inefficiency risks. 849 The "count" parameter gives the client the ability to evaluate the 850 completeness of a response. The "sort" parameter allows the client 851 to obtain the most relevant information at the beginning of the 852 result set. This can reduce the number of unnecessary search 853 requests. Finally, the "cursor" parameter enables the user to scroll 854 the result set by submitting a sequence of sustainable queries within 855 server-acceptable limits. 857 8. References 859 8.1. Normative References 861 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 862 Requirement Levels", BCP 14, RFC 2119, 863 DOI 10.17487/RFC2119, March 1997, 864 . 866 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 867 Specifications: ABNF", STD 68, RFC 5234, 868 DOI 10.17487/RFC5234, January 2008, 869 . 871 [RFC5890] Klensin, J., "Internationalized Domain Names for 872 Applications (IDNA): Definitions and Document Framework", 873 RFC 5890, DOI 10.17487/RFC5890, August 2010, 874 . 876 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 877 DOI 10.17487/RFC6350, August 2011, 878 . 880 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 881 Protocol (HTTP/1.1): Message Syntax and Routing", 882 RFC 7230, DOI 10.17487/RFC7230, June 2014, 883 . 885 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 886 Registration Data Access Protocol (RDAP)", RFC 7480, 887 DOI 10.17487/RFC7480, March 2015, 888 . 890 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 891 Registration Data Access Protocol (RDAP)", RFC 7481, 892 DOI 10.17487/RFC7481, March 2015, 893 . 895 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 896 Protocol (RDAP) Query Format", RFC 7482, 897 DOI 10.17487/RFC7482, March 2015, 898 . 900 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 901 Registration Data Access Protocol (RDAP)", RFC 7483, 902 DOI 10.17487/RFC7483, March 2015, 903 . 905 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 906 Code: The Implementation Status Section", BCP 205, 907 RFC 7942, DOI 10.17487/RFC7942, July 2016, 908 . 910 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 911 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 912 May 2017, . 914 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 915 Interchange Format", STD 90, RFC 8259, 916 DOI 10.17487/RFC8259, December 2017, 917 . 919 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 920 DOI 10.17487/RFC8288, October 2017, 921 . 923 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 924 ICANN Extensions for the Registration Data Access Protocol 925 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 926 . 928 [W3C.CR-xpath-31-20161213] 929 Robie, J., Dyck, M., and J. Spiegel, "XML Path Language 930 (XPath) 3.1", World Wide Web Consortium CR CR-xpath- 931 31-20161213, December 2016, 932 . 934 8.2. Informative References 936 [CURSOR] Nimesh, R., "Paginating Real-Time Data with Keyset 937 Pagination", July 2014, . 940 [CURSOR-API1] 941 facebook.com, "facebook for developers - Using the Graph 942 API", July 2017, . 945 [CURSOR-API2] 946 twitter.com, "Pagination", 2017, 947 . 950 [GOESSNER-JSON-PATH] 951 Goessner, S., "JSONPath - XPath for JSON", 2007, 952 . 954 [HATEOAS] Jedrzejewski, B., "HATEOAS - a simple explanation", 2018, 955 . 958 [OData-Part1] 959 Pizzo, M., Handl, R., and M. Zurmuehl, "OData Version 4.0. 960 Part 1: Protocol Plus Errata 03", June 2016, 961 . 966 [REST] Fielding, R., "Architectural Styles and the Design of 967 Network-based Software Architectures", 2000, 968 . 971 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 972 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 973 DOI 10.17487/RFC6901, April 2013, 974 . 976 [SEEK] EverSQL.com, "Faster Pagination in Mysql - Why Order By 977 With Limit and Offset is Slow?", July 2017, 978 . 981 Appendix A. JSONPath operators 983 A JSONPath expression represents a path to find an element (or a set 984 of elements) in a JSON content. 986 The base JSONPath specification requires that implementations support 987 a set of "basic operators". These operators are used to access the 988 elements of a JSON structure like objects and arrays, and their 989 subelements, respectively, object members and array items. No 990 operations are defined for retrieving parent or sibling elements of a 991 given element. The root element is always referred to as $ 992 regardless of it being an object or array. 994 Additionally, the specification permits implementations to support 995 arbitrary script expressions. These can be used to index into an 996 object or array, or to filter elements from an array. While script 997 expression behavior is implementation-defined, most implementations 998 support the basic relational and logical operators, as well as both 999 object member and array item access, sufficiently similar for the 1000 purpose of this document. Commonly-supported operators/functions 1001 divided into "top-level operators" and "filter operators" are 1002 documented in Table 2 and Table 3 respectively. 1004 +-------------------+-----------------------------------------+ 1005 | Operator | Descritpion | 1006 +-------------------+-----------------------------------------+ 1007 | $ | Root element | 1008 | . | Object member access (dot-notation) | 1009 | [''] | Object member access (bracket-notation) | 1010 | [] | Array item access | 1011 | * | All elements within the specified scope | 1012 | [?()] | Filter expression | 1013 +-------------------+-----------------------------------------+ 1015 Table 2: JSONPath Top-Level Operators 1017 +------------+----------------------------------------+ 1018 | Operator | Descritpion | 1019 +------------+----------------------------------------+ 1020 | @ | Current element being processed | 1021 | . | Object member access | 1022 | [] | Array item access | 1023 | == | Left is equal to right | 1024 | != | Left is not equal to right | 1025 | < | Left is less than right | 1026 | <= | Left is less than or equal to right | 1027 | > | Left is greater than right | 1028 | >= | Left is greater than or equal to right | 1029 | && | Logical conjunction | 1030 | || | Logical disjunction | 1031 +------------+----------------------------------------+ 1033 Table 3: JSONPath Filter Operators 1035 Appendix B. Approaches to Result Pagination 1037 An RDAP query could return a response with hundreds, even thousands, 1038 of objects, especially when partial matching is used. For this 1039 reason, the cursor parameter addressing result pagination is defined 1040 to make responses easier to handle. 1042 Presently, the most popular methods to implement pagination in a REST 1043 API include offset pagination and keyset pagination. Neither 1044 pagination method requires the server to handle the result set in a 1045 storage area across multiple requests since a new result set is 1046 generated each time a request is submitted. Therefore, they are 1047 preferred to any other method requiring the management of a REST 1048 session. 1050 Using limit and offset operators represents the traditionally used 1051 method to implement result pagination. Both of them can be used 1052 individually: 1054 o "limit": means that the server MUST return the first N objects of 1055 the result set; 1057 o "offset": means that the server MUST skip the first N objects and 1058 MUST return objects starting from position N+1. 1060 When limit and offset are used together, they provide the ability to 1061 identify a specific portion of the result set. For example, the pair 1062 "offset=100,limit=50" returns the first 50 objects starting from 1063 position 101 of the result set. 1065 Though easy to implement, offset pagination also includes drawbacks: 1067 o When offset has a very high value, scrolling the result set could 1068 take some time; 1070 o It always requires fetching all rows before dropping as many rows 1071 as specified by offset; 1073 o It may return inconsistent pages when data are frequently updated 1074 (i.e. real-time data). 1076 Keyset pagination [SEEK] adds a query condition that enables the 1077 selection of the only data not yet returned. This method has been 1078 taken as the basis for the implementation of a "cursor" parameter 1079 [CURSOR] by some REST API providers [CURSOR-API1] [CURSOR-API2]. The 1080 cursor is an opaque URL-safe string representing a logical pointer to 1081 the first result of the next page (Figure 5). 1083 Nevertheless, even keyset pagination can be troublesome: 1085 o It needs at least one key field; 1087 o It does not allow sorting simply by any field because the sorting 1088 criterion must contain a key; 1090 o It works best with full composite values support by data base 1091 management systems (i.e. [x,y]>[a,b]), emulation is possible but 1092 inelegant and less efficient; 1094 o It does not allow direct navigation to arbitrary pages because the 1095 result set must be scrolled in sequential order starting from the 1096 initial page; 1098 o Implementing bi-directional navigation is tedious because all 1099 comparison and sort operations have to be reversed. 1101 B.1. Specific Issues Raised by RDAP 1103 Furthermore, in the RDAP context, some additional considerations can 1104 be made: 1106 o An RDAP object is a conceptual aggregation of information 1107 generally collected from more than one data structure (e.g. table) 1108 and this makes it even harder to implement keyset pagination, a 1109 task that is already quite difficult. For example, the entity 1110 object can include information from different data structures 1111 (registrars, registrants, contacts, resellers), each one with its 1112 key field mapping the RDAP entity handle; 1114 o Depending on the number of page results as well as the number and 1115 the complexity of the properties of each RDAP object in the 1116 response, the time required by offset pagination to skip the 1117 previous pages could be much faster than the processing time 1118 needed to build the current page. In fact, RDAP objects are 1119 usually formed by information belonging to multiple data 1120 structures and containing multivalued properties (i.e. arrays) 1121 and, therefore, data selection might therefore be a time consuming 1122 process. This situation occurs even though the selection is 1123 supported by indexes; 1125 o Depending on the access levels defined by each RDAP operator, the 1126 increase in complexity and the decrease in flexibility of keyset 1127 pagination in comparison to offset pagination could be considered 1128 impractical. 1130 Ultimately, both pagination methods have benefits and drawbacks. 1132 Appendix C. Additional Implementation Notes 1134 This section contains an overview of the main choices made during the 1135 implementation of the capabilities defined above in the RDAP public 1136 test server of Registro.it at the Institute of Informatics and 1137 Telematics of the National Research Counci (IIT-CNR). The content of 1138 this section can represent a guidance for those implementers who plan 1139 to provide RDAP users with those capabilities. The RDAP public test 1140 server can be accessed at https://rdap.pubtest.nic.it/. Further 1141 documentation about the server features is available at 1142 https://rdap.pubtest.nic.it/doc/README.html. 1144 C.1. Sorting 1146 If no sort criterion is specified in the query string, the results 1147 are sorted by a default property: "name" for domains and nameservers, 1148 "handle" for entities. The server supports multiple property sorting 1149 but the "sorting_metadata" object includes only the links to 1150 alternative result set views sorted by a single property just to show 1151 the list of sorting properties allowed for each searchable object. 1152 The server supports all the object specific sorting properties 1153 described in the specification except for nameserver sorting based on 1154 unicodeName, that is, the "name" sorting property is mapped onto the 1155 "ldhName" response field. Regarding the object common properties, 1156 the sorting by registrationDate, expirationDate, lastChangedDate and 1157 transferDate is supported. 1159 C.2. Counting 1161 The counting operation is implemented through a separate query. Some 1162 relational database management systems support custom operators to 1163 get the total count together with the rows, but the resulting query 1164 can be considerably more expensive than that performed without the 1165 total count. Therefore, as "totalCount" is an optional response 1166 information, fetching always the total number of rows has been 1167 considered an inefficient solution. Furthermore, to avoid the 1168 processing of unnecessary queries, when the "count" parameter is 1169 included in the submitted query, it is not also repeated in the query 1170 strings of the "links" array provided in both "paging_metadata" and 1171 "sorting_metadata" objects. 1173 C.3. Paging 1175 The server implements the cursor pagination through the keyset 1176 pagination when sorting by a unique property is requested or the 1177 default sort is applied, through offset pagination otherwise. As 1178 most of the relational database management systems don't support the 1179 comparison of full composite values natively, the implementation of 1180 full keyset pagination seem to be troublesome so, at least initially, 1181 a selective applicability of keyset pagination is advisable. 1182 Moreover, the "cursor" value encodes not only information about 1183 pagination but also about the search pattern and the other query 1184 parameters in order to check the consistency of the entire query 1185 string. If the "cursor" value is inconsistent with the rest of the 1186 query string, the server returns an error response. 1188 Acknowledgements 1190 The authors would like to acknowledge Brian Mountford, Tom Harrison, 1191 Karl Heinz Wolf and Jasdip Singh for their contribution to the 1192 development of this document. 1194 Change Log 1196 00: Initial working group version ported from draft-loffredo-regext- 1197 rdap-sorting-and-paging-05 1198 01: Removed both "offset" and "nextOffset" to keep "paging_metadata" 1199 consistent between the pagination methods. Renamed 1200 "Considerations about Paging Implementation" section in ""cursor" 1201 Parameter". Removed "FOR DISCUSSION" items. Provided a more 1202 detailed description of both "sorting_metadata" and 1203 "paging_metadata" objects. 1204 02: Removed both "offset" and "limit" parameters. Added ABNF syntax 1205 of the cursor parameter. Rearranged the layout of some sections. 1207 Removed some items from "Informative References" section. Changed 1208 "IANA Considerations" section. 1209 03: Added "cc" to the list of sorting properties in "Sorting 1210 Properties Declaration" section. Added RFC8605 to the list of 1211 "Informative References". 1212 04: Replaced "ldhName" with "name" in the "Sorting Properties 1213 Declaration" section. Clarified the sorting logic for the JSON 1214 value types and the sorting policy for multivalued fields. 1215 05: Clarified the logic of sorting on IP addresses. Clarified the 1216 mapping between the sorting properties and the RDAP fields. 1217 Updated "Acknowledgements" section. 1218 06: Renamed "pageCount" to "pageSize" and added "pageNumber" in the 1219 "paging_metadata" object. 1220 07: Added "Paging Responses to POST Requests" section. 1221 08: Added "Approaches to Result Pagination" section to appendix. 1222 Added the case of requesting a sort on a property not included in 1223 the response to the errors listed in the "Negative Answers" 1224 section. 1225 09: Updated the "Implementation Status" section to include APNIC 1226 implementation. Moved the "RDAP Conformance" section up in the 1227 document. Removed the "Paging Responses to POST Requests" 1228 section. Updated the "Acknowledgements" section. Removed unused 1229 references. In the "Sorting Properties Declaration" section: 1231 * clarified the logic of sorting on events; 1232 * corrected the JSONPath of the "lastChanged" sorting property; 1233 * provided a JSONPath example taking into account the vCard 1234 "pref" parameter. 1235 10: Corrected the JSONPaths of both "fn" and "org" sorting 1236 properties in Table 2. Corrected JSON content in Figure 4. Moved 1237 [W3C.CR-xpath-31-20161213] and [RFC7942] to the "Normative 1238 References". Changed the rdapConformance tags "sorting_level_0" 1239 and "paging_level_0" to "sorting" and "paging" respectively. 1240 11: Added the "JSONPath operators" section to appendix. 1241 12: Changed the content of "JSONPath operators" section. 1242 13: Minor pre-AD review edits. 1243 14: Additionl minor pre-AD review edits. 1244 15: In section ""sort" Parameter" added a paragraph providing 1245 conversions of IP addresses into their numerical representations. 1246 In section "Sorting Properties Declaration" rearranged Table 2 in 1247 a list to make the content more readable. Other minor edits due 1248 to AD review. 1249 16: In section "Introduction" replaced "... large result set that 1250 could be truncated ..." with "... large result set that is often 1251 truncated ..." as suggested by Gen-ART reviewer. Added 1252 Appendix C. 1253 17: Edits made: 1255 * in the "Sorting and Paging Metadata" section: 1257 + replaced "Members are:" with "The AvailableSort object 1258 includes the following members:"; 1259 + clarified that an RDAP server MUST define only one default 1260 sorting property for each object class; 1261 * in the "Negative Answers" section: 1263 + replaced the phrase "the response MAY include additional 1264 information regarding the negative answer" with the phrase 1265 "the response MAY include additional information regarding 1266 either the supported sorting properties or the correct 1267 cursor value"; 1268 + added a new example; 1269 * clarified the required members of a Link object in the 1270 "Representing Sorting Links" section; 1271 * corrected the [REST] reference in the "Informative References" 1272 section; 1273 * replaced the phrase "and subsequent denial of service due to 1274 abuse" with the phrase "and subsequent denial of service" in 1275 "Security Considerations" section. 1277 Authors' Addresses 1279 Mario Loffredo 1280 IIT-CNR/Registro.it 1281 Via Moruzzi,1 1282 Pisa 56124 1283 IT 1285 Email: mario.loffredo@iit.cnr.it 1286 URI: http://www.iit.cnr.it 1288 Maurizio Martinelli 1289 IIT-CNR/Registro.it 1290 Via Moruzzi,1 1291 Pisa 56124 1292 IT 1294 Email: maurizio.martinelli@iit.cnr.it 1295 URI: http://www.iit.cnr.it 1296 Scott Hollenbeck 1297 Verisign Labs 1298 12061 Bluemont Way 1299 Reston, VA 20190 1300 USA 1302 Email: shollenbeck@verisign.com 1303 URI: https://www.verisignlabs.com/