Re: [regext] Benjamin Kaduk's Discuss on draft-ietf-regext-rdap-partial-response-13: (with DISCUSS and COMMENT)

[Benjamin Kaduk <[e-mail]>]

Hi Mario,

Also inline.

On Fri, Sep 11, 2020 at 01:11:03PM +0200, Mario Loffredo wrote:
> Hi Benjamin,
> 
> thanks a lot for your extensive review. Please fidn my comments inline.
> 
> Il 09/09/2020 20:47, Benjamin Kaduk via Datatracker ha scritto:
> > Benjamin Kaduk has entered the following ballot position for
> > draft-ietf-regext-rdap-partial-response-13: Discuss
> >
> > When responding, please keep the subject line intact and reply to all
> > email addresses included in the To and CC lines. (Feel free to cut this
> > introductory paragraph, however.)
> >
> >
> > Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
> > for more information about IESG DISCUSS and COMMENT positions.
> >
> >
> > The document, along with other ballot positions, can be found here:
> > https://datatracker.ietf.org/doc/draft-ietf-regext-rdap-partial-response/
> >
> >
> >
> > ----------------------------------------------------------------------
> > DISCUSS:
> > ----------------------------------------------------------------------
> >
> > As was the case for Murray, I'm unconvinced that I have understood what
> > Section 3 intended to convey.  However, I am balloting Discuss because
> > my current best understanding is for a statement that seems inconsistent
> > with my understanding of how the partial response mechanism works.  In
> > particular, how would the topmost objects be returned according to
> > different field sets, if there's only a single query parameter and (I
> > assume) all topmost objects are the results of the same single query?
> >
> >
> > ----------------------------------------------------------------------
> > COMMENT:
> > ----------------------------------------------------------------------
> >
> > Thanks to the shepherd for noting that the examples have been through
> > JSONLint!
> >
> > Abstract
> >
> >     The Registration Data Access Protocol (RDAP) does not include
> >     capabilities to request partial responses.  Servers will only return
> >     full responses that include all of the information that a client is
> >     authorized to receive.  A partial response capability that limits the
> >
> > [There is perhaps some stylistic question of whether to describe the
> > present state in the present tense vs. saying something like "prior to
> > the mechanism defined in this document" or "as specified in [RFC7483".]
> >
> > Section 1
> >
> >     Currently, RDAP does not provide a client with any way to request a
> >     partial response.  Servers can only provide the client with a full
> >
> > nit: will this age well?
> [ML] :-)
> >
> > Section 2
> >
> >     The path segment defined in this section is an OPTIONAL extension of
> >     search path segments defined in [RFC7482].  This document defines an
> >
> > It's not entirely clear to me in what sense it's accurate to say that
> > this section "defines" a path segment.  (Perhaps RDAP path segments
> > diverge from normal HTTP and generic URI path segments in this sense?)
> > My current understanding is that we are defining an optional query
> > parameter in the purest URI sense, which does not require a new path
> > segment in the URI sense.
> >
> >     full response (Figure 1).  The field sets supported by a server are
> >     usually described in out-of-band documents (e.g.  RDAP profile)
> >
> > nit: comma (and only one space) after "e.g.".
> [ML] There is only one space after "e.g." in the XML version. Anyway, 
> I'll put the comma.
> >
> > Section 2.1
> >
> >     responses about the available field sets.  Such information is
> >     collected in a new data structure named "subsetting_metadata"
> >     containing the following properties:
> >
> > I assume this is a JSON datastructure, specifically?
> [ML] OK. I'll specify "JSON data structure"
> >
> >     o  "availableFieldSets": "AvailableFieldSet[]" (OPTIONAL) an array of
> >        objects, with each element describing an available field set.
> >        Members are:
> >
> >        *  "name": "String" (REQUIRED) the field set name;
> >        *  "default": "Boolean" (REQUIRED) whether the field set is
> >           applied by default;
> >
> > Is it allowed to have more than one entry in the array set
> > "default":true?
> [ML] Obviously not. Should I furtherly explain that only one field set 
> must be applied by default? Isn't implicitly stated by the meaning of 
> "applied by default"?

I think it's probably worth saying what the error handling is if more than
one is set -- treat the whole thing as malformed, or pick one?

> >
> >        *  "links": "Link[]" (OPTIONAL) an array of links as described in
> >           [RFC8288] containing the query string that applies the field
> >           set.
> >
> > I suggest giving an example or a bit more detail as to exactly what
> > structure/format is expected here; 8288 has a fair bit of meat to it.
> > Ah, but this is covered in Section 2.1.2, so maybe just a
> > forward-reference is enough.
> [ML] I'll put the reference "(see Section 2.1.2)"

Thanks!

> > It would be good (either here or there) to
> > give some indication as to which of "value"/"rel"/"href"/"title"/"type"
> > are required/optional, though.
> 
> [ML] In Section 4.2 of RFC7483bis 
> <https://datatracker.ietf.org/doc/draft-ietf-regext-rfc7483bis/> is written:
> 
> The "value", "rel" and "href" JSON values MUST be specified.  All other
>     JSON values are OPTIONAL.
> 
> Could be enough to report the same text?

That would work, since presumably we don't want to make this document wait
until that one is done.

> >
> > Section 4
> >
> >     o  "id": the server provides only the key field: "handle" for
> >        entities, "ldhName" for domains and nameservers.  If a returned
> >        domain or nameserver is an Internationalized Domain Name (IDN)
> >        [RFC5890], then the "unicodeName" field MUST be included in the
> >
> > nit: I suggest "also" or "additionally be included".
> [ML] OK. I'll change it to "MUST additionally be included"
> >
> >     The "objectClassName" field is implicitly included in each of the
> >     above field sets.  RDAP providers SHOULD include a "self" link in
> >     each field set.  RDAP providers MAY also add any property providing
> >     service information.
> >
> > Just to check my understanding: the "property" that might also be added
> > here is a "field" that would be included in a given field set and
> > corresponding query response?  (I don't know if "property" has
> > RDAP-specific connotations that make it a better word to use here.)
> [ML] it is a required property as defined in Section 4.9 of RFC7483bis 
> <https://datatracker.ietf.org/doc/draft-ietf-regext-rfc7483bis/>

Sorry, I was trying to ask about "MAY also add any property providing
service information" -- specifically, about how that is conveyed in the
response.  (My assumption is just as a field of the topmost JSON object.)

> >
> > (nit?) I'm also not entirely sure that 'include a "self" link in each
> > field set' is pedantically correct, as opposed to 'include a "links"
> > field indicating the "self" link relationship'.
> [ML] OK.
> >
> > Section 8
> >
> > I suppose it's always possible that by using a narrow field set a client
> > would not get back some important piece of information, e.g., a modifier
> > that restricts the scope of applicability of some information.  It seems
> > fairly obvious that the onus for knowing what fields are possible and
> > avoiding this scenario falls on the client, though perhaps it is worth
> > also giving some guidance to the server to take this into consideration
> > while defining field sets.
> [ML] I'm convinced that the number and the content of the field sets 
> defined in an RDAP profile should be agreed between producers and 
> consumers. I expect that the field sets number and content will be the 
> result of a tuning process.

I agree.  I am wondering if we should give advice to the producer, pointing
out that if done badly, a "smaller" field set might omit critical
information and lead the consumer to behave in a dangerous or unexpected
way.

> >
> >     Servers can also define different result limits according to the
> >     available field sets, so a more flexible truncation strategy can be
> >
> > I'm not entirely sure I am understanding this correctly -- is it just
> > saying (roughly) "when using the 'id' field set it's safe to use much
> > larger page size than for the 'full' field set"?  (I didn't find a
> > specific definition of "result limits" in RFCs 7482 or 7483.)
> [ML] Yes, exactly. The value "result set truncated due to excessive 
> load" is presented among the values defined in Section 10.2.1 of RFC7483 
> for "Notice and remark Types". When a server returns such notice, it 
> means that server limits have been exceeded.

I see now; thanks for the pointer and explanation.

> >
> >     implemented.  The new query parameter presented in this document
> >     provides RDAP operators with a way to implement a server that reduces
> >     inefficiency risks.
> >
> > Perhaps it's worth mentioning that in the face of unupdated clients
> > these potential gains are not actually realized.
> 
> [ML] Could you furtherly explain this concept?

If the server implements partial responses, but all clients do not, the
server still has to spend resources producing full responses for all
clients.  The efficiency gains and risk reduction seem to be proportional
to the fraction of clients that support partial responses.

> >
> > Section 9.1
> >
> > The one place we cite RFC 7481 does not seem to itself be a normative
> > usage (though I can imagine that one does need to read it in order to
> > build a complete system).
> 
> [ML] Do you suggest to insert it among the "informative References"? I 
> think that even if it isn't essential to implement the proposed 
> capability, I believe it's needful to achieve a comprehensive 
> implementation that takes into account the relationship between the 
> availability and the content of each fiedl set and the user access profiles.
> 
> For this reason, I put it among the "Normative References"

Your reasoning seems sound; please leave it where it is.

> >
> > Appendix A
> >
> >     Looking at the implementation experiences of partial response, two
> >     approaches are observed:
> >
> > Looking at context from later in the suggestion suggests that this
> > survey was not restricted to RDAP partial response, which might be worth
> > mentioning.
> 
> [ML] OK. Could be enough to update the sentence as in the following?
> 
> "Looking at the implementation experiences of partial response offered 
> by data providers on the web,  two approaches are observed"

I think so; thanks.

> >
> >     o  The request of some fields might not match the client's access and
> >        authorization levels.  Clients might request unauthorized fields
> >        and servers should define a strategy for responding, such as
> >        always returning an error response or returning a response that
> >
> > nit: I think this is more of "servers have to" than "servers should"
> > (even though this strategy might just be "do whatever the existing code
> > happens to do").
> [ML] OK. I change that sentence as you suggest.
> >
> > Appendix A.1
> >
> >     o  Relevant entity object information is included in a jCard, but
> >        such information cannot be easily selected because it is split
> >        into the items of a jagged array;
> >
> > nit: I didn't find "jagged array" used in either RFC 7483 or RFC 7095;
> > is is relationship to jCard specified somewhere else?
> [ML] It is not a jCard specific term. It is a term generally used in the 
> programming languages to refer to an array of arrays of which the member 
> arrays can be of different sizes. The straightforward deserialization of 
> a jCard produces a jagged array.

I see, thanks.  (Can you tell I mostly only program in C?)

> >     The latter approach seems to facilitate RDAP interoperability.
> >     Servers can define basic field sets which, if known to clients, can
> >     increase the probability of obtaining a valid response.  The usage of
> >
> > nit: the "latter approach" seems to be an artifact of some text moves,
> > as there isn't a recent comparison of two approaches in this section.
> > ("Latter approach" also appears in the following paragraph.)
> [ML] I'll replace "latter approach" with "the field sets approach".
> 
> 
> Hope I forgot nothing.
> 
> Looking forward for your reply to my comments and proposed updates.

I appreciate your responses and updates; they look good to me.

Thanks!

-Ben