idnits 2.17.1 draft-ietf-regext-rdap-sorting-and-paging-20.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 (November 30, 2020) is 1215 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 607 -- Looks like a reference, but probably isn't: '1' on line 608 -- Looks like a reference, but probably isn't: '3' on line 608 -- Looks like a reference, but probably isn't: '6' on line 583 == Unused Reference: 'RFC8605' is defined on line 951, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** 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: 6 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: June 3, 2021 S. Hollenbeck 6 Verisign Labs 7 November 30, 2020 9 Registration Data Access Protocol (RDAP) Query Parameters for Result 10 Sorting and Paging 11 draft-ietf-regext-rdap-sorting-and-paging-20 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 June 3, 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 . . . . . . . . . . . . . 26 83 Appendix C. Additional Implementation Notes . . . . . . . . . . 26 84 C.1. Sorting . . . . . . . . . . . . . . . . . . . . . . . . . 27 85 C.2. Counting . . . . . . . . . . . . . . . . . . . . . . . . 27 86 C.3. Paging . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 28 88 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 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 relevant 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 [RFC7231]. 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 Finally, providing custom information through HTTP headers assumes 123 the client to have a prior knowledge of the server implementation 124 which is widely considered a REST design anti-pattern. As a result, 125 this document describes a specification based on the use of query 126 parameters. 128 Currently, the RDAP protocol [RFC7482] defines two query types: 130 o lookup: the server returns only one object; 131 o search: the server returns a collection of objects. 133 While the lookup query does not raise issues regarding response size 134 management, the search query can potentially generate a large result 135 set that is often truncated according to server limits. Besides, it 136 is not possible to obtain the total number of objects found that 137 might be returned in a search query response [RFC7483]. Lastly, 138 there is no way to specify sort criteria to return the most relevant 139 objects at the beginning of the result set. Therefore, the client 140 might traverse the whole result set to find the relevant objects or, 141 due to truncation, might not find them at all. 143 The specification described in this document extends RDAP query 144 capabilities to enable result sorting and paging, by adding new query 145 parameters that can be applied to RDAP search path segments. The 146 service is implemented using the Hypertext Transfer Protocol (HTTP) 147 [RFC7230] and the conventions described in [RFC7480]. 149 The implementation of the new parameters is technically feasible, as 150 operators for counting, sorting and paging rows are currently 151 supported by the major relational database management systems. 153 1.1. Conventions Used in This Document 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 157 "OPTIONAL" in this document are to be interpreted as described in BCP 158 14 [RFC2119] [RFC8174] when, and only when, they appear in all 159 capitals, as shown here. 161 2. RDAP Query Parameter Specification 163 The new query parameters are OPTIONAL extensions of path segments 164 defined in [RFC7482]. They are as follows: 166 o "count": a boolean value that allows a client to request the 167 return of the total number of objects found; 169 o "sort": a string value that allows a client to request a specific 170 sort order for the result set; 172 o "cursor": a string value representing a pointer to a specific 173 fixed size portion of the result set. 175 Augmented Backus-Naur Form (ABNF) [RFC5234] is used in the following 176 sections to describe the formal syntax of these new parameters. 178 2.1. Sorting and Paging Metadata 180 According to most advanced principles in REST design, collectively 181 known as HATEOAS (Hypermedia as the Engine of Application State) 182 [HATEOAS], a client entering a REST application through an initial 183 URI should use server-provided links to dynamically discover 184 available actions and access the resources it needs. In this way, 185 the client is not required to have prior knowledge of the service 186 and, consequently, to hard code the URIs of different resources. 187 This allows the server to make URI changes as the API evolves without 188 breaking clients. Definitively, a REST service should be as self- 189 descriptive as possible. 191 Therefore, servers implementing the query parameters described in 192 this specification SHOULD provide additional information in their 193 responses about both the available sorting criteria and possible 194 pagination. Such information is collected in two OPTIONAL response 195 elements named "sorting_metadata" and "paging_metadata". 197 The "sorting_metadata" element contains the following properties: 199 o "currentSort": "String" (OPTIONAL) either the value of "sort" 200 parameter as specified in the query string or the sort applied by 201 default, if any; 203 o "availableSorts": "AvailableSort[]" (OPTIONAL) an array of 204 objects, with each element describing an available sort criterion. 205 The AvailableSort object includes the following members: 207 * "property": "String" (REQUIRED) the name that can be used by 208 the client to request the sort criterion; 209 * "default": "Boolean" (REQUIRED) whether the sort criterion is 210 applied by default. An RDAP server MUST define only one 211 default sorting property for each object class; 212 * "jsonPath": "String" (OPTIONAL) the JSONPath expression of the 213 RDAP field corresponding to the property; 214 * "links": "Link[]" (OPTIONAL) an array of links as described in 215 [RFC8288] containing the query string that applies the sort 216 criterion. 218 At least one of the "currentSort" and "availableSorts" properties 219 MUST be present. 221 The "paging_metadata" element contains the following fields: 223 o "totalCount": "Numeric" (OPTIONAL) a numeric value representing 224 the total number of objects found. It MUST be provided if and 225 only if the query string contains the "count" parameter; 227 o "pageSize": "Numeric" (OPTIONAL) a numeric value representing the 228 number of objects that should have been returned in the current 229 page. It MUST be provided if and only if the total number of 230 objects exceeds the page size. This property is redundant for 231 RDAP clients because the page size can be derived from the length 232 of the search results array but, it can be helpful if the end user 233 interacts with the server through a web browser; 235 o "pageNumber": "Numeric" (OPTIONAL) a numeric value representing 236 the number of the current page in the result set. It MUST be 237 provided if and only if the total number of objects found exceeds 238 the page size; 240 o "links": "Link[]" (OPTIONAL) an array of links as described in 241 [RFC8288] containing the reference to the next page. In this 242 specification, only forward pagination is described because it is 243 all that is necessary to traverse the result set. 245 2.1.1. RDAP Conformance 247 Servers returning the "paging_metadata" element in their response 248 MUST include the string literal "paging" in the rdapConformance 249 array. Servers returning the "sorting_metadata" element MUST include 250 the string literal "sorting". 252 2.2. "count" Parameter 254 Currently, the RDAP protocol does not allow a client to determine the 255 total number of the results in a query response when the result set 256 is truncated. This is inefficient because the user cannot determine 257 if the result set is complete. 259 The "count" parameter provides additional functionality that allows a 260 client to request information from the server that specifies the 261 total number of objects matching the search pattern. 263 The following is an example of an RDAP query including the "count" 264 parameter: 266 https://example.com/rdap/domains?name=example*.com&count=true 268 The ABNF syntax is the following: 270 count = "count=" ( trueValue / falseValue ) 271 trueValue = ("true" / "yes" / "1") 272 falseValue = ("false" / "no" / "0") 274 A trueValue means that the server MUST provide the total number of 275 the objects in the "totalCount" field of the "paging_metadata" 276 element (Figure 1). A falseValue means that the server MUST NOT 277 provide this number. 279 { 280 "rdapConformance": [ 281 "rdap_level_0", 282 "paging" 283 ], 284 ... 285 "paging_metadata": { 286 "totalCount": 43 287 }, 288 "domainSearchResults": [ 289 ... 290 ] 291 } 293 Figure 1: Example of RDAP response with "paging_metadata" element 294 containing the "totalCount" field 296 2.3. "sort" Parameter 298 The RDAP protocol does not provide any capability to specify the 299 result set sort criteria. A server could implement a default sorting 300 scheme according to the object class, but this feature is not 301 mandatory and might not meet user requirements. Sorting can be 302 addressed by the client, but this solution is rather inefficient. 303 Sorting features provided by the RDAP server could help avoid 304 truncation of relevant results. 306 The "sort" parameter allows the client to ask the server to sort the 307 results according to the values of one or more properties and 308 according to the sort direction of each property. The ABNF syntax is 309 the following: 311 sort = "sort=" sortItem *( "," sortItem ) 312 sortItem = property-ref [":" ( "a" / "d" ) ] 313 property-ref = ALPHA *( ALPHA / DIGIT / "_" ) 315 "a" means that an ascending sort MUST be applied, "d" means that a 316 descending sort MUST be applied. If the sort direction is absent, an 317 ascending sort MUST be applied. 319 The following are examples of RDAP queries including the "sort" 320 parameter: 322 https://example.com/rdap/domains?name=example*.com&sort=name 324 https://example.com/rdap/ 325 domains?name=example*.com&sort=registrationDate:d 326 https://example.com/rdap/ 327 domains?name=example*.com&sort=lockedDate,name 329 Except for sorting IP addresses and values denoting dates and times, 330 servers MUST implement sorting according to the JSON value type of 331 the RDAP field the sorting property refers to. That is, JSON strings 332 MUST be sorted lexicographically and JSON numbers MUST be sorted 333 numerically. Values denoting dates and times MUST be sorted in 334 chronological order. If IP addresses are represented as JSON 335 strings, they MUST be sorted based on their numeric conversion. 337 The conversion of an IPv4 address to a number is possible since each 338 dotted format IPv4 address is a representation of a number written in 339 a 256-based manner: 192.168.0.1 means 1*256^0 + 0*256^1 + 168*256^2 + 340 192*256^3 = 3232235521. Similarly, an IPv6 address can be converted 341 into a number by applying the base 65536. Therefore, the numerical 342 representation of the IPv6 address 2001:0db8:85a3:0:0:8a2e:0370:7334 343 is 42540766452641154071740215577757643572. Builtin functions and 344 libraries for converting IP addresses into numbers are available in 345 most known programming languages and relational database management 346 systems. 348 If the "sort" parameter presents an allowed sorting property, it MUST 349 be provided in the "currentSort" field of the "sorting_metadata" 350 element. 352 2.3.1. Sorting Properties Declaration 354 In the "sort" parameter ABNF syntax, the element named "property-ref" 355 represents a reference to a property of an RDAP object. Such a 356 reference could be expressed by using a JSONPath expression (named 357 "jsonpath" in the following). 359 JSONPath is a syntax, originally based on the XML XPath notation 360 [W3C.CR-xpath-31-20161213], which represents a path to select an 361 element (or a set of elements) in a JSON document [RFC8259]. For 362 example, the jsonpath to select the value of the ASCII name inside an 363 RDAP domain lookup response is "$.ldhName", where $ identifies the 364 root of the document object model (DOM). Another way to select a 365 value inside a JSON document is the JSON Pointer [RFC6901]. 367 While JSONPath or JSON Pointer are both commonly adopted notations to 368 select any value inside JSON data, neither is particularly coincise 369 and easy to use (e.g. "$.domainSearchResults[*].events[?(@.eventActio 370 n='registration')].eventDate" is the jsonpath of the registration 371 date in an RDAP domain search response). 373 Therefore, this specification defines the "property-ref" element in 374 terms of names identifying RDAP properties. However, not all the 375 RDAP properties are suitable to be used in sort criteria, such as: 377 o properties providing service information (e.g. links, notices, 378 remarks); 380 o multivalued properties (e.g. status, roles, variants); 382 o properties representing relationships to other objects (e.g. 383 entities). 385 On the contrary, properties expressed as values of other properties 386 (e.g. registration date) could be used in such a context. 388 A list of properties an RDAP server MAY implement is defined. The 389 properties are divided into two groups: object common properties and 390 object specific properties. 392 o Object common properties. Object common properties are derived 393 from merging the "eventAction" and the "eventDate" properties. 394 The following values of the "sort" parameter are defined: 396 * registrationDate 397 * reregistrationDate 398 * lastChangedDate 399 * expirationDate 400 * deletionDate 401 * reinstantiationDate 402 * transferDate 403 * lockedDate 404 * unlockedDate 406 o Object specific properties. Note that some of these properties 407 are also defined as query path segments. These properties 408 include: 410 * Domain: name 411 * Nameserver: name, ipv4, ipv6. 412 * Entity: fn, handle, org, email, voice, country, cc, city. 414 The correspondence between these sorting properties and the RDAP 415 object classes is shown in Table 1. Some of the sorting properties 416 defined for the RDAP entity class are related to jCard elements 417 [RFC7095] but, being jCard the JSON format for vCard [RFC6350], the 418 corresponding definitions are included in vCard specification. 420 An RDAP server MUST NOT use the defined sorting properties with a 421 meaning other than the one described in Table 1. 423 +------------+------------+-----------------+-------+-------+-------+ 424 | Object | Sorting | RDAP property | RFC | RFC | RFC | 425 | class | property | | 7483 | 6350 | 8605 | 426 +------------+------------+-----------------+-------+-------+-------+ 427 | Searchable | Common | eventAction | 4.5 | | | 428 | objects | properties | values suffixed | | | | 429 | | | by "Date" | | | | 430 | | | | | | | 431 | Domain | name | unicodeName/ | 5.3 | | | 432 | | | ldhName | | | | 433 | | | | | | | 434 | Nameserver | name | unicodeName/ | 5.2 | | | 435 | | | ldhName | | | | 436 | | ipv4 | v4 ipAddress | 5.2 | | | 437 | | ipv6 | v6 ipAddress | 5.2 | | | 438 | | | | | | | 439 | Entity | handle | handle | 5.1 | | | 440 | | fn | jCard fn | 5.1 | 6.2.1 | | 441 | | org | jCard org | 5.1 | 6.6.4 | | 442 | | voice | jCard tel with | 5.1 | 6.4.1 | | 443 | | | type="voice" | | | | 444 | | email | jCard email | 5.1 | 6.4.2 | | 445 | | country | country name in | 5.1 | 6.3.1 | | 446 | | | jCard adr | | | | 447 | | cc | country code in | 5.1 | | 3.1 | 448 | | | jCard adr | | | | 449 | | city | locality in | 5.1 | 6.3.1 | | 450 | | | jCard adr | | | | 451 +------------+------------+-----------------+-------+-------+-------+ 453 Table 1: Sorting properties definition 455 Regarding the definitions in Table 1, some further considerations are 456 needed to disambiguate some cases: 458 o since the response to a search on either domains or nameservers 459 might include both A-labels and U-labels [RFC5890] in general, a 460 consistent sorting policy MUST treat the unicodeName and ldhName 461 as two representations of the same value. The unicodeName value 462 MUST be used while sorting if it is present; when the unicodeName 463 is unavailable, the value of the ldhName MUST be used instead; 465 o the jCard "sort-as" parameter MUST be ignored for the sorting 466 capability described in this document; 468 o even if a nameserver can have multiple IPv4 and IPv6 addresses, 469 the most common configuration includes one address for each IP 470 version. Therefore, this specification makes the assumption that 471 nameservers have a single IPv4 and/or IPv6 value. When more than 472 one address per IP version is presented, sorting MUST be applied 473 to the first value; 475 o multiple events with a given action on an object might be 476 returned. If this occurs, sorting MUST be applied to the most 477 recent event; 479 o except for handle values, all the sorting properties defined for 480 entity objects can be multivalued according to the definition of 481 vCard as given in [RFC6350]. When more than one value is 482 presented, sorting MUST be applied to the preferred value 483 identified by the parameter pref="1". If the pref parameter is 484 missing, sorting MUST be applied to the first value. 486 The "jsonPath" field in the "sorting_metadata" element is used to 487 clarify the RDAP response field the sorting property refers to. The 488 mapping between the sorting properties and the jsonpaths of the RDAP 489 response fields is shown below. The JSONPath operators used herein 490 are described in Appendix A. 492 o Searchable objects 494 registrationDate 496 $.domainSearchResults[*].events[?(@.eventAction=="registration" 497 )].eventDate 499 reregistrationDate 501 $.domainSearchResults[*].events[?(@.eventAction=="reregistratio 502 n")].eventDate 504 lastChangedDate 506 $.domainSearchResults[*].events[?(@.eventAction=="last 507 changed")].eventDate 509 expirationDate 511 $.domainSearchResults[*].events[?(@.eventAction=="expiration")] 512 .eventDate 514 deletionDate 515 $.domainSearchResults[*].events[?(@.eventAction=="deletion")].e 516 ventDate 518 reinstantiationDate 520 $.domainSearchResults[*].events[?(@.eventAction=="reinstantiati 521 on")].eventDate 523 transferDate 525 $.domainSearchResults[*].events[?(@.eventAction=="transfer")].e 526 ventDate 528 lockedDate 530 $.domainSearchResults[*].events[?(@.eventAction=="locked")].eve 531 ntDate 533 unlockedDate 535 $.domainSearchResults[*].events[?(@.eventAction=="unlocked")].e 536 ventDate 538 o Domain 540 name 542 $.domainSearchResults[*].[unicodeName,ldhName] 544 o Nameserver 546 name 548 $.nameserverSearchResults[*].[unicodeName,ldhName] 550 ipv4 552 $.nameserverSearchResults[*].ipAddresses.v4[0] 554 ipv6 556 $.nameserverSearchResults[*].ipAddresses.v6[0] 558 o Entity 560 handle 562 $.entitySearchResults[*].handle 564 fn 566 $.entitySearchResults[*].vcardArray[1][?(@[0]=="fn")][3] 568 org 570 $.entitySearchResults[*].vcardArray[1][?(@[0]=="org")][3] 572 voice 574 $.entitySearchResults[*].vcardArray[1][?(@[0]=="tel" && 575 @[1].type=="voice")][3] 577 email 579 $.entitySearchResults[*].vcardArray[1][?(@[0]=="email")][3] 581 country 583 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][6] 585 cc 587 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][1].cc 589 city 591 $.entitySearchResults[*].vcardArray[1][?(@[0]=="adr")][3][3] 593 Additional notes on the provided jsonpaths: 595 o those related to the event dates are defined only for the "domain" 596 object. To obtain the equivalent jsonpaths for "entity" and 597 "nameserver", the path segment "domainSearchResults" must be 598 replaced with "entitySearchResults" and "nameserverSearchResults" 599 respectively; 601 o those related to jCard elements are specified without taking into 602 account the "pref" parameter. Servers that sort those values 603 identified by the pref parameter SHOULD update a jsonpath by 604 adding an appropriate filter. For example, if the email values 605 identified by pref="1" are considered for sorting, the jsonpath of 606 the "email" sorting property should be: 607 $.entitySearchResults[*].vcardArray[1][?(@[0]=="email" && 608 @[1].pref=="1")][3] 610 2.3.2. Representing Sorting Links 612 An RDAP server MAY use the "links" array of the "sorting_metadata" 613 element to provide ready-made references [RFC8288] to the available 614 sort criteria (Figure 2). Each link represents a reference to an 615 alternate view of the results. 617 The "value", "rel" and "href" JSON values MUST be specified. All 618 other JSON values are OPTIONAL. 620 { 621 "rdapConformance": [ 622 "rdap_level_0", 623 "sorting" 624 ], 625 ... 626 "sorting_metadata": { 627 "currentSort": "name", 628 "availableSorts": [ 629 { 630 "property": "registrationDate", 631 "jsonPath": "$.domainSearchResults[*] 632 .events[?(@.eventAction==\"registration\")].eventDate", 633 "default": false, 634 "links": [ 635 { 636 "value": "https://example.com/rdap/domains?name=example*.com 637 &sort=name", 638 "rel": "alternate", 639 "href": "https://example.com/rdap/domains?name=example*.com 640 &sort=registrationDate", 641 "title": "Result Ascending Sort Link", 642 "type": "application/rdap+json" 643 }, 644 { 645 "value": "https://example.com/rdap/domains?name=example*.com 646 &sort=name", 647 "rel": "alternate", 648 "href": "https://example.com/rdap/domains?name=example*.com 649 &sort=registrationDate:d", 650 "title": "Result Descending Sort Link", 651 "type": "application/rdap+json" 652 } 653 ] 654 }, 655 ... 656 ] 657 }, 658 "domainSearchResults": [ 659 ... 660 ] 661 } 663 Figure 2: Example of a "sorting_metadata" instance to implement 664 result sorting 666 2.4. "cursor" Parameter 668 The cursor parameter defined in this specification can be used to 669 encode information about any pagination method. For example, in the 670 case of a simple implementation of the cursor parameter to represent 671 offset pagination information, the cursor value 672 "b2Zmc2V0PTEwMCxsaW1pdD01MA==" is the Base64 encoding of 673 "offset=100,limit=50". Likewise, in a simple implementation to 674 represent keyset pagination information, the cursor value 675 "ZXhhbXBsZS1OLmNvbQ==" represents the Base64 encoding of 676 "key=example-N.com" whereby the key value identifies the last row of 677 the current page. 679 Note that this specification uses a Base64 encoding for cursor 680 obfuscation just for example. RDAP servers are NOT RECOMMENDED to 681 obfuscate a cursor value through a mere Base64 encoding. 683 This solution lets RDAP providers implement a pagination method 684 according to their needs, a user's access level, and the submitted 685 query. Besides, servers can change the method over time without 686 announcing anything to clients. The considerations that have led to 687 this solution are described in more detail in Appendix B. 689 The ABNF syntax of the cursor parameter is the following: 691 cursor = "cursor=" 1*( ALPHA / DIGIT / "/" / "=" / "-" / "_" ) 693 The following is an example of an RDAP query including the "cursor" 694 parameter: 696 https://example.com/rdap/domains?name=example*.com 697 &cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M= 699 2.4.1. Representing Paging Links 701 An RDAP server SHOULD use the "links" array of the "paging_metadata" 702 element to provide a ready-made reference [RFC8288] to the next page 703 of the result set (Figure 3). Examples of additional "rel" values a 704 server MAY implement are "first", "last", and "prev". 706 { 707 "rdapConformance": [ 708 "rdap_level_0", 709 "paging" 710 ], 711 ... 712 "notices": [ 713 { 714 "title": "Search query limits", 715 "type": "result set truncated due to excessive load", 716 "description": [ 717 "search results for domains are limited to 50" 718 ] 719 } 720 ], 721 "paging_metadata": { 722 "totalCount": 73, 723 "pageSize": 50, 724 "pageNumber": 1, 725 "links": [ 726 { 727 "value": "https://example.com/rdap/domains?name=example*.com", 728 "rel": "next", 729 "href": "https://example.com/rdap/domains?name=example*.com 730 &cursor=wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=", 731 "title": "Result Pagination Link", 732 "type": "application/rdap+json" 733 } 734 ] 735 }, 736 "domainSearchResults": [ 737 ... 738 ] 739 } 741 Figure 3: Example of a "paging_metadata" instance to implement cursor 742 pagination 744 3. Negative Answers 746 The constraints for the parameters values are defined by their ABNF 747 syntax. Therefore, each request that includes an invalid value for a 748 parameter SHOULD produce an HTTP 400 (Bad Request) response code. 749 The same response SHOULD be returned in the following cases: 751 o if in both single and multi sort the client provides an 752 unsupported value for the "sort" parameter, as well as a value 753 related to an object property not included in the response; 755 o if the client submits an invalid value for the "cursor" parameter. 757 Optionally, the response MAY include additional information regarding 758 either the supported sorting properties or the correct cursor values 759 in the HTTP entity body (Figure 4). 761 { 762 "errorCode": 400, 763 "title": "Domain sorting property 'unknownproperty' is not valid", 764 "description": [ 765 "Supported domain sorting properties are: 'aproperty', 'anotherproperty'." 766 ] 768 } 770 Figure 4: Example of RDAP error response due to an invalid domain 771 sorting property included in the request 773 4. Implementation Considerations 775 Implementation of the new parameters is technically feasible, as 776 operators for counting, sorting and paging are currently supported by 777 the major relational database management systems. Similar operators 778 are completely or partially supported by the most well-known NoSQL 779 databases (e.g. MongoDB, CouchDB, HBase, Cassandra, Hadoop). 780 Additional implementation notes are included in Appendix C. 782 5. IANA Considerations 784 IANA is requested to register the following values in the RDAP 785 Extensions Registry: 787 Extension identifier: paging 788 Registry operator: Any 789 Published specification: This document. 790 Contact: IETF 791 Intended usage: This extension describes best practice for result 792 set paging. 794 Extension identifier: sorting 795 Registry operator: Any 796 Published specification: This document. 797 Contact: IETF 798 Intended usage: This extension describes best practice for result 799 set sorting. 801 6. Implementation Status 803 NOTE: Please remove this section and the reference to RFC 7942 prior 804 to publication as an RFC. 806 This section records the status of known implementations of the 807 protocol defined by this specification at the time of posting of this 808 Internet-Draft, and is based on a proposal described in [RFC7942]. 809 The description of implementations in this section is intended to 810 assist the IETF in its decision processes in progressing drafts to 811 RFCs. Please note that the listing of any individual implementation 812 here does not imply endorsement by the IETF. Furthermore, no effort 813 has been spent to verify the information presented here that was 814 supplied by IETF contributors. This is not intended as, and must not 815 be construed to be, a catalog of available implementations or their 816 features. Readers are advised to note that other implementations may 817 exist. 819 According to RFC 7942, "this will allow reviewers and working groups 820 to assign due consideration to documents that have the benefit of 821 running code, which may serve as evidence of valuable experimentation 822 and feedback that have made the implemented protocols more mature. 823 It is up to the individual working groups to use this information as 824 they see fit". 826 6.1. IIT-CNR/Registro.it 828 Responsible Organization: Institute of Informatics and Telematics 829 of the National Research Council (IIT-CNR)/Registro.it 830 Location: https://rdap.pubtest.nic.it/ 831 Description: This implementation includes support for RDAP queries 832 using data from .it public test environment. 833 Level of Maturity: This is an "alpha" test implementation. 834 Coverage: This implementation includes all of the features 835 described in this specification. 836 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 838 6.2. APNIC 840 Responsible Organization: Asia-Pacific Network Information Centre 841 Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/sorting- 842 and-paging 843 Description: A proof-of-concept for RDAP mirroring. 844 Level of Maturity: This is a proof-of-concept implementation. 845 Coverage: This implementation includes all of the features 846 described in the specification except for nameserver sorting and 847 unicodeName sorting. 848 Contact Information: Tom Harrison, tomh@apnic.net 850 7. Security Considerations 852 Security services for the operations specified in this document are 853 described in [RFC7481]. 855 A search query typically requires more server resources (such as 856 memory, CPU cycles, and network bandwidth) when compared to a lookup 857 query. This increases the risk of server resource exhaustion and 858 subsequent denial of service. This risk can be mitigated by either 859 restricting search functionality or limiting the rate of search 860 requests. Servers can also reduce their load by truncating the 861 results in a response. However, this last security policy can result 862 in a higher inefficiency or risk due to acting on incomplete 863 information if the RDAP server does not provide any functionality to 864 return the truncated results. 866 The new parameters presented in this document provide RDAP operators 867 with a way to implement a server that reduces inefficiency risks. 868 The "count" parameter gives the client the ability to evaluate the 869 completeness of a response. The "sort" parameter allows the client 870 to obtain the most relevant information at the beginning of the 871 result set. This can reduce the number of unnecessary search 872 requests. Finally, the "cursor" parameter enables the user to scroll 873 the result set by submitting a sequence of sustainable queries within 874 server-acceptable limits. 876 8. References 878 8.1. Normative References 880 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 881 Requirement Levels", BCP 14, RFC 2119, 882 DOI 10.17487/RFC2119, March 1997, 883 . 885 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 886 Specifications: ABNF", STD 68, RFC 5234, 887 DOI 10.17487/RFC5234, January 2008, 888 . 890 [RFC5890] Klensin, J., "Internationalized Domain Names for 891 Applications (IDNA): Definitions and Document Framework", 892 RFC 5890, DOI 10.17487/RFC5890, August 2010, 893 . 895 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 896 DOI 10.17487/RFC6350, August 2011, 897 . 899 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 900 DOI 10.17487/RFC7095, January 2014, 901 . 903 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 904 Protocol (HTTP/1.1): Message Syntax and Routing", 905 RFC 7230, DOI 10.17487/RFC7230, June 2014, 906 . 908 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 909 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 910 DOI 10.17487/RFC7231, June 2014, 911 . 913 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 914 Registration Data Access Protocol (RDAP)", RFC 7480, 915 DOI 10.17487/RFC7480, March 2015, 916 . 918 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 919 Registration Data Access Protocol (RDAP)", RFC 7481, 920 DOI 10.17487/RFC7481, March 2015, 921 . 923 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 924 Protocol (RDAP) Query Format", RFC 7482, 925 DOI 10.17487/RFC7482, March 2015, 926 . 928 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 929 Registration Data Access Protocol (RDAP)", RFC 7483, 930 DOI 10.17487/RFC7483, March 2015, 931 . 933 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 934 Code: The Implementation Status Section", BCP 205, 935 RFC 7942, DOI 10.17487/RFC7942, July 2016, 936 . 938 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 939 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 940 May 2017, . 942 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 943 Interchange Format", STD 90, RFC 8259, 944 DOI 10.17487/RFC8259, December 2017, 945 . 947 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 948 DOI 10.17487/RFC8288, October 2017, 949 . 951 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 952 ICANN Extensions for the Registration Data Access Protocol 953 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 954 . 956 8.2. Informative References 958 [CURSOR] Nimesh, R., "Paginating Real-Time Data with Keyset 959 Pagination", July 2014, . 962 [CURSOR-API1] 963 facebook.com, "facebook for developers - Using the Graph 964 API", July 2017, . 967 [CURSOR-API2] 968 twitter.com, "Pagination", 2017, 969 . 972 [GOESSNER-JSON-PATH] 973 Goessner, S., "JSONPath - XPath for JSON", 2007, 974 . 976 [HATEOAS] Jedrzejewski, B., "HATEOAS - a simple explanation", 2018, 977 . 980 [JSONPATH-COMPARISON] 981 "JSONPath Comparison", 2020, 982 . 984 [JSONPATH-WG] 985 "JSON Path (jsonpath)", 2020, 986 . 988 [OData-Part1] 989 Pizzo, M., Handl, R., and M. Zurmuehl, "OData Version 4.0. 990 Part 1: Protocol Plus Errata 03", June 2016, 991 . 996 [REST] Fielding, R., "Architectural Styles and the Design of 997 Network-based Software Architectures", 2000, 998 . 1001 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 1002 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 1003 DOI 10.17487/RFC6901, April 2013, 1004 . 1006 [SEEK] EverSQL.com, "Faster Pagination in Mysql - Why Order By 1007 With Limit and Offset is Slow?", July 2017, 1008 . 1011 [W3C.CR-xpath-31-20161213] 1012 Robie, J., Dyck, M., and J. Spiegel, "XML Path Language 1013 (XPath) 3.1", World Wide Web Consortium CR CR-xpath- 1014 31-20161213, December 2016, 1015 . 1017 Appendix A. JSONPath operators 1019 The jsonpaths used in this document are provided according to the 1020 Goessner v.0.8.0 proposal [GOESSNER-JSON-PATH]. 1022 Such specification requires that implementations support a set of 1023 "basic operators". These operators are used to access the elements 1024 of a JSON structure like objects and arrays, and their subelements, 1025 respectively, object members and array items. No operations are 1026 defined for retrieving parent or sibling elements of a given element. 1027 The root element is always referred to as $ regardless of it being an 1028 object or array. 1030 Additionally, the specification permits implementations to support 1031 arbitrary script expressions. These can be used to index into an 1032 object or array, or to filter elements from an array. While script 1033 expression behavior is implementation-defined, most implementations 1034 support the basic relational and logical operators, as well as both 1035 object member and array item access, sufficiently similar for the 1036 purpose of this document. Commonly-supported operators/functions 1037 divided into "top-level operators" and "filter operators" are 1038 documented in Table 2 and Table 3 respectively. 1040 For more information on implementation interoperability issues, see 1041 [JSONPATH-COMPARISON]. As at the time of writing, work is beginning 1042 on a standardization effort, too: see [JSONPATH-WG]. 1044 +-------------------+-----------------------------------------+ 1045 | Operator | Description | 1046 +-------------------+-----------------------------------------+ 1047 | $ | Root element | 1048 | . | Object member access (dot-notation) | 1049 | [''] | Object member access (bracket-notation) | 1050 | [] | Array item access | 1051 | * | All elements within the specified scope | 1052 | [?()] | Filter expression | 1053 +-------------------+-----------------------------------------+ 1055 Table 2: JSONPath Top-Level Operators 1057 +--------------------+----------------------------------------+ 1058 | Operator | Description | 1059 +--------------------+----------------------------------------+ 1060 | @ | Current element being processed | 1061 | . | Object member access | 1062 | .[,] | Union of object members | 1063 | [] | Array item access | 1064 | == | Left is equal to right | 1065 | != | Left is not equal to right | 1066 | < | Left is less than right | 1067 | <= | Left is less than or equal to right | 1068 | > | Left is greater than right | 1069 | >= | Left is greater than or equal to right | 1070 | && | Logical conjunction | 1071 | || | Logical disjunction | 1072 +--------------------+----------------------------------------+ 1074 Table 3: JSONPath Filter Operators 1076 Appendix B. Approaches to Result Pagination 1078 An RDAP query could return a response with hundreds, even thousands, 1079 of objects, especially when partial matching is used. For this 1080 reason, the cursor parameter addressing result pagination is defined 1081 to make responses easier to handle. 1083 Presently, the most popular methods to implement pagination in a REST 1084 API include offset pagination and keyset pagination. Neither 1085 pagination method requires the server to handle the result set in a 1086 storage area across multiple requests since a new result set is 1087 generated each time a request is submitted. Therefore, they are 1088 preferred to any other method requiring the management of a REST 1089 session. 1091 Using limit and offset operators represents the traditionally used 1092 method to implement result pagination. Both of them can be used 1093 individually: 1095 o "limit=N": means that the server returns the first N objects of 1096 the result set; 1098 o "offset=N": means that the server skips the first N objects and 1099 returns objects starting from position N+1. 1101 When limit and offset are used together, they provide the ability to 1102 identify a specific portion of the result set. For example, the pair 1103 "offset=100,limit=50" returns the first 50 objects starting from 1104 position 101 of the result set. 1106 Though easy to implement, offset pagination also includes drawbacks: 1108 o when offset has a very high value, scrolling the result set could 1109 take some time; 1111 o it always requires fetching all rows before dropping as many rows 1112 as specified by offset; 1114 o it may return inconsistent pages when data are frequently updated 1115 (i.e. real-time data). 1117 Keyset pagination [SEEK] adds a query condition that enables the 1118 selection of the only data not yet returned. This method has been 1119 taken as the basis for the implementation of a "cursor" parameter 1120 [CURSOR] by some REST API providers [CURSOR-API1] [CURSOR-API2]. The 1121 cursor is an opaque to client URL-safe string representing a logical 1122 pointer to the first result of the next page. 1124 Nevertheless, even keyset pagination can be troublesome: 1126 o it needs at least one key field; 1128 o it does not allow sorting simply by any field because the sorting 1129 criterion must contain a key; 1131 o it works best with full composite values support by data base 1132 management systems (i.e. [x,y]>[a,b]), emulation is possible but 1133 inelegant and less efficient; 1135 o it does not allow direct navigation to arbitrary pages because the 1136 result set must be scrolled in sequential order starting from the 1137 initial page; 1139 o implementing bi-directional navigation is tedious because all 1140 comparison and sort operations have to be reversed. 1142 B.1. Specific Issues Raised by RDAP 1144 Some additional considerations can be made in the RDAP context: 1146 o an RDAP object is a conceptual aggregation of information 1147 generally collected from more than one data structure (e.g. table) 1148 and this makes it even harder to implement keyset pagination, a 1149 task that is already quite difficult. For example, the entity 1150 object can include information from different data structures 1151 (registrars, registrants, contacts, resellers), each one with its 1152 key field mapping the RDAP entity handle; 1154 o depending on the number of page results as well as the number and 1155 the complexity of the properties of each RDAP object in the 1156 response, the time required by offset pagination to skip the 1157 previous pages could be much faster than the processing time 1158 needed to build the current page. In fact, RDAP objects are 1159 usually formed by information belonging to multiple data 1160 structures and containing multivalued properties (i.e. arrays) 1161 and, therefore, data selection might therefore be a time consuming 1162 process. This situation occurs even though the selection is 1163 supported by indexes; 1165 o depending on the access levels defined by each RDAP operator, the 1166 increase in complexity and the decrease in flexibility of keyset 1167 pagination in comparison to offset pagination could be considered 1168 impractical. 1170 Ultimately, both pagination methods have benefits and drawbacks. 1172 Appendix C. Additional Implementation Notes 1174 This section contains an overview of the main choices made during the 1175 implementation of the capabilities defined above in the RDAP public 1176 test server of Registro.it at the Institute of Informatics and 1177 Telematics of the National Research Counci (IIT-CNR). The content of 1178 this section can represent a guidance for those implementers who plan 1179 to provide RDAP users with those capabilities. The RDAP public test 1180 server can be accessed at https://rdap.pubtest.nic.it/. Further 1181 documentation about the server features is available at 1182 https://rdap.pubtest.nic.it/doc/README.html. 1184 C.1. Sorting 1186 If no sort criterion is specified in the query string, the results 1187 are sorted by a default property: "name" for domains and nameservers, 1188 "handle" for entities. The server supports multiple property sorting 1189 but the "sorting_metadata" object includes only the links to 1190 alternative result set views sorted by a single property just to show 1191 the list of sorting properties allowed for each searchable object. 1192 The server supports all the object specific sorting properties 1193 described in the specification except for nameserver sorting based on 1194 unicodeName, that is, the "name" sorting property is mapped onto the 1195 "ldhName" response field. Regarding the object common properties, 1196 the sorting by registrationDate, expirationDate, lastChangedDate and 1197 transferDate is supported. 1199 C.2. Counting 1201 The counting operation is implemented through a separate query. Some 1202 relational database management systems support custom operators to 1203 get the total count together with the rows, but the resulting query 1204 can be considerably more expensive than that performed without the 1205 total count. Therefore, as "totalCount" is an optional response 1206 information, fetching always the total number of rows has been 1207 considered an inefficient solution. Furthermore, to avoid the 1208 processing of unnecessary queries, when the "count" parameter is 1209 included in the submitted query, it is not also repeated in the query 1210 strings of the "links" array provided in both "paging_metadata" and 1211 "sorting_metadata" objects. 1213 C.3. Paging 1215 The server implements the cursor pagination through the keyset 1216 pagination when sorting by a unique property is requested or the 1217 default sort is applied, through offset pagination otherwise. As 1218 most of the relational database management systems don't support the 1219 comparison of full composite values natively, the implementation of 1220 full keyset pagination seem to be troublesome so, at least initially, 1221 a selective applicability of keyset pagination is advisable. 1222 Moreover, the "cursor" value encodes not only information about 1223 pagination but also about the search pattern and the other query 1224 parameters in order to check the consistency of the entire query 1225 string. If the "cursor" value is inconsistent with the rest of the 1226 query string, the server returns an error response. 1228 Acknowledgements 1230 The authors would like to acknowledge Brian Mountford, Tom Harrison, 1231 Karl Heinz Wolf, Jasdip Singh, Erik Kline, Eric Vyncke, Benjamin 1232 Kaduk and Roman Danyliw for their contribution to the development of 1233 this document. 1235 Change Log 1237 00: Initial working group version ported from draft-loffredo-regext- 1238 rdap-sorting-and-paging-05 1239 01: Removed both "offset" and "nextOffset" to keep "paging_metadata" 1240 consistent between the pagination methods. Renamed 1241 "Considerations about Paging Implementation" section in ""cursor" 1242 Parameter". Removed "FOR DISCUSSION" items. Provided a more 1243 detailed description of both "sorting_metadata" and 1244 "paging_metadata" objects. 1245 02: Removed both "offset" and "limit" parameters. Added ABNF syntax 1246 of the cursor parameter. Rearranged the layout of some sections. 1247 Removed some items from "Informative References" section. Changed 1248 "IANA Considerations" section. 1249 03: Added "cc" to the list of sorting properties in "Sorting 1250 Properties Declaration" section. Added RFC8605 to the list of 1251 "Informative References". 1252 04: Replaced "ldhName" with "name" in the "Sorting Properties 1253 Declaration" section. Clarified the sorting logic for the JSON 1254 value types and the sorting policy for multivalued fields. 1255 05: Clarified the logic of sorting on IP addresses. Clarified the 1256 mapping between the sorting properties and the RDAP response 1257 fields. Updated "Acknowledgements" section. 1258 06: Renamed "pageCount" to "pageSize" and added "pageNumber" in the 1259 "paging_metadata" object. 1260 07: Added "Paging Responses to POST Requests" section. 1261 08: Added "Approaches to Result Pagination" section to appendix. 1262 Added the case of requesting a sort on a property not included in 1263 the response to the errors listed in the "Negative Answers" 1264 section. 1265 09: Updated the "Implementation Status" section to include APNIC 1266 implementation. Moved the "RDAP Conformance" section up in the 1267 document. Removed the "Paging Responses to POST Requests" 1268 section. Updated the "Acknowledgements" section. Removed unused 1269 references. In the "Sorting Properties Declaration" section: 1271 * clarified the logic of sorting on events; 1272 * corrected the jsonpath of the "lastChanged" sorting property; 1273 * provided a JSONPath example taking into account the vCard 1274 "pref" parameter. 1276 10: Corrected the jsonpaths of both "fn" and "org" sorting 1277 properties in Table 2. Corrected JSON content in Figure 2. Moved 1278 [W3C.CR-xpath-31-20161213] and [RFC7942] to the "Normative 1279 References". Changed the rdapConformance tags "sorting_level_0" 1280 and "paging_level_0" to "sorting" and "paging" respectively. 1281 11: Added the "JSONPath operators" section to appendix. 1282 12: Changed the content of "JSONPath operators" section. 1283 13: Minor pre-AD review edits. 1284 14: Additionl minor pre-AD review edits. 1285 15: In section ""sort" Parameter" added a paragraph providing 1286 conversions of IP addresses into their numerical representations. 1287 In section "Sorting Properties Declaration" rearranged Table 2 in 1288 a list to make the content more readable. Other minor edits due 1289 to AD review. 1290 16: In section "Introduction" replaced "... large result set that 1291 could be truncated ..." with "... large result set that is often 1292 truncated ..." as suggested by Gen-ART reviewer. Added 1293 Appendix C. 1294 17: Edits made: 1296 * in the "Sorting and Paging Metadata" section: 1298 + replaced "Members are:" with "The AvailableSort object 1299 includes the following members:"; 1300 + clarified that an RDAP server MUST define only one default 1301 sorting property for each object class; 1302 * in the "Negative Answers" section: 1304 + replaced the phrase "the response MAY include additional 1305 information regarding the negative answer" with the phrase 1306 "the response MAY include additional information regarding 1307 either the supported sorting properties or the correct 1308 cursor value"; 1309 + added a new example; 1310 * clarified the required members of a Link object in the 1311 "Representing Sorting Links" section; 1312 * corrected the [REST] reference in the "Informative References" 1313 section; 1314 * replaced the phrase "and subsequent denial of service due to 1315 abuse" with the phrase "and subsequent denial of service" in 1316 "Security Considerations" section. 1317 18: Edits made: 1319 * in the "Introduction" section: 1321 + revised the reasons for using query parameters instead of 1322 HTTP headers; 1323 * in the "Sorting and Paging Metadata" section: 1325 + replaced the phrase "number of objects returned in the 1326 current page" with the phrase "number of objects that should 1327 have been returned in the current page" in the definition of 1328 the "pageSize" field; 1329 * in the ""sort" Parameter" section: 1331 + clarified the sorting logic for values denoting dates and 1332 times; 1333 + replaced the IPv6 address 1334 "2001:0db8:85a3:0000:0000:8a2e:0370:7334" with 1335 "2001:0db8:85a3:0:0:8a2e:0370:7334"; 1336 * in the "Sorting Properties Declaration" section: 1338 + replaced the sorting properties "ipV4" and "ipV6" with 1339 "ipv4" and "ipv6"; 1340 + replaced the sentence "Therefore, the assumption of having a 1341 single IPv4 and/or IPv6 value for a nameserver cannot be 1342 considered too stringent." with the sentence "Therefore, 1343 this specification makes the assumption that nameservers 1344 have a single IPv4 and/or IPv6 value." 1345 + clarified that the sorting properties MUST NOT be used with 1346 a with a meaning other than the one described this document; 1347 + specified that JSONPath operators used in this section are 1348 those defined in "Appendix A"; 1349 * in the ""cursor" Parameter" section: 1351 + corrected the Base64 encoding of "offset=100,limit=50"; 1352 + clarified that RDAP servers are NOT RECOMMENDED to obfuscate 1353 a cursor value through a mere Base64 encoding; 1354 * changed last sentence of second paragraph of the "Security 1355 Considerations" section; 1356 * updated the "Acknowledgements" section; 1357 * in "Appendix A": 1359 + changed introductory paragraph; 1360 + replaced "opaque URL-safe string" with "opaque to client 1361 URL-safe string"; 1362 * added JSONPath union operator in Table 2 of "Appendix B" 1363 * changed the explanation of offset and limit operators in 1364 "Appendix B"; 1365 * converted the figures containing only RDAP queries into texts; 1366 * changed the wildcard prefixed patterns into wildcard suffixed 1367 in all the RDAP queries; 1368 * cleaned the text. 1369 19: Replaced the words "encryption/encrypt" with "obfuscation/ 1370 obfuscate" in the ""cursor" Parameter" section. 1372 20: Added a final paragraph to Appendix A to reference the 1373 comparison between JSONPath operators and IETF JSONPath WG web 1374 site. 1376 Authors' Addresses 1378 Mario Loffredo 1379 IIT-CNR/Registro.it 1380 Via Moruzzi,1 1381 Pisa 56124 1382 IT 1384 Email: mario.loffredo@iit.cnr.it 1385 URI: http://www.iit.cnr.it 1387 Maurizio Martinelli 1388 IIT-CNR/Registro.it 1389 Via Moruzzi,1 1390 Pisa 56124 1391 IT 1393 Email: maurizio.martinelli@iit.cnr.it 1394 URI: http://www.iit.cnr.it 1396 Scott Hollenbeck 1397 Verisign Labs 1398 12061 Bluemont Way 1399 Reston, VA 20190 1400 USA 1402 Email: shollenbeck@verisign.com 1403 URI: https://www.verisignlabs.com/