Subject: [regext] AD review of draft-ietf-regext-rdap-sorting-and-paging-14

From: Barry Leiba <[email-masked]>
Date: Fri, 24 Jul 2020 15:27:50 -0400

As with partial-response, I really appreciate the recent editorial work on
this document:  Version -14 is easy to read and mostly clear, and it’s
almost ready for last call.  I have some review comments below; most are
minor, but the ones about Section 2.3 and Table 2 need to be addressed
before last call.  I’ll put this into “revised I-D needed” state, and
please let me know if you have questions or disagreement with my comments
below.

— Section 1 —

   operators for counting, sorting and paging rows are currently
   supported by the major RDBMSs.

You use “RDBMSs” here and in Section 4, and it’s not a central term to the
document, but it should be expanded at least on first use.  I suggest
simply using “relational database management systems” in both places, and
avoiding the abbreviation and having to explain it.

— Section 1.1 —
Please use the exact BCP 14 boilerplate from RFC 8174.

— Section 2.1 —

   Such information is collected in two OPTIONAL response
   elements named, respectively, "sorting_metadata" and
   "paging_metadata".

Please remove “, respectively,” as it’s misused: there’s nothing to match
the two names up with, so no reason to use “respectively”.

   o  "totalCount": "Numeric" (OPTIONAL) a numeric value representing
      the total number of objects found.  It MUST be provided if the
      query string contains the "count" parameter;

Section 2.2 says also that it MUST NOT be provided otherwise, and I suggest
adding that here as well: ‘It MUST be provided if the query string contains
the "count" parameter, and MUST NOT be provided otherwise;’, or perhaps ‘It
MUST be provided if and only if the query string contains the "count"
parameter;’.  I also wonder whether the same thing is true for pageSize and
pageNumber.

      This property is redundant for 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;

But a web browser is a client too.  I suggest “redundant for some clients”;
what do you think?  I also suggest a comma before “but”, to break the long
sentence up a little.

— Section 2.3 —

   If IP
   addresses are represented as JSON strings, they MUST be sorted based
   on their numeric conversion.

I think most people will understand this, but I also think it’s not clearly
specified.  What does the “numeric conversion” of, say, 10.0.0.9 mean?  How
does “their numeric conversion” explain that 8.8.8.8 sorts lower than
10.0.0.9 ?  And I think it’s yet more complicated with v6 addresses.  I’d
like to see a *little* clearer explanation of what you mean, even though I
know what you mean and even though I think most readers will.  I want to
make sure that all readers will.

— Section 2.3.1 —

   identifies the root of the document (DOM).

Use your judgment on this one, because I’m not sure what the right approach
is: “document (DOM)” isn’t really right, but “document object model (DOM)”
feels unnecessary and awkward.  Consider this comment and let me know what
you think is best (including leaving it as it is, or perhaps just removing
“(DOM)”).

   (e.g. links, notices, remarks, etc.)

Nit: Here and elsewhere: “e.g.” and “etc.” together is redundant... you
shouldn’t have both.  I suggest leaving the former and removing the
latter.  Also, “e.g.” needs a comma after it, so: “(e.g., links, notices,
remarks)”.

In the first and second columns of Table 1, it is really awkward to have
the words “searchable”, “nameserver”, and “properties” split between two
lines.  I think you can manage it if you make the last column one character
narrower.  Also, why are there trailing “.” in column 4?

Table 2, in contrast, is extremely hard to read, because everything is
broken up onto multiple lines.  It’s visual chaos.  Clearly, there’s no way
to make the table work otherwise, so maybe it’s better to come up with a
different way to present the information, probably using an xml2rfc list
structure instead?

— Section 5 —
Please change the contact to “IETF” instead of “IESG”.

—
Barry

---

From: Mario Loffredo <[email-masked]>
Date: Tue, 28 Jul 2020 13:48:57 +0200

Hi Barry,

thanks a lot for your review and feedback. I provide my responses to 
your feedback below.

Il 24/07/2020 21:27, Barry Leiba ha scritto:
> As with partial-response, I really appreciate the recent editorial 
> work on this document:  Version -14 is easy to read and mostly clear, 
> and it’s almost ready for last call.  I have some review comments 
> below; most are minor, but the ones about Section 2.3 and Table 2 need 
> to be addressed before last call.  I’ll put this into “revised I-D 
> needed” state, and please let me know if you have questions or 
> disagreement with my comments below.
>
> — Section 1 —
>
> You use “RDBMSs” here and in Section 4, and it’s not a central term to 
> the document, but it should be expanded at least on first use.  I 
> suggest simply using “relational database management systems” in both 
> places, and avoiding the abbreviation and having to explain it.
>
[ML] No problem.
> Please use the exact BCP 14 boilerplate from RFC 8174.
[ML] OK.
> Please remove “, respectively,” as it’s misused: there’s nothing to 
> match the two names up with, so no reason to use “respectively”.
[ML] OK.
> Section 2.2 says also that it MUST NOT be provided otherwise, and I 
> suggest adding that here as well: ‘It MUST be provided if the query 
> string contains the "count" parameter, and MUST NOT be provided 
> otherwise;’, or perhaps ‘It MUST be provided if and only if the query 
> string contains the "count" parameter;’.  I also wonder whether the 
> same thing is true for pageSize and pageNumber.
[ML] Opted for "if and only if". The same doen't work for for pageSize 
and pageNumber because thy are provided depending on the comparison 
between the maximum number of results returned in a  page and the total 
number of objects found.
> But a web browser is a client too.  I suggest “redundant for some 
> clients”; what do you think?  I also suggest a comma before “but”, to 
> break the long sentence up a little.
[ML] I propose "RDAP clients". Is it okay?
> I think most people will understand this, but I also think it’s not 
> clearly specified.  What does the “numeric conversion” of, say, 
> 10.0.0.9 mean?  How does “their numeric conversion” explain that 
> 8.8.8.8 sorts lower than 10.0.0.9 ? And I think it’s yet more 
> complicated with v6 addresses.  I’d like to see a *little* clearer 
> explanation of what you mean, even though I know what you mean and 
> even though I think most readers will.  I want to make sure that all 
> readers will.

[ML] Agreed. Could it be fine something like in the following?

The conversion of an IPv4 address to a number is possible since each 
dotted format IPv4 address is a representation of a number written in a 
256-based manner: 192.168.0.1 means 1*256^0 + 0*256^1 + 168*256^2 + 
192*256^3 = 3232235521.  Similarly,  an IPv6 address can be converted 
into a number by applying the base 65536. Therefore, the numerical 
representation of the IPv6 address 
2001:0db8:85a3:0000:0000:8a2e:0370:7334 is 
42540766452641154071740215577757643572.   Builtin functions and 
libraries for converting IP addresses into numbers are available in most 
known programming languages and relational database management systems.

>
> — Section 2.3.1 —
>
>    identifies the root of the document (DOM)..
>
> Use your judgment on this one, because I’m not sure what the right 
> approach is: “document (DOM)” isn’t really right, but “document object 
> model (DOM)” feels unnecessary and awkward.  Consider this comment and 
> let me know what you think is best (including leaving it as it is, or 
> perhaps just removing “(DOM)”).
[ML] I would opt for "document object model (DOM)"
> Nit: Here and elsewhere: “e.g.” and “etc.” together is redundant... 
> you shouldn’t have both.  I suggest leaving the former and removing 
> the latter.  Also, “e.g.” needs a comma after it, so: “(e.g., links, 
> notices, remarks)”.
>
[ML} OK.
> In the first and second columns of Table 1, it is really awkward to 
> have the words “searchable”, “nameserver”, and “properties” split 
> between two lines.  I think you can manage it if you make the last 
> column one character narrower.  Also, why are there trailing “.” in 
> column 4?
>
[ML] Removed the trailing dots and made the layout more readable by 
splitting "unicodeName/ldhName"

> broken up onto multiple lines.  It’s visual chaos.  Clearly, there’s 
> no way to make the table work otherwise, so maybe it’s better to come 
> up with a different way to present the information, probably using an 
> xml2rfc list structure instead?
[ML] OK. I rearrange the table as a list.
> Please change the contact to “IETF” instead of “IESG”.

[ML] OK.

Hope to publish the new version in a couple of days, after your reply to 
my questions anyway.

Best,

Mario

>
> —
> Barry
>
> _______________________________________________
> regext mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/regext

-- 
Dr. Mario Loffredo
Systems and Technological Development Unit
Institute of Informatics and Telematics (IIT)
National Research Council (CNR)
via G. Moruzzi 1, I-56124 PISA, Italy
Phone: +39.0503153497
Mobile: +39.3462122240
Web: http://www.iit.cnr.it/mario.loffredo

---

From: Barry Leiba <[email-masked]>
Date: Tue, 28 Jul 2020 09:11:31 -0400

Hi, Mario; thanks for the response.  I've eliminated, below, the
comments that I consider addressed.

> between the maximum number of results returned in a  page and the total

Right, but I think you misunderstood what I meant by "the same".
Clearly, pageSize and pageNumber aren't controlled by the "count"
parameter.  What I meant was whether it's also true that pageSize and
pageNumber are also provided on an "if and only if" basis: if and only
if the total number of objects found exceeds the page size.

> But a web browser is a client too.  I suggest “redundant for some clients”; what do you think?
>

It's kind of okay, but... when a web browser is doing RDAP, isn't it
also an RDAP client?  I think what you're really referring to is
purpose-built RDAP clients, which will likely have been coded to more
completely understand the full RDAP.  I'm not sure what the best way
to refer to those is, and calling them "RDAP clients" might be fine,
and the right answer.  I think people will understand what you mean.
Let's go with that, and see if there are any comments about it during
last call or from the IESG.  I think it will be okay.

Barry

---

From: Mario Loffredo <[email-masked]>
Date: Tue, 28 Jul 2020 16:31:26 +0200

Hi Barry,

> if the total number of objects found exceeds the page size.
I apologize. Yes, that's true. I'll update the doc accordingly.
> also an RDAP client?

[ML] Yes but in that case for a human it is very ugly both to count the 
number of results returned in the page and to remember the number of the 
current page. The goal here is to avoid that a human using simply a web 
browser feels disoriented in the result set.

On the contrary, a non-human user, I mean a software agent acting as an 
RDAP client, can easily find or caluclate both of them. In that sense, 
they might be considered redundant by an implementer of an RDAP client.

> I think what you're really referring to is

[ML] OK.

Cheers,

Mario