Subject: [webfinger] AD review of draft-ietf-appsawg-webfinger-10

From: Barry Leiba <[email-masked]>
Date: Mon, 4 Mar 2013 14:42:21 -0500

This document's in good shape, and is really good work.  Thanks, everyone.

I have a bunch of comments, but only one of them is significant... the
rest are quite minor.  None of them will block last call, so after I
send this I'm going to request the last call.

Document editors: please respond as appropriate to my comments, and
then on next Monday, when I-D submissions are open again, post an -11
version with whatever updates you have at that point.

---------------------------------------------
One significant issue:

In Section 4.3:
   In the event that a client requests link relation types that are not
   defined for the specified "resource", a resource descriptor MUST be
   returned.  In the returned JRD, the "links" array MAY be absent,
   empty, or contain only links that did match a provided "rel" value.

I don't understand what this is trying to tell me to do, if I'm
implementing a WebFinger resource and I get inappropriate "rel"
values.  I'm guessing that this is what you want, but this text
doesn't make that clear at all:

1. Ignore all "rel" values that contain link relation types that are
not defined for the specified resource.
2. If there are other "rel" values left, filter on them as though they
were the only ones present.
3. If there are *no* other "rel" values left, do *not* return an
unfiltered JRD.  Instead, either:
3a. ...return a JRD with an empty "links" array ("links" : [ ]), or
3b. ...return a JRD with no "links" array present at all.

Is there a reason to allow both 3a and 3b, rather than specifying one
or the other?

In any case, please re-word this paragraph so it says clearly what you
want it to say.

---------------------------------------------
Other minor comments:

In the last paragraph of Section 3.2, you have "OPTIONAL".  The 2119
keyword is out of place in this non-normative example.  Besides: it's
not optional; it's a "SHOULD support".  So, really, change "is
OPTIONAL" to "is not guaranteed".

In the first paragraph of Section 4, to be consistent with how you
render things later, you should probably make these changes (and then
make sure your use of this is consistent throughout the document):

   using the HTTPS scheme => using the "https" scheme

   other URI scheme (such as HTTP) ==> other URI scheme (such as "http")

In Section 4:
   GET requests to a WebFinger resource convey the URI to perform the
   query upon in the URI's query string; see Section 4.1 for details.

First, I find this to be an awkward, with two different URIs not
clearly differentiated.  Second, Section 4.1 doesn't actually give
details of the "URI to perform the query upon".  Maybe this?:

NEW
   A WebFinger resource is always given a query target, which is
   another URI that identifies the entity whose information is
   sought.  GET requests to a WebFinger resource convey the query
   target in the "resource" parameter in the WebFinger URI's query
   string; see Section 4.1 for details.
END

In Section 4.1:
   First, each parameter value is percent-encoded, as
   per Section 2.1 of RFC 3986, so that it conforms to the query
   production in Section 3.4 of that specification, and additionally any
   instances of the "=" and "&" characters are also percent-encoded.

I think this would be a bit clearer this way:

NEW
   First, each parameter value is percent-encoded, as
   per Section 2.1 of RFC 3986.  The encoding is done to conform to
   the query production in Section 3.4 of that specification, with the
   addition that any instances of the "=" and "&" characters within the
   parameter value are also percent-encoded.
END

I think that will avoid anyone's trying to encode the "=" in
"resource=", and the like.

   The order in which the client places each
   attribute-and-value pair within the query component is unspecified.

Is that really trying to say that the order has to be treated as
insignificant when the query component is interpreted?  If so, it
should say it that way:

NEW
   The order in which the client places each
   attribute-and-value pair within the query component does not matter
   in the interpretation of the query component.
END

In Section 4.2:
   The client MAY include the "Accept"
   header to indicate a desired representation, though no other
   representation than JRD is defined in this specification.

I think I might prefer this:

NEW
   The client MAY include the "Accept"
   header to indicate a desired representation; representations
   other than JRD might be defined in future specifications.  The
   WebFinger resource MUST silently ignore any requested
   representations that it does not understand and support.
END

   A WebFinger resource MAY redirect the client, but MUST only redirect
   the client to an HTTPS URI.

I don't think this will actually be misinterpreted, but just to be
clear about the MAY/MUST thing:

NEW
   A WebFinger resource MAY redirect the client; if it does, the
   redirection MUST only be to an "https" URI.
END

In Section 4.3:
   When the "rel" parameter is used, only the link relations
   that match the link relations provided via the "rel" parameter are
   included in the array of links returned in the JRD.

Not when it's *used* -- it can be used, but the resource might not
support it, right?  So:

NEW
   When the "rel" parameter is used and accepted, only the link
   relations that match the link relations provided via the "rel"
   parameter are included in the array of links returned in the JRD.
END

   The "rel" parameter MAY be transmitted to the WebFinger resource
   multiple times in order to request multiple types of link relations.

Does this really mean this?:

NEW
   The "rel" parameter MAY be included in the query component of the
   WebFinger URI multiple times in order to request multiple types of
   link relations.
END

Actually, I think "in the query component of the WebFinger URI" can be
removed, to just say, "MAY be included multiple times".

In Section 4.4, you've hit a pedantic pet peeve of mine that's a lost
cause that I still fight:

   a JSON object that is comprised of the following

Correctly, the whole "comprises" the parts (or "is composed of", but
not "is comprised of").

NEW
   a JSON object that comprises the following
END

And similarly in the following paragraph and in Sections 4.4.3,
4.4.4.4, and 4.4.4.5.

In Section 4.5:
   WebFinger requests can include a "resource" parameter (see Section
   4.1) specifying the URI of an account, device, or other entity.

Not "can include"; they do include it: Section 4.2 says that the
'query component MUST include the "resource" parameter exactly once'.

   To perform a WebFinger lookup on an account specific to the host
   being queried, use of the "acct" URI scheme is RECOMMENDED, since it
   explicitly identifies an account accessible via WebFinger.

I'm racking my brain, trying to decide whether this is an appropriate
2119 "RECOMMENDED", which means "SHOULD", which means that there's an
interoperability reason why you must do this unless you fully
understand the consequences of not doing it.

If what you're saying is that "acct" is always guaranteed to work,
while others, such as "mailto" are crap shoots, then I think
"RECOMMENDED" is OK.  But if they all might or might not work, and
we're just saying that "acct" was made for this and we're encouraging
its use and it's the best of the bunch, then that's not a 2119
"RECOMMENDED".

So can you clarify this for me (in email; don't change the text yet)?

In Section 6:
   As with all web resources, access to the WebFinger resource MAY
   require authentication.  Further, failure to provide required
   credentials MAY result in the server forbidding access or providing a
   different response than had the client authenticated with the server.

Neither of these "MAY"s is an appropriate 2119 key word.  "MAY" means
"this is a completely optional choice".  The WebFinger resource will
either require authentication or it won't, but that's not a MAY sort
of choice for anyone.  Make both of them "may", or perhaps "might" or
"could".

Just as a contrast, the MAY in the second paragraph is fine, because
it really is describing a choice that the resource can make, at its
option.

In the third paragraph, it's less clear.  Given the example you use,
I'd remove the "MAY".  But I'm not going to beat you with truncheons
about that one.

In Section 8:
On the two paragraphs about private/personal information, I suggest
explicitly passing that by Alissa Cooper for review and comment, if
you haven't already.

Section 9.1:
It would be good to explicitly request review on the
<[email-masked]> mailing list now.  That could save
time for the formality later.

---------------------------------------------

---

From: "Paul E. Jones" <[email-masked]>
Date: Mon, 4 Mar 2013 23:17:07 -0500

Barry,

> Document editors: please respond as appropriate to my comments, and then
> on next Monday, when I-D submissions are open again, post an -11 version
> with whatever updates you have at that point.

OK.  I'll reply below and make edits as requested.
 
> values.  I'm guessing that this is what you want, but this text doesn't
> make that clear at all:
> 
> 1. Ignore all "rel" values that contain link relation types that are not
> defined for the specified resource.
> Is there a reason to allow both 3a and 3b, rather than specifying one or
> the other?
> 

Your interpretation is correct.  The reason for allowing either an empty
array or a JRD with the links array absent is that there is no semantic
difference.  If we say that the array must be absent, someone may still
return an empty array.  Likewise, if we say the array must be empty, someone
might still leave it out entirely.  I can appreciate how this might happen
based on how the serialization routines are written.  I have no strong
preference one way or the other, but I'd prefer to treat absent/empty as
equal and expect either.

Considering the specific paragraph in question, the previous text explains
how the server filters the request with respect to the "rel" parameter.

So, what I would propose to modify the first paragraph of 4.3 as shown
(taking the above and below comments into account):

    When issuing a request to a WebFinger resource, the client MAY
    utilize the "rel" parameter to request only a subset of the
    information that would otherwise be returned without the "rel"
    parameter.  When the "rel" parameter is used and accepted, only
    the link relation types that match the link relation types
    provided via the "rel" parameter are included in the array of
    links returned in the JRD.  If there are no matching link
    relation types defined for the resource, the "links" array in
    the JRD will either be absent or empty.  All other information
    present in a resource descriptor remains present, even when
    "rel" is employed.

Then I propose to delete the last paragraph of 4.3 entirely.

> not optional; it's a "SHOULD support".  So, really, change "is OPTIONAL"
> to "is not guaranteed".

Done.
 
> First, I find this to be an awkward, with two different URIs not clearly
> differentiated.  Second, Section 4.1 doesn't actually give details of
> the "URI to perform the query upon".  Maybe this?:
> 
> NEW

That works for me.
 
>    parameter value are also percent-encoded.

OK
 
> I think that will avoid anyone's trying to encode the "=" in "resource=",
> and the like.
> 
> insignificant when the query component is interpreted?  If so, it should
> say it that way:
> 
> NEW

Correct interpretation.  Changed.
 
>    representations that it does not understand and support.

Done.
 
> I don't think this will actually be misinterpreted, but just to be clear
> about the MAY/MUST thing:
> 
> NEW

Done.
 
>    parameter are included in the array of links returned in the JRD.

Done, and also modified as discussed above.

> removed, to just say, "MAY be included multiple times".

Done.  To be clearer, I suggest switching moving types to the end as:

    The "rel" parameter MAY be included multiple times in order to request
    multiple link relation types.

> Correctly, the whole "comprises" the parts (or "is composed of", but not
> "is comprised of").
> 
> NEW
>    a JSON object that comprises the following END

Done.

> And similarly in the following paragraph and in Sections 4.4.3, 4.4.4.4,
> and 4.4.4.5.

Done.
 
> Not "can include"; they do include it: Section 4.2 says that the 'query
> component MUST include the "resource" parameter exactly once'.

Indeed.  Removed "can".
 
> interoperability reason why you must do this unless you fully understand
> the consequences of not doing it.
> 
> If what you're saying is that "acct" is always guaranteed to work, while
> others, such as "mailto" are crap shoots, then I think "RECOMMENDED" is
> OK.  But if they all might or might not work, and we're just saying that
> "acct" was made for this and we're encouraging its use and it's the best
> of the bunch, then that's not a 2119 "RECOMMENDED".
> 

The use of the word RECOMMENDED was to encourage, but not mandate, use of
the acct URI scheme when querying for information about a user's account.
Personally, I would be OK with mandating use of "acct" when querying for
information about a user's account, but I think we all agree that using
"mailto" or any other scheme is acceptable depending on the nature of the
information sought.  For example, if I want to find out information about
one's email service, then "mailto" might be the appropriate URI to use.

I'll revise according to your next instructions.
 
> either require authentication or it won't, but that's not a MAY sort of
> choice for anyone.  Make both of them "may", or perhaps "might" or
> "could".

Done.
 
> Just as a contrast, the MAY in the second paragraph is fine, because it
> really is describing a choice that the resource can make, at its option.
> 
> In the third paragraph, it's less clear.  Given the example you use, I'd
> remove the "MAY".  But I'm not going to beat you with truncheons about
> that one.

Changed to "might".
 
> explicitly passing that by Alissa Cooper for review and comment, if you
> haven't already.

OK, I will do that.
 
> Section 9.1:
> It would be good to explicitly request review on the <wellknown-uri-
> [email-masked]> mailing list now.  That could save time for the
> formality later.

I'll send an email to request a review.

Thanks,
Paul

---

From: Barry Leiba <[email-masked]>
Date: Tue, 5 Mar 2013 08:31:07 -0500

Thanks for the quick response, Paul.  Summary: everything looks good here.

> preference one way or the other, but I'd prefer to treat absent/empty as

Ack; that's fine, and thanks for the explanation.

>>    explicitly identifies an account accessible via WebFinger.
...
>> of the bunch, then that's not a 2119 "RECOMMENDED".
...
> one's email service, then "mailto" might be the appropriate URI to use.

Why not change "RECOMMENDED" to "strongly encouraged", then?  (Or I
gather you mean to make it "recommended", which will be fine as well.)

Barry

---

From: "Paul E. Jones" <[email-masked]>
Date: Wed, 6 Mar 2013 02:34:19 -0500

Barry,

> Thanks for the quick response, Paul.  Summary: everything looks good

Great!
 
> > The use of the word RECOMMENDED was to encourage, but not mandate, use
> > of the acct URI scheme when querying for information about a user's
> account.
> > Personally, I would be OK with mandating use of "acct" when querying
> > for information about a user's account, but I think we all agree that
> > using "mailto" or any other scheme is acceptable depending on the
> > nature of the information sought.  For example, if I want to find out
> > information about one's email service, then "mailto" might be the
> appropriate URI to use.
> 

I'll got with lowercase.

Paul