Registration Data Access Protocol (RDAP) Query Parameters for Result Sorting and Paging
draft-ietf-regext-rdap-sorting-and-paging-20

[Ballot comment]
Thanks for the updates in the -18; they look good with one exception:

In Section 2.4, I strongly recommend using the word "encode" (and "encoding")
instead of "encrypt" (and "encryption") -- it is good to reserve the term "encrypt"
for a procedure that applies cryptographic protection.  Part of why we are
anti-recommending base64 for this usage is because it does not provide cryptographic
protection, so it is surprising to use the word "encrypt" to describe it.

[Ballot comment]
I support Roman's DISCUSS point about resolving the JSONPath reference.  I'm working the chartering of the proposed "jsonpath" working group, so I'm happy to contribute to resolving this.  And a "thank you" to the document shepherd for including this in the writeup.  Another possible option is to cite draft-goessner-dispatch-jsonpath, marking it as "work in progress", though I think that's still tricky because we don't know for sure that changes produced by the proposed working group will be fully backward-compatible with what this document requires.

I also support Ben's DISCUSS point about multi-sorts.

Section 1:

A totally minor nit, but I think the reference to RFC 7230 should be up where HTTP is first used.

Section 2.2:

The ABNF here reminds me that string literals in ABNF are case-insensitive (RFC 5234, Section 2.3).  Just wanted to check that "COUNT=fAlSe" is fine here, for example.

[Ballot discuss]
Should we say something about which order the sorting criteria are
applied (first to last vs last to first) when multiple sortItems are
specified in a query?

I recognize that in the HATEOS model, the actual JSONPaths reported by
the server should be used by the client to determine what a given sort
property does, but it also seems like it would be confusing for this
document to specify (e.g.) an "email" property with specific JSONPath,
and then have a server go off and use "email" to mean something else,
even if that is just the addition of "pref" as discussed at the end of
Section 2.3.1.  Do we want to try to have the properties defined by this
document be universally defined and encourage the use of new/different
property names for variations on them?  (The answer may well be "no",
but the answer is not intuitively clear to me.)  To put it another way,
is the list in Section 2.3.1 normative, or just an example?

[Ballot comment]
Section 1

  However, there are some drawbacks associated with the use of the HTTP
  header.  First, the header properties cannot be set directly from a
  web browser.  Moreover, in an HTTP session, the information on the
  status (i.e. the session identifier) is usually inserted in the
  header or a cookie, while the information on the resource
  identification or the search type is included in the query string.
  The second approach is therefore not compliant with the HTTP standard
  [RFC7230].  As a result, this document describes a specification
  based on the use of query parameters.

A few more words (section number from 7230?) on why the second approach
is not compliant with HTTP might help the reader, though it isn't
stricly necessary (we're not using it, after all).

Section 2.1

      *  "jsonPath": "String" (OPTIONAL) the JSONPath of the RDAP field
        corresponding to the property;

What is this path relative to?  (Does the client have to know from the
other context what type of object it refers to?)

      *  "links": "Link[]" (OPTIONAL) an array of links as described in
        [RFC8288] containing the query string that applies the sort
        criterion.

Just to check: this is going to have the same structure for a Link
object that draft-ietf-regext-rdap-partial-response does?  (I am not
coming up with a great way to deduplicate the definitions, off the top
of my head.)

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

If it's redundant, we should probably say something about error handling
for when the things that are supposed to be identical have different
values.

Section 2.3

  Except for sorting IP addresses, servers MUST implement sorting
  according to the JSON value type of the RDAP field the sorting
  property refers to.  That is, JSON strings MUST be sorted
  lexicographically and JSON numbers MUST be sorted numerically.  If IP
  addresses are represented as JSON strings, they MUST be sorted based
  on their numeric conversion.

There are more JSON types than string and number; are those other types
garanteed to not appear in sortable RDAP fields?  (I can't see how such
a guarantee could be made, given that servers can define their own
sorting properties.)

  If the "sort" parameter reports an allowed sorting property, it MUST
  be provided in the "currentSort" field of the "sorting_metadata"
  element.

nit: is "reports" the best word to describe this behavior (which, IIUC,
is "present in the query component of the request URL"?

Section 2.3.1

  In the "sort" parameter ABNF syntax, property-ref represents a
  reference to a property of an RDAP object.  Such a reference could be
  expressed by using a JSONPath.  The JSONPath in a JSON document

nit: is there a missing word here ("a JSONPath expression")?

  o  Note that some of the object specific properties are also defined
      as query paths.  The object specific properties include:

nit: the list structure in this item does not seem parallel to the
structure of the first item.

      as two representations of the same value.  By default, the
      unicodeName value MUST be used while sorting.  When the
      unicodeName is unavailable, the value of the ldhName MUST be used
      instead;

I'm not entirely sure how much value "by default" adds here.  Would the
meaning be different if we said "The unicodeName value MUST be used
while sorting if it is present; when the unicodeName is unavailable, the
value of the ldhName is used instead"?

  o  The jCard "sort-as" parameter MUST be ignored for the sorting
      capability described in this document;

It's a little bit of a juxtaposition to refer to jCard here in the prose
but vcard in the table.

  o  Even if a nameserver can have multiple IPv4 and IPv6 addresses,
      the most common configuration includes one address for each IP
      version.  Therefore, the assumption of having a single IPv4 and/or
      IPv6 value for a nameserver cannot be considered too stringent.

I disagree with the flat assertion that it "cannot be considered too
stringent".  It can be so considered, as a matter of difference of
opinion; what is appropriate to do here is to say that this
document/protocol makes the assumption (especially since we go on to
describe the exception-handling procedure when the assumption is
violated).

  o  Multiple events with a given action on an object might be
      returned.  If this occurs, sorting MUST be applied to the most
      recent event;

This makes a lot of sense as the default and I don't propose changing it
now, but I do wonder how hard it would be to add support later for
sorting on (say) the oldest event instead.

  The "jsonPath" field in the "sorting_metadata" element is used to
  clarify the RDAP field the sorting property refers to.  The mapping
  between the sorting properties and the JSONPaths of the RDAP fields
  is shown below:
  [...]
      name

        $.domainSearchResults[*].unicodeName

This seems to ignore the subtlety regarding unicodeName vs ldhName.  Is
there a way it could be expressed in JSONPath?

  o  Nameserver

      name

        $.domainSearchResults[*].unicodeName

Presumably this is supposed to be nameserverSearchResults?

Section 2.4

I think we want another introductory paragraph like:

% The cursor parameter is used by the server to preserve information
% about the pagination state of a given query's results across calls to
% the search API, so that successive requests by the client can return
% page N, N+1, N+2, etc.  Its value is only required to be interpretable
% by the server and could be implemented, for example, as an opaque
% database lookup key.  If a server does use a method for generating
% cursor values that involves internal structure, such as the one
% described below, the server needs to recognize that the value supplied
% by a client could have been modified (maliciously), and implement
% appropriate bounds-checking and similar measures when parsing received
% values.

The current wording strongly suggests that base64-encoding a meaningful
value that the client could inspect or even construct is required, and I
do not think that is very maintainable or what was intended, given the
current second paragraph ("servers can change the method over time
without announcing anything to clients").

(side note) I'm also pretty partial to the way JMAP discusses returning
(paginated, but non-uniformly) changes to a given data stream, e.g., at
https://www.rfc-editor.org/rfc/rfc8620.html#section-5.2 -- any given
state is named, and you can get "stuff starting at " and
the name to use for the state as of the current reply.

Section 4

If the server doesn't have access to an efficient (e.g.) counting
operation on the backend, would we recommend that the server not support
sorting/pagination, since there's not much benefit from having the
server pull up all the results and count them just to be able to return
the total count value back to the client, and then go do the same work again
when the client asks for the next page of results?

Section 7

I suggest noting that (encoded) structured "cursor" values present a new
attack surface on the server that needs to be protected.

  results in a response.  However, this last security policy can result
  in a higher inefficiency if the RDAP server does not provide any
  functionality to return the truncated results.

I'm not sure I understand (or agree with) this last sentence -- it seems
that unlateral silent truncation of results by the server leads to not
just inefficiency but also potential security considerations in its own
right, with the client not knowing that it has incomplete results.
Also, if the server is truncating the results, by definition it "has
functionality to return the truncated results" -- that's what it's
doing!  So I assume the intent was to say something about negotiating or
indicating that the results are truncated, not actually doing the
truncation.

  The new parameters presented in this document provide RDAP operators
  with a way to implement a server that reduces inefficiency risks.

[same question about "inefficiency" being the right word]

Appendix B

  o  It does not allow direct navigation to arbitrary pages because the
      result set must be scrolled in sequential order starting from the
      initial page;

(side note) I didn't follow the references, so maybe this was covered
there, but I don't quite follow why direct navigation is impossible.  If
you use a key field for seeking, can't you just start in the middle from
some known value for that key field?

Appendix C.2

  total count.  Therefore, as "totalCount" is an optional response
  information, fetching always the total number of rows has been

I'm not entirely sure in what sense "optional response information" is
intended -- my reading of Section 2.1 is that it's mandatory to return
totalCount if the client included the 'count' query parameter.

[Ballot discuss]
** Canonical Reference for JSONPath.  Section 2.1/2.3.1 describes field(s) whose syntax is in JSONPath.  The shepherd’s note acknowledges that there is no good reference for JSONPath.  Nevertheless, the text needs to be clearer on where to turn to for guidance.

(1) Section 2.3.1 says: “Such a reference could be
  expressed by using a JSONPath.  The JSONPath in a JSON document
  [RFC8259] is equivalent to the XPath [W3C.CR-xpath-31-20161213] in a
  XML document. 

(2) The JSONPaths are provided according to the Goessner v.0.8.0
  specification [GOESSNER-JSON-PATH].

(3) Further documentation about
  JSONPath operators used in this specification is included in
  Appendix A.

Taking the perspective of the implementer, which of these three resources is canonical for understanding JSONPath:

(a) [W3C.CR-xpath-31-20161213] = a reference marked normative that has nothing to do with JSON but suggests equivalence through a few examples.

(b) [GOESSNER-JSON-PATH] = a reference marked as informative which is being used to describe the normative mapping between JSONPaths of the RDAP fields in the text, and is the actual description of the JSONPath syntax.  The shepherd’s note points out the difficulty of using this as a normative reference

(c) Appendix A = self-contained text which describes JSONPath independent of (a) and (c).  As an aside, I’m not sure of the completeness of this write-up.
Additionally, the IETF is currently considering it’s own version of JSONPath -- https://datatracker.ietf.org/doc/charter-ietf-jsonpath/

IMO, the fig leaf of citing [W3C.CR-xpath-31-20161213] is inappropriate (as in, it isn’t the actual reference) and unnecessary (as in, it’s just there to meet the letter of having a normative reference).  I recommend being practical about the need:

-- Use language to the effect of saying the “JSONPath used here is a flavor defined in XXX”

-- Make “XXX” be Appendix A.

-- Bolster Appendix A to say something to the effect of “this version of JSONPath is inspired by [W3C.CR-xpath-31-20161213] (informative reference) and an articulation of what is used in production [GOESSNER-JSON-PATH] (informative reference)”; and where necessary, add more language around the syntax.

This approach will also allow for new JSONPath WG to define a variant which is not strictly compatible (if that’s where the work goes).

I’m open to an alternative approach.  I just want to end up with a single clear reference of where to read about this documents particular JSONPath syntax.

** Section 2.4.  Does this specification provide any normative guidance of “cursor” beyond an opaque value constrained by ABNF?  The text notes the notion of “offsets”, “limits”, and “keys”, Base64, CSV but these appear to be referenced as examples.  However, Appendix B contains normative language around “limit” and “offset”.

[Ballot comment]
Thank you for the SECDIR review, Rifaat (Shekh-Yusef)!

** Section 2.3.1.  The text notes that JSON Pointer is “hard to use”.  It wasn’t clear where the mandate to use JSON Pointer came.

** Section 2.4.  Please replace thelastdomainofthepage.com with example.*

** Section 2.4  Is there any semantics to read into “&cursor=wJ…” in Figure 5 beyond it being blob conforming to the cursor ABNF?  Editorially, the text doesn’t reference it to explain what’s there.

** Section 7.  The issue of paging is being framed as primarily a security issue is puzzling.  It seems to me that this is about providing a more usable API for the client which has a net benefit of reducing the resources required to serve the comparable information.  If DoS is really the concern, the queries can be rate or resource limited by the application or the underlying RDMS (whose underlying capabilities are explained in earlier text as making this process efficient)

** Section 7.  Per the third paragraph, what is the security issue?  What’s the threat?

** Section 7.  Concur with Eric, there appears to be an implicit assumption that returning subsets of a record set is “fast” and so is counting the number of records.  IMO, this isn’t a problem if this is a stated assumption.

[Ballot comment]
[[ comments ]]

[ section 2.3 ]

* My current understanding is that it's not possible to request a sort by
  IP address in general (i.e. without regard to IP address family).  Otherwise,
  since some IPv6 addresses (admittedly not any within the current 2000::/3
  GUA space) might be numerically less then some IPv4 addresses, I think there
  would probably need to be some text around relative ordering between IPv4 and
  IPv6 addresses regardless of numerical equivalent values.

  But again: my reading is that sort can only be by ipV4 or ipV6 (and not just
  some generalized "ip" parameter), so this shouldn't be necessary.


[[ nits ]]

[ section 2.1 ]

* s/value of sort "parameter"/value of the "sort" parameter/ perhaps?

[ section 2.4 ]

* I think the cursor value "b2Zmc2V0PTEwMCxsaW1pdD01MAo=" might decode to
  'offset=100,limit=50\n' (with a trailing newline).  The base64 encoding
  without the trailing newline might be 'b2Zmc2V0PTEwMCxsaW1pdD01MA==', but
  someone should double-check me on that.

[Ballot comment]
Thank you for the work put into this document.

Please find below a couple of non-blocking COMMENT points (but, to be honest, I was close to put a DISCUSS about server performance impact that is not fully addressed in the security section).

I hope that this helps to improve the document,

Regards,

-éric

== COMMENTS ==

-- Section 2.1 --
I find the wording a little confusing in ""totalCount": "Numeric" (OPTIONAL) ...  It MUST be provided if and only if ...". While I understand the meaning, would another wording avoid the conflicting "OPTIONAL" <-> "MUST" ? I.e., the "OPTIONAL" could possibly be removed.

-- Section 2.2 --
I am concerned that a server having to compute "totalCount" (even if only to return the first 10 entries) may spend a lot of time computing this number in the absence of index... The security section does not offer a definitive answer to this issue IMHO. E.g., I would prefer to allow the server to refuse to serve "totalCount" until the last page (and even).

-- Section 2.3 --
Is there a reason why RFC 5952 was not used to represent the IPv6 address ?

I am concerned that a server having to sort on client-side selection of properties may have a huge performance impact in the absence of relevant DB indexes.The security section does not offer a definitive answer to this issue IMHO.

-- Section 2.3.1 --
Is there a reason for this unusual writing of 'ipV4' (uppercase V) ?

-- Section 2.4 --
Suggestion: mention that the cursor value is opaque for the client ?
     
== NITS ==

-- Section 2.2 --
Is a 'figure' element really required for a single line example ?

Should the URI be "https://example.com/rdap/domains?name=*example.com&count=true" (also applicable to section 2.3)

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-regext-rdap-sorting-and-paging-15. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there is a single action which we must complete.

In the RDAP Extensions registry located at:

https://www.iana.org/assignments/rdap-extensions/

two new registrations are to be made as follows:

Extension identifier: paging
Registry operator: Any
Published specification: [ RFC-to-be ]
Contact: IETF
Intended usage: This extension describes best practice for result set paging.

Extension identifier: sorting
Registry operator: Any
Published specification: [ RFC-to-be ]
Contact: IETF
Intended usage: This extension describes best practice for result set sorting.

As this document requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

The IANA Functions Operator understands that this is the only action required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2020-08-13):

From: The IESG
To: IETF-Announce
CC: draft-ietf-regext-rdap-sorting-and-paging@ietf.org, barryleiba@gmail.com, tomh@apnic.net, Tom Harrison , regext@ietf.org, regext-chairs@ietf.org
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Registration Data Access Protocol (RDAP) Query Parameters for Result Sorting and Paging) to Proposed Standard


The IESG has received a request from the Registration Protocols Extensions WG
(regext) to consider the following document: - 'Registration Data Access
Protocol (RDAP) Query Parameters for Result
  Sorting and Paging'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2020-08-13. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  The Registration Data Access Protocol (RDAP) does not include core
  functionality for clients to provide sorting and paging parameters
  for control of large result sets.  This omission can lead to
  unpredictable server processing of queries and client processing of
  responses.  This unpredictability can be greatly reduced if clients
  can provide servers with their preferences for managing large
  responses.  This document describes RDAP query extensions that allow
  clients to specify their preferences for sorting and paging result
  sets.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-regext-rdap-sorting-and-paging/



No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc8605: vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP) (Informational - IETF stream)

> As required by RFC 4858, this is the current template for the Document
> Shepherd Write-Up. Changes are expected over time.
>
> This version is dated 1 November 2019.
>
> (1) What type of RFC is being requested (BCP, Proposed Standard,
> Internet Standard, Informational, Experimental, or Historic)? Why is
> this the proper type of RFC? Is this type of RFC indicated in the
> title page header?

The type of RFC being requested is Proposed Standard, because the
document defines extensions to the existing RDAP protocol.  The type
is indicated in the title page header.

> (2) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up.
> Recent examples can be found in the "Action" announcements for
> approved documents. The approval announcement contains the following
> sections:

Technical Summary:

    This document describes RDAP query extensions that allow clients
    to specify their preferences for sorting and paging result sets.
    This helps clients to find relevant results more easily, as well
    as improving server response times and reducing bandwidth
    requirements.

Working Group Summary:

    This document was posted to the WG back in mid-2017, and has been
    presented at IETF 100 and 103-106, as well as at the Registration
    Operations Workshop (#6).  There was nothing unusual process-wise,
    and no issues with consensus or similar.

Document Quality:

    There are two proof-of-concept implementations, and there were
    a number of reviews from within the group.  No expert review was
    required.

Personnel:

    Document Shepherd: Tom Harrison
    Responsible AD: TBD

> (3) Briefly describe the review of this document that was performed
> by the Document Shepherd. If this version of the document is not
> ready for publication, please explain why the document is being
> forwarded to the IESG.

The document shepherd has reviewed the document in detail, which led
to a number of minor changes in the document, and is also responsible
for one of the proof-of-concept implementations.

> (4) Does the document Shepherd have any concerns about the depth or
> breadth of the reviews that have been performed?

No.  The document has been reviewed by participants from both the
name and number communities.

> (5) Do portions of the document need review from a particular or
> from broader perspective, e.g., security, operational complexity,
> AAA, DNS, DHCP, XML, or internationalization? If so, describe the
> review that took place.

N/A

> (6) Describe any specific concerns or issues that the Document
> Shepherd has with this document that the Responsible Area Director
> and/or the IESG should be aware of? For example, perhaps he or she
> is uncomfortable with certain parts of the document, or has concerns
> whether there really is a need for it. In any event, if the WG has
> discussed those issues and has indicated that it still wishes to
> advance the document, detail those concerns here.

N/A

> (7) Has each author confirmed that any and all appropriate IPR
> disclosures required for full conformance with the provisions of BCP
> 78 and BCP 79 have already been filed. If not, explain why?

The document authors have all confirmed they know of no needed
IPR disclosures.

> (8) Has an IPR disclosure been filed that references this document?
> If so, summarize any WG discussion and conclusion regarding the IPR
> disclosures.

N/A

> (9) How solid is the WG consensus behind this document? Does it
> represent the strong concurrence of a few individuals, with others
> being silent, or does the WG as a whole understand and agree with
> it?

It is more the former than the latter, but there was good support for
adoption, and no concerns have been raised by those who were
originally supportive.

> (10) Has anyone threatened an appeal or otherwise indicated extreme
> discontent? If so, please summarise the areas of conflict in
> separate email messages to the Responsible Area Director. (It should
> be in a separate email because this questionnaire is publicly
> available.)

N/A

> (11) Identify any ID nits the Document Shepherd has found in this
> document. (See http://www.ietf.org/tools/idnits/ and the
> Internet-Drafts Checklist). Boilerplate checks are not enough; this
> check needs to be thorough.

The idnits tool only reported false positives (e.g. due to RFC 8605
being listed as a normative reference, but the text not citing it in
the expected form).

> (12) Describe how the document meets any required formal review
> criteria, such as the MIB Doctor, YANG Doctor, media type, and URI
> type reviews.

N/A

> (13) Have all references within this document been identified as
> either normative or informative?

Yes.

> (14) Are there normative references to documents that are not ready
> for advancement or are otherwise in an unclear state? If such
> normative references exist, what is the plan for their completion?

The document depends on the 'JSON Path' specification
(http://goessner.net/articles/JsonPath/) normatively, in the sense
that JSON Paths are used in protocol responses.  However, since the
JSON Path specification does not meet the requirements for being
included as a normative reference, the document has XPath as a
normative reference (of which the JSON Path specification is an
adaptation) and the JSON Path specification as an informative
reference.

> (15) Are there downward normative references references (see RFC
> 3967)? If so, list these downward references to support the Area
> Director in the Last Call procedure.

N/A

> (16) Will publication of this document change the status of any
> existing RFCs? Are those RFCs listed on the title page header,
> listed in the abstract, and discussed in the introduction? If the
> RFCs are not listed in the Abstract and Introduction, explain why,
> and point to the part of the document where the relationship of this
> document to the other RFCs is discussed. If this information is not
> in the document, explain why the WG considers it unnecessary.

N/A

> (17) Describe the Document Shepherd's review of the IANA
> considerations section, especially with regard to its consistency
> with the body of the document. Confirm that all protocol extensions
> that the document makes are associated with the appropriate
> reservations in IANA registries. Confirm that any referenced IANA
> registries have been clearly identified. Confirm that newly created
> IANA registries include a detailed specification of the initial
> contents for the registry, that allocations procedures for future
> registrations are defined, and a reasonable name for the new
> registry has been suggested (see RFC 8126).

The document requests that two additional entries ('sorting' and
'paging') be added to the IANA RDAP Extensions Registry.  The requests
are consistent with the use of those values in the document.

> (18) List any new IANA registries that require Expert Review for
> future allocations. Provide any public guidance that the IESG would
> find useful in selecting the IANA Experts for these new registries.

N/A

> (19) Describe reviews and automated checks performed by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, YANG
> modules, etc.

The document contains ABNF rules, JSON documents, and JSON Path
strings.  The ABNR rules were validated with
https://tools.ietf.org/tools/bap/abnf.cgi.  The JSON documents were
validated using Perl's JSON::XS.  The JSON Path strings were validated
against the Goessner JS implementation and the Jayway Java
implementation (see https://jsonpath.herokuapp.com/).

> (20) If the document contains a YANG module, has the module been
> checked with any of the recommended validation tools
> (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax
> and formatting validation? If there are any resulting errors or
> warnings, what is the justification for not fixing them at this
> time? Does the YANG module comply with the Network Management
> Datastore Architecture (NMDA) as specified in RFC8342?

N/A

> As required by RFC 4858, this is the current template for the Document
> Shepherd Write-Up. Changes are expected over time.
>
> This version is dated 1 November 2019.
>
> (1) What type of RFC is being requested (BCP, Proposed Standard,
> Internet Standard, Informational, Experimental, or Historic)? Why is
> this the proper type of RFC? Is this type of RFC indicated in the
> title page header?

The type of RFC being requested is Proposed Standard, because the
document defines extensions to the existing RDAP protocol.  The type
is indicated in the title page header.

> (2) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up.
> Recent examples can be found in the "Action" announcements for
> approved documents. The approval announcement contains the following
> sections:

Technical Summary:

    This document describes RDAP query extensions that allow clients
    to specify their preferences for sorting and paging result sets.
    This helps clients to find relevant results more easily, as well
    as improving server response times and reducing bandwidth
    requirements.

Working Group Summary:

    This document was posted to the WG back in mid-2017, and has been
    presented at IETF 100 and 103-106, as well as at the Registration
    Operations Workshop (#6).  There was nothing unusual process-wise,
    and no issues with consensus or similar.

Document Quality:

    There are two proof-of-concept implementations, and there were
    a number of reviews from within the group.  No expert review was
    required.

Personnel:

    Document Shepherd: Tom Harrison
    Responsible AD: TBD

> (3) Briefly describe the review of this document that was performed
> by the Document Shepherd. If this version of the document is not
> ready for publication, please explain why the document is being
> forwarded to the IESG.

The document shepherd has reviewed the document in detail, which led
to a number of minor changes in the document, and is also responsible
for one of the proof-of-concept implementations.

> (4) Does the document Shepherd have any concerns about the depth or
> breadth of the reviews that have been performed?

No.  The document has been reviewed by participants from both the
name and number communities.

> (5) Do portions of the document need review from a particular or
> from broader perspective, e.g., security, operational complexity,
> AAA, DNS, DHCP, XML, or internationalization? If so, describe the
> review that took place.

N/A

> (6) Describe any specific concerns or issues that the Document
> Shepherd has with this document that the Responsible Area Director
> and/or the IESG should be aware of? For example, perhaps he or she
> is uncomfortable with certain parts of the document, or has concerns
> whether there really is a need for it. In any event, if the WG has
> discussed those issues and has indicated that it still wishes to
> advance the document, detail those concerns here.

N/A

> (7) Has each author confirmed that any and all appropriate IPR
> disclosures required for full conformance with the provisions of BCP
> 78 and BCP 79 have already been filed. If not, explain why?

The document authors have all confirmed they know of no needed
IPR disclosures.

> (8) Has an IPR disclosure been filed that references this document?
> If so, summarize any WG discussion and conclusion regarding the IPR
> disclosures.

N/A

> (9) How solid is the WG consensus behind this document? Does it
> represent the strong concurrence of a few individuals, with others
> being silent, or does the WG as a whole understand and agree with
> it?

It is more the former than the latter, but there was good support for
adoption, and no concerns have been raised by those who were
originally supportive.

> (10) Has anyone threatened an appeal or otherwise indicated extreme
> discontent? If so, please summarise the areas of conflict in
> separate email messages to the Responsible Area Director. (It should
> be in a separate email because this questionnaire is publicly
> available.)

N/A

> (11) Identify any ID nits the Document Shepherd has found in this
> document. (See http://www.ietf.org/tools/idnits/ and the
> Internet-Drafts Checklist). Boilerplate checks are not enough; this
> check needs to be thorough.

The idnits tool only reported false positives (e.g. due to RFC 8605
being listed as a normative reference, but the text not citing it in
the expected form).

> (12) Describe how the document meets any required formal review
> criteria, such as the MIB Doctor, YANG Doctor, media type, and URI
> type reviews.

N/A

> (13) Have all references within this document been identified as
> either normative or informative?

Yes.

> (14) Are there normative references to documents that are not ready
> for advancement or are otherwise in an unclear state? If such
> normative references exist, what is the plan for their completion?

The document depends on the 'JSON Path' specification
(http://goessner.net/articles/JsonPath/) normatively, in the sense
that JSON Paths are used in protocol responses.  However, since the
JSON Path specification does not meet the requirements for being
included as a normative reference, the document has XPath as a
normative reference (of which the JSON Path specification is an
adaptation) and the JSON Path specification as an informative
reference.

> (15) Are there downward normative references references (see RFC
> 3967)? If so, list these downward references to support the Area
> Director in the Last Call procedure.

N/A

> (16) Will publication of this document change the status of any
> existing RFCs? Are those RFCs listed on the title page header,
> listed in the abstract, and discussed in the introduction? If the
> RFCs are not listed in the Abstract and Introduction, explain why,
> and point to the part of the document where the relationship of this
> document to the other RFCs is discussed. If this information is not
> in the document, explain why the WG considers it unnecessary.

N/A

> (17) Describe the Document Shepherd's review of the IANA
> considerations section, especially with regard to its consistency
> with the body of the document. Confirm that all protocol extensions
> that the document makes are associated with the appropriate
> reservations in IANA registries. Confirm that any referenced IANA
> registries have been clearly identified. Confirm that newly created
> IANA registries include a detailed specification of the initial
> contents for the registry, that allocations procedures for future
> registrations are defined, and a reasonable name for the new
> registry has been suggested (see RFC 8126).

The document requests that two additional entries ('sorting' and
'paging') be added to the IANA RDAP Extensions Registry.  The requests
are consistent with the use of those values in the document.

> (18) List any new IANA registries that require Expert Review for
> future allocations. Provide any public guidance that the IESG would
> find useful in selecting the IANA Experts for these new registries.

N/A

> (19) Describe reviews and automated checks performed by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, YANG
> modules, etc.

The document contains ABNF rules, JSON documents, and JSON Path
strings.  The ABNR rules were validated with
https://tools.ietf.org/tools/bap/abnf.cgi.  The JSON documents were
validated using Perl's JSON::XS.  The JSON Path strings were validated
against the Goessner JS implementation and the Jayway Java
implementation (see https://jsonpath.herokuapp.com/).

> (20) If the document contains a YANG module, has the module been
> checked with any of the recommended validation tools
> (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax
> and formatting validation? If there are any resulting errors or
> warnings, what is the justification for not fixing them at this
> time? Does the YANG module comply with the Network Management
> Datastore Architecture (NMDA) as specified in RFC8342?

N/A

> As required by RFC 4858, this is the current template for the Document
> Shepherd Write-Up. Changes are expected over time.
>
> This version is dated 1 November 2019.
>
> (1) What type of RFC is being requested (BCP, Proposed Standard,
> Internet Standard, Informational, Experimental, or Historic)? Why is
> this the proper type of RFC? Is this type of RFC indicated in the
> title page header?

The type of RFC being requested is Proposed Standard, because the
document defines extensions to the existing RDAP protocol.  The type
is indicated in the title page header.

> (2) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up.
> Recent examples can be found in the "Action" announcements for
> approved documents. The approval announcement contains the following
> sections:

Technical Summary:

    This document describes RDAP query extensions that allow clients
    to specify their preferences for sorting and paging result sets.
    This helps clients to find relevant results more easily, as well
    as improving server response times and reducing bandwidth
    requirements.

Working Group Summary:

    This document was posted to the WG back in mid-2017, and has been
    presented at IETF 100 and 103-106, as well as at the Registration
    Operations Workshop (#6).  There was nothing unusual process-wise,
    and no issues with consensus or similar.

Document Quality:

    There are two proof-of-concept implementations, and there were
    a number of reviews from within the group.  No expert review was
    required.

Personnel:

    Document Shepherd: Tom Harrison
    Responsible AD: TBD

> (3) Briefly describe the review of this document that was performed
> by the Document Shepherd. If this version of the document is not
> ready for publication, please explain why the document is being
> forwarded to the IESG.

The document shepherd has reviewed the document in detail, which led
to a number of minor changes in the document, and is also responsible
for one of the proof-of-concept implementations.

> (4) Does the document Shepherd have any concerns about the depth or
> breadth of the reviews that have been performed?

No.  The document has been reviewed by participants from both the
name and number communities.

> (5) Do portions of the document need review from a particular or
> from broader perspective, e.g., security, operational complexity,
> AAA, DNS, DHCP, XML, or internationalization? If so, describe the
> review that took place.

N/A

> (6) Describe any specific concerns or issues that the Document
> Shepherd has with this document that the Responsible Area Director
> and/or the IESG should be aware of? For example, perhaps he or she
> is uncomfortable with certain parts of the document, or has concerns
> whether there really is a need for it. In any event, if the WG has
> discussed those issues and has indicated that it still wishes to
> advance the document, detail those concerns here.

N/A

> (7) Has each author confirmed that any and all appropriate IPR
> disclosures required for full conformance with the provisions of BCP
> 78 and BCP 79 have already been filed. If not, explain why?

The document authors have all confirmed they know of no needed
IPR disclosures.

> (8) Has an IPR disclosure been filed that references this document?
> If so, summarize any WG discussion and conclusion regarding the IPR
> disclosures.

N/A

> (9) How solid is the WG consensus behind this document? Does it
> represent the strong concurrence of a few individuals, with others
> being silent, or does the WG as a whole understand and agree with
> it?

It is more the former than the latter, but there was good support for
adoption, and no concerns have been raised by those who were
originally supportive.

> (10) Has anyone threatened an appeal or otherwise indicated extreme
> discontent? If so, please summarise the areas of conflict in
> separate email messages to the Responsible Area Director. (It should
> be in a separate email because this questionnaire is publicly
> available.)

N/A

> (11) Identify any ID nits the Document Shepherd has found in this
> document. (See http://www.ietf.org/tools/idnits/ and the
> Internet-Drafts Checklist). Boilerplate checks are not enough; this
> check needs to be thorough.

The idnits tool only reported false positives (e.g. due to RFC 8605
being listed as a normative reference, but the text not citing it in
the expected form).

> (12) Describe how the document meets any required formal review
> criteria, such as the MIB Doctor, YANG Doctor, media type, and URI
> type reviews.

N/A

> (13) Have all references within this document been identified as
> either normative or informative?

Yes.

> (14) Are there normative references to documents that are not ready
> for advancement or are otherwise in an unclear state? If such
> normative references exist, what is the plan for their completion?

The document depends on the 'JSON Path' specification
(http://goessner.net/articles/JsonPath/) normatively, in the sense
that JSON Paths are used in protocol responses.  However, since the
JSON Path specification does not meet the requirements for being
included as a normative reference, the document has XPath as a
normative reference (of which the JSON Path specification is an
adaptation) and the JSON Path specification as an informative
reference.

> (15) Are there downward normative references references (see RFC
> 3967)? If so, list these downward references to support the Area
> Director in the Last Call procedure.

N/A

> (16) Will publication of this document change the status of any
> existing RFCs? Are those RFCs listed on the title page header,
> listed in the abstract, and discussed in the introduction? If the
> RFCs are not listed in the Abstract and Introduction, explain why,
> and point to the part of the document where the relationship of this
> document to the other RFCs is discussed. If this information is not
> in the document, explain why the WG considers it unnecessary.

N/A

> (17) Describe the Document Shepherd's review of the IANA
> considerations section, especially with regard to its consistency
> with the body of the document. Confirm that all protocol extensions
> that the document makes are associated with the appropriate
> reservations in IANA registries. Confirm that any referenced IANA
> registries have been clearly identified. Confirm that newly created
> IANA registries include a detailed specification of the initial
> contents for the registry, that allocations procedures for future
> registrations are defined, and a reasonable name for the new
> registry has been suggested (see RFC 8126).

The document requests that two additional entries ('sorting' and
'paging') be added to the IANA RDAP Extensions Registry.  The requests
are consistent with the use of those values in the document.

> (18) List any new IANA registries that require Expert Review for
> future allocations. Provide any public guidance that the IESG would
> find useful in selecting the IANA Experts for these new registries.

N/A

> (19) Describe reviews and automated checks performed by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, YANG
> modules, etc.

The document contains ABNF rules, JSON documents, and JSON Path
strings.  The ABNR rules were validated with
https://tools.ietf.org/tools/bap/abnf.cgi.  The JSON documents were
validated using Perl's JSON::XS.  The JSON Path strings were validated
against the Goessner JS implementation and the Jayway Java
implementation (see https://jsonpath.herokuapp.com/).

> (20) If the document contains a YANG module, has the module been
> checked with any of the recommended validation tools
> (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax
> and formatting validation? If there are any resulting errors or
> warnings, what is the justification for not fixing them at this
> time? Does the YANG module comply with the Network Management
> Datastore Architecture (NMDA) as specified in RFC8342?

N/A

> As required by RFC 4858, this is the current template for the Document
> Shepherd Write-Up. Changes are expected over time.
>
> This version is dated 1 November 2019.
>
> (1) What type of RFC is being requested (BCP, Proposed Standard,
> Internet Standard, Informational, Experimental, or Historic)? Why is
> this the proper type of RFC? Is this type of RFC indicated in the
> title page header?

The type of RFC being requested is Proposed Standard, because the
document defines extensions to the existing RDAP protocol.  The type
is indicated in the title page header.

> (2) The IESG approval announcement includes a Document Announcement
> Write-Up. Please provide such a Document Announcement Write-Up.
> Recent examples can be found in the "Action" announcements for
> approved documents. The approval announcement contains the following
> sections:

Technical Summary:

    This document describes RDAP query extensions that allow clients
    to specify their preferences for sorting and paging result sets.
    This helps clients to find relevant results more easily, as well
    as improving server response times and reducing bandwidth
    requirements.

Working Group Summary:

    This document was posted to the WG back in mid-2017, and has been
    presented at IETF 100 and 103-106, as well as at the Registration
    Operations Workshop (#6).  There was nothing unusual process-wise,
    and no issues with consensus or similar.

Document Quality:

    There are two proof-of-concept implementations, and there were
    a number of reviews from within the group.  No expert review was
    required.

Personnel:

    Document Shepherd: Tom Harrison
    Responsible AD: TBD

> (3) Briefly describe the review of this document that was performed
> by the Document Shepherd. If this version of the document is not
> ready for publication, please explain why the document is being
> forwarded to the IESG.

The document shepherd has reviewed the document in detail, which led
to a number of minor changes in the document, and is also responsible
for one of the proof-of-concept implementations.

> (4) Does the document Shepherd have any concerns about the depth or
> breadth of the reviews that have been performed?

No.  The document has been reviewed by participants from both the
name and number communities.

> (5) Do portions of the document need review from a particular or
> from broader perspective, e.g., security, operational complexity,
> AAA, DNS, DHCP, XML, or internationalization? If so, describe the
> review that took place.

There is no need for a broader review.

> (6) Describe any specific concerns or issues that the Document
> Shepherd has with this document that the Responsible Area Director
> and/or the IESG should be aware of? For example, perhaps he or she
> is uncomfortable with certain parts of the document, or has concerns
> whether there really is a need for it. In any event, if the WG has
> discussed those issues and has indicated that it still wishes to
> advance the document, detail those concerns here.

The document shepherd has no concerns.

> (7) Has each author confirmed that any and all appropriate IPR
> disclosures required for full conformance with the provisions of BCP
> 78 and BCP 79 have already been filed. If not, explain why?

The document authors have all confirmed they know of no needed
IPR disclosures.

> (8) Has an IPR disclosure been filed that references this document?
> If so, summarize any WG discussion and conclusion regarding the IPR
> disclosures.

There is no IPR disclosure filed for this document.

> (9) How solid is the WG consensus behind this document? Does it
> represent the strong concurrence of a few individuals, with others
> being silent, or does the WG as a whole understand and agree with
> it?

It is more the former than the latter, but there was good support for
adoption, and no concerns have been raised by those who were
originally supportive.

> (10) Has anyone threatened an appeal or otherwise indicated extreme
> discontent? If so, please summarise the areas of conflict in
> separate email messages to the Responsible Area Director. (It should
> be in a separate email because this questionnaire is publicly
> available.)

There has been neither threat of an appeal nor extreme discontent.

> (11) Identify any ID nits the Document Shepherd has found in this
> document. (See http://www.ietf.org/tools/idnits/ and the
> Internet-Drafts Checklist). Boilerplate checks are not enough; this
> check needs to be thorough.

The idnits tool only reported false positives (e.g. due to RFC 8605
being listed as a normative reference, but the text not citing it in
the expected form).

> (12) Describe how the document meets any required formal review
> criteria, such as the MIB Doctor, YANG Doctor, media type, and URI
> type reviews.

The document has no content that requires formal review.

> (13) Have all references within this document been identified as
> either normative or informative?

Yes.

> (14) Are there normative references to documents that are not ready
> for advancement or are otherwise in an unclear state? If such
> normative references exist, what is the plan for their completion?

The document depends on the 'JSON Path' specification
(http://goessner.net/articles/JsonPath/) normatively, in the sense
that JSON Paths are used in protocol responses.  However, since the
JSON Path specification does not meet the requirements for being
included as a normative reference, the document has XPath as a
normative reference (of which the JSON Path specification is an
adaptation) and the JSON Path specification as an informative
reference.

> (15) Are there downward normative references references (see RFC
> 3967)? If so, list these downward references to support the Area
> Director in the Last Call procedure.

There are no downward normative references in the document.

> (16) Will publication of this document change the status of any
> existing RFCs? Are those RFCs listed on the title page header,
> listed in the abstract, and discussed in the introduction? If the
> RFCs are not listed in the Abstract and Introduction, explain why,
> and point to the part of the document where the relationship of this
> document to the other RFCs is discussed. If this information is not
> in the document, explain why the WG considers it unnecessary.

This document does not change the status of any existing RFCs.

> (17) Describe the Document Shepherd's review of the IANA
> considerations section, especially with regard to its consistency
> with the body of the document. Confirm that all protocol extensions
> that the document makes are associated with the appropriate
> reservations in IANA registries. Confirm that any referenced IANA
> registries have been clearly identified. Confirm that newly created
> IANA registries include a detailed specification of the initial
> contents for the registry, that allocations procedures for future
> registrations are defined, and a reasonable name for the new
> registry has been suggested (see RFC 8126).

The document requests that two additional entries ('sorting' and
'paging') be added to the IANA RDAP Extensions Registry.  The requests
are consistent with the use of those values in the document.

> (18) List any new IANA registries that require Expert Review for
> future allocations. Provide any public guidance that the IESG would
> find useful in selecting the IANA Experts for these new registries.

The document does not define any new IANA registries.

> (19) Describe reviews and automated checks performed by the Document
> Shepherd to validate sections of the document written in a formal
> language, such as XML code, BNF rules, MIB definitions, YANG
> modules, etc.

The document contains ABNF rules, JSON documents, and JSON Path
strings.  The ABNR rules were validated with
https://tools.ietf.org/tools/bap/abnf.cgi.  The JSON documents were
validated using Perl's JSON::XS.  The JSON Path strings were validated
against the Goessner JS implementation and the Jayway Java
implementation (see https://jsonpath.herokuapp.com/).

> (20) If the document contains a YANG module, has the module been
> checked with any of the recommended validation tools
> (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax
> and formatting validation? If there are any resulting errors or
> warnings, what is the justification for not fixing them at this
> time? Does the YANG module comply with the Network Management
> Datastore Architecture (NMDA) as specified in RFC8342?

The document does not contain any YANG modules.