Subject: [webfinger] Fwd: [apps-discuss] WGLC feedback on webfinger-09

From: Gonzalo Salgueiro <[email-masked]>
Date: Tue, 5 Feb 2013 02:02:52 -0500

Posting to Webfinger list for visibility.

--G

Begin forwarded message:

> From: Mark Nottingham <[email-masked]>
> Subject: [apps-discuss] WGLC feedback on webfinger-09
> Date: February 5, 2013 1:58:02 AM EST
> To: "[email-masked] Discuss" <[email-masked]>
> 
> Had a quick read of this draft. Overall this looks pretty good; the points I raise are fairly minor.
> 
> 1) The introduction seems to be missing a vital bit of information: that the Whole Point -- the Big Trick -- that WebFinger performs is (AIUI) that you can use an identifier that might not be usable as a locator (e.g., a mailto: uri, an acct: uri) as a locator. In that sense, it's really just a more real-world-usable URN lookup facility*.
> 
> This is really important to include in the abstract as well as the introduction, because without it, WF just seems like a silly indirection mechanism on top of HTTP.
> 
> 2) The examples use unregistered link relations types <http://www.iana.org/assignments/link-relations/link-relations.xml>; specifically, "blog" and "vcard". Naughty.
> 
> 3) The text in section 4.1 isn't precise enough; consider the "=" and "&" characters, which are NOT required to be percent-encoded by RFC3986 section 2.1. Also, the things that section is defining are not "URI parameters" (which is things after a semicolon in a path segment); it's a query string format. Really, what you want to do is either: a) reference or re-define <http://www.w3.org/html/wg/drafts/html/master/forms.html#application/x-www-form-urlencoded-encoding-algorithm>, or b) define a subset of it that's simple yet precise.
> 
> 4) Section 4.2 would be a lot clearer if you just said that the well-known location is ONLY defined for the HTTPS URI scheme.
> 
> 5) Why not define a media type for JRD? You can instruct clients to also accept application/json if you're worried about bad server configurations.
> 
> 6) What's the motivation for expires, given that HTTP caching information is already available? Have you considered the interaction between them?
> 
> 7) Section 4.4.5 "user's preferred link relation." --> "user's preferred link relation type." (and likely elsewhere).
> 
> 8) RFC5988 defines the "target IRI" as what's at the end of the link; here, "linked resource" is used (e.g., 4.4.5.[2,3]). Suggest "target resource" as a way to tie them together conceptually.
> 
> 9) Similarly, an important concept in 5988 is the "context" of the link; suggest saying that the context of all of these links is the subject(s).
> 
> 10) What if a target resource supports multiple media types for the same relation? Suggest allowing multiple values in "type."
> 
> 11) 4.5 says "WebFinger requests can include a parameter specifying..." What kind of parameter? Tie it back to what happens in 4.1.
> 
> 12) 4.5 says "WebFinger is agnostic regarding the scheme of such a URI..."   I think you mean "neutral", unless the protocol really believes that the scheme is unknowable.
> 
> Lucky 13) "For resources associated with a user account at a host..." --> "To perform a webfinger lookup on an account specific to the host being queried..."
> 
> 14) In section 7 (and likely elsewhere), you should use the full URL, not just the path /.well-known/webfinger, to make it clear that this is just over HTTPS.
> 
> Cheers,
> 
> 
> * I'm not INTENTIONALLY trolling here; if it starts a fight, it's not my fault.
> 
> --
> Mark Nottingham   http://www.mnot.net/
> 
> 
> 
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 5 Feb 2013 20:24:54 +1100

Forwarding upon request.

Begin forwarded message:

> Subject: WGLC feedback on webfinger-09
> Date: 5 February 2013 5:58:02 PM AEDT

---

From: "Paul E. Jones" <[email-masked]>
Date: Wed, 6 Feb 2013 01:57:44 -0500

Mark,

> 1) The introduction seems to be missing a vital bit of information: that
> the Whole Point -- the Big Trick -- that WebFinger performs is (AIUI)
> that you can use an identifier that might not be usable as a locator
> (e.g., a mailto: uri, an acct: uri) as a locator. In that sense, it's
> really just a more real-world-usable URN lookup facility*.
> 
> This is really important to include in the abstract as well as the
> introduction, because without it, WF just seems like a silly indirection
> mechanism on top of HTTP.

Do you have suggested wording?  As I pondered on the abstract, I only made
it more complex.
 
> 2) The examples use unregistered link relations types
> <http://www.iana.org/assignments/link-relations/link-relations.xml>;
> specifically, "blog" and "vcard". Naughty.

Yeah, but there is an intent to register both of those.  You're the expert
here: any reason these could not be registered for their intended purposes?
(We can use URIs here, but the group preferred to use these type names.)
 
> 3) The text in section 4.1 isn't precise enough; consider the "=" and
> "&" characters, which are NOT required to be percent-encoded by RFC3986
> section 2.1. Also, the things that section is defining are not "URI
> parameters" (which is things after a semicolon in a path segment); it's
> a query string format. Really, what you want to do is either: a)
> reference or re-define
> <http://www.w3.org/html/wg/drafts/html/master/forms.html#application/x-
> www-form-urlencoded-encoding-algorithm>, or b) define a subset of it
> that's simple yet precise.

I forgot who offered this text.  It might have been either Tim or Dick.

I received other suggested wording.  I currently have this:

"This specification defines URI parameters that are passed from the client
to the server when issuing a request.  These parameters, "resource" and
"rel", and the parameter values are included in the "query" component of the
URI (see Section 3.4 of RFC 3986).  To construct the "query" component, the
client performs the following steps.  First, each parameter value is
percent-encoded as per Section 2.1 of RFC 3986.  Next, the client constructs
a string to be placed in the query component by concatenating the name of
the first parameter together with an equal sign ("=") and the
percent-encoded parameter value.  For any subsequent parameters, the client
appends an ampersand ("&") to the string, the name of the next parameter, an
equal sign, and the parameter value (percent-encoded as needed).  The client
MUST NOT insert any spaces while constructing the string.  The order in
which the client places each attribute-and-value pair within the query
component is unspecified."

Exactly what should we change?

> 4) Section 4.2 would be a lot clearer if you just said that the well-
> known location is ONLY defined for the HTTPS URI scheme.

There are several things said in that section that are not related to HTTPS.
Exactly what are you suggesting we change?
 
> 5) Why not define a media type for JRD? You can instruct clients to also
> accept application/json if you're worried about bad server
> configurations.

This was discussed separately.  What's the point of an application type for
a JSON object that exists only in this context?  There do not seem to be
many people defining JSON-specific sub-types, either.  There are a gazillion
+xml registrations and it's a bit of a mess, IMO.

> 6) What's the motivation for expires, given that HTTP caching
> information is already available? Have you considered the interaction
> between them?

Expires is defined in XRD and the already-defined JRD in RFC 6415.  There is
no discussion on the interaction between the HTTP caching and the JRD
expires value.  But, these are at two different layers in the stack.
Whatever generates a JRD may be a level removed from the HTTP server.
Likewise on the receiving end that processes a JRD.
 
> 7) Section 4.4.5 "user's preferred link relation." --> "user's preferred
> link relation type." (and likely elsewhere).

This is referring to multiple link relations of the same type.  If there are
multiple link relations of the same type, the first one is the user's
preferred link relation.

That is, if I insert three link relations of type "avatar" into a JRD, the
first one if my preferred avatar.
 
> 8) RFC5988 defines the "target IRI" as what's at the end of the link;
> here, "linked resource" is used (e.g., 4.4.5.[2,3]). Suggest "target
> resource" as a way to tie them together conceptually.

Just replace "linked resource" with "target resource"?
 
> 9) Similarly, an important concept in 5988 is the "context" of the link;
> suggest saying that the context of all of these links is the subject(s).

Can you suggest words to add?
 
> 10) What if a target resource supports multiple media types for the same
> relation? Suggest allowing multiple values in "type."

This would require a change in the syntax, which I'd rather not do at this
point.  However, this can be accomplished by defining two array elements,
both having the same "rel" value, but having a different "type" value.

> 11) 4.5 says "WebFinger requests can include a parameter specifying..."
> What kind of parameter? Tie it back to what happens in 4.1.

This is just the "resource" parameter.  Perhaps it's clearer if written this
way:

'WebFinger requests can include a "resource" parameter specifying...'

> 12) 4.5 says "WebFinger is agnostic regarding the scheme of such a
> URI..."   I think you mean "neutral", unless the protocol really
> believes that the scheme is unknowable.

OK, I'll change "agnostic" to "neutral".
 
> Lucky 13) "For resources associated with a user account at a host..." -->
> "To perform a webfinger lookup on an account specific to the host being
> queried..."

OK 
> 14) In section 7 (and likely elsewhere), you should use the full URL,
> not just the path /.well-known/webfinger, to make it clear that this is
> just over HTTPS.

Are you referring to the examples?  That is what the protocol would look
like on the wire.  If you're referring to the text like this:

'When a query is issued to "/.well-known/webfinger", the web server...'

The challenge there is that I need a hostname and I would not want to put
"example.com" there.  Perhaps it might be better to just say:

'When a query is issued to the WebFinger resource, the web server...'

But, that would not help clarify the use of HTTPS.  But, use of HTTPS is
stated so many times in the doc, I don't think people will screw that up.

Thanks!
Paul

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 7 Feb 2013 16:44:32 +1100

> Do you have suggested wording?  As I pondered on the abstract, I only made

"""
WebFinger is a protocol for locating information about various types of URIs that might not be usable as a locator otherwise. For example, mailto: and acct: URIs can be used to identify e-mail and localised accounts, but they do not provide an in-built way to discover and convey additional information about the identifier.

WebFinger builds on top of HTTP [ref], TLS [ref], JSON [ref] and Web Linking [ref] to provide this service, through a well-known [ref] HTTPS URI on the same host as the URI's authority. Note that WebFinger cannot be used to find information about URIs that do not have an authority (e.g., URNs).
"""

That could replace the abstract and the first paragraph of the intro.

> (We can use URIs here, but the group preferred to use these type names.)

Putting unregistered ANYTHING in an RFC is bad -- especially if it looks vaguely useful.

Register them or change them, before publishing. Since "text/vcard" is already a media type, you might want to re-think that one before doing so; it's likely to have problems as-is.

> Exactly what should we change?

?? I reported an obvious bug and suggested three different ways to fix it. What more do you want?

> Exactly what are you suggesting we change?

I think I'd change the top of Section 4 to be:

"""
A Webfinger Resource is a well-known URI [ref] using the HTTPS scheme. Webfinger resources MUST NOT be served with any other URI scheme (such as HTTP).

GET requests to a WebFinger resource convey the URI to perform the query upon in the URI's query string; see [ref to 4.1] for details. 
"""

Then, edit the rest of 4.x to fit with that. 

BTW, what's the difference between 4.1 "Constructing a WebFinger Query" and 4.2 "Performing a WebFinger Query"? Are these really two separate steps that justify their own subsections?

Also, consider replacing "WebFinger server" with "WebFinger Resource".

> +xml registrations and it's a bit of a mess, IMO.

This is the Web; we identify formats with media types. How do you know it's only ever going to "exist only in this context"?

> Expires is defined in XRD and the already-defined JRD in RFC 6415.

That's a really weak justification. This spec can choose to deprecate it when used with WebFinger. What's it actually used for? Especially since that, by definition, this protocol ONLY works over HTTP?

> There is
> expires value.

Really? What happens when the HTTP response has a large freshness lifetime (either explicit or heuristic), but a smaller expires window? 

> But, these are at two different layers in the stack.

That's weak. You're happy to use the query string, so the server side will have access to HTTP headers. Very, VERY few clients these days don't have access to HTTP headers.

> first one if my preferred avatar.

Hmm. In that case, it would just be "links" not "link relations".

> Just replace "linked resource" with "target resource"?

Yes.

> Can you suggest words to add?

At the top of 4.4.5:

"""
The "links" array has any number of member objects, each of which represents a link [RFC5988]. Each of these link objects can have the following members:

* rel
* type
* href
* titles
* properties

The "rel" and "href" members are strings representing the link's relation type and the target IRI, respectively. The context of the link is the subject [ref to subject].

The "type" member is a string indicating what the media type of the result of dereferencing the link ought to be.
"""

BTW, 4.4.5 uses "elements" several times. JSON doesn't have elements; the only containment relationships are object members and array members.

> both having the same "rel" value, but having a different "type" value.

I'd like to hear the WG response in addition to the editors' response.

> 'WebFinger requests can include a "resource" parameter specifying...'

The core problem is that "parameter" is not well-defined in this specification. See earlier feedback.

> Are you referring to the examples?

Yes.

>  That is what the protocol would look

That could work. An alternative would be

"When a query is issued to the "/.well-known/webfinger" resource on an HTTPS Web server..." 

However, I think I like your formulation better, provided that "webfinger resource" is well-defined (see above).

Cheers,

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 7 Feb 2013 03:32:39 -0500

Mark,

> > Do you have suggested wording?  As I pondered on the abstract, I only
> > made it more complex.
> 
> """
> WebFinger is a protocol for locating information about various types of
> URIs that might not be usable as a locator otherwise. For example,
> mailto: and acct: URIs can be used to identify e-mail and localised
> accounts, but they do not provide an in-built way to discover and convey
> additional information about the identifier.
> 
> WebFinger builds on top of HTTP [ref], TLS [ref], JSON [ref] and Web
> Linking [ref] to provide this service, through a well-known [ref] HTTPS
> URI on the same host as the URI's authority. Note that WebFinger cannot
> be used to find information about URIs that do not have an authority
> (e.g., URNs).
> """
> 

Concerns with this text:
1) It removes the words "discover information about people or other
entities".  While what you wrote is correct, if I were not familiar with WF,
it would not immediately strike me as a protocol used for discovering
information about people.  I think that's needed.
2) I don't think we should have references in the abstract, but if we can
leave them out (since they're referenced later), that's OK
3) Replacing the first paragraph in the intro with the above makes the
second sentence seem entirely out of place.  It does not flow smoothly.
4) WebFinger can be used with URNs, but we don't talk about it.  For
example, folks have expressed interest in using it for tel: URIs.  That
would work just fine, but one just has to have a client that knows what WF
server to talk to.

I don't think we should so radically change these two sections, but I am
still open to introducing something here to make your point.
 
> Putting unregistered ANYTHING in an RFC is bad -- especially if it looks

OK, I can change them.  I'm not sure what to change them to, though.  I
guess another URI.  I'd like to have at least one example that is not a URI.
Perhaps I should replace one of those with something already registered.
I'll have to ponder this one.  (Comments, anyone?)

> Register them or change them, before publishing. Since "text/vcard" is
> already a media type, you might want to re-think that one before doing
> so; it's likely to have problems as-is.

Why would that present an issue?  That's a different registry.
 
> >> "&" characters, which are NOT required to be percent-encoded by
> >> RFC3986 section 2.1. Also, the things that section is defining are
> >> not "URI parameters" (which is things after a semicolon in a path
> >> segment); it's a query string format. Really, what you want to do is
> >> either: a) reference or re-define
<snipped as it has been updated again>
> it. What more do you want?

The text that is there was offered by somebody in order to try to make it
clear as to how to present these parameters.  Section 2.1 does not say = or
& are or are not to be encoded, but merely says that "octet's corresponding
character is outside the allowed set or is being used as a delimiter of, or
within, the component" are encoded as explained in that section.  When the
text was proposed, I had no challenge understanding exactly what to do.

So, this is why I'm having trouble understanding what to change. You call it
an obvious bug, but it's not so obvious there is a bug to me.  I would
prefer to not refer to the HTTP spec, as I think that is more challenging to
read than either the other RFC or the text currently in the WF spec.  Not
sure how to address your concern.

Here's the current text:

` This specification defines parameters that are passed from the client to
the server when issuing a request.  These parameters, "resource" and "rel",
and the parameter values are included in the "query" component of the URI
(see Section 3.4 of RFC 3986).  To construct the "query" component, the
client performs the following steps.  First, each parameter value is
percent-encoded as per Section 2.1 of RFC 3986.  Next, the client constructs
a string to be placed in the query component by concatenating the name of
the first parameter together with an equal sign ("=") and the
percent-encoded parameter value.  For any subsequent parameters, the client
appends an ampersand ("&") to the string, the name of the next parameter, an
equal sign, and the parameter value (percent-encoded as needed).  The client
MUST NOT insert any spaces while constructing the string.  The order in
which the client places each attribute-and-value pair within the query
component is unspecified.'

> A Webfinger Resource is a well-known URI [ref] using the HTTPS scheme.
> Webfinger resources MUST NOT be served with any other URI scheme (such
> as HTTP).
> 
> GET requests to a WebFinger resource convey the URI to perform the query
> upon in the URI's query string; see [ref to 4.1] for details.
> """
> 

That sounds good.  How is this:

`A Webfinger resource is a well-known URI [3] using the HTTPS scheme.
Webfinger resources MUST NOT be served with any other URI scheme (such as
HTTP).

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.

WebFinger returns a JSON Resource Descriptor (JRD) to convey information
about an entity on the Internet and utilizes the Cross-Origin Resource
Sharing (CORS) [9] specification to facilitate queries made via a web
browser.'

The last paragraph switches from 
 
> BTW, what's the difference between 4.1 "Constructing a WebFinger Query"
> and 4.2 "Performing a WebFinger Query"? Are these really two separate
> steps that justify their own subsections?

Section 4.1 is really about constructing the Request URI.  Perhaps the title
should be:

"Constructing a WebFinger Request URI"

Would that be better?
 
> Also, consider replacing "WebFinger server" with "WebFinger Resource".

That might be doable, but I need to look through the whole document.  We use
"server" in a lot of places.  We also use the word client a lot, as the
terminology used has been client/server centric.  So, I need to ensure the
wording sounds right.  I'm sure I'll mess that up ;-)

How do others feel about this one?

> >> 5) Why not define a media type for JRD? You can instruct clients to
> >> also accept application/json if you're worried about bad server
> >> configurations.
> >
> > This was discussed separately.  What's the point of an application
> > type for a JSON object that exists only in this context?  There do not
> > seem to be many people defining JSON-specific sub-types, either.
> > There are a gazillion
> This is the Web; we identify formats with media types. How do you know
> it's only ever going to "exist only in this context"?

A WF resource is an HTTP resource with a specific means defined of accessing
the resource. If there ever was some other context, then it's not WF.

There are tons of web services out there using JSON today and they don't all
have their own media types.  IANA would be employed all day on that problem
if folks did  register every separate use of JSON.
 
> That's a really weak justification. This spec can choose to deprecate it
> when used with WebFinger. What's it actually used for? Especially since
> that, by definition, this protocol ONLY works over HTTP?

I have no use for it, but wanted to maintain compatibility with RFC 6415
since there are some folks who are using RFC 6415 and would appreciate not
breaking the existing defined format.  However, I don't know what folks are
doing with it now.  I don't send it from my own server.

> Really? What happens when the HTTP response has a large freshness
> lifetime (either explicit or heuristic), but a smaller expires window?

Then somebody has a bad implementation and a recipient is going to get stale
data.

> That's weak. You're happy to use the query string, so the server side
> will have access to HTTP headers. Very, VERY few clients these days
> don't have access to HTTP headers.

Well, it is.  Consider the example where an email client performs a WF
query.  It's not a web browser, but an email client.  Perhaps this email
client is configured to automatically query the WF server for a sender as
soon as the message is opened.  It might maintain JRDs for a while, though,
since they're convenient data structures.  There might be a hash map on the
email address to JRD structures in memory.  The email application might
ignore the HTTP headers entirely and the "client" in this case is some other
part of the client that displays pictures or other information it can
discover about a contact.  The email client certainly could have access to
the HTTP headers, but that might be a thread or two removed from the other
code that is using the received JRD.

The same might be said on the server side.  In fact, it's quite likely even
more true.  JRDs might be created or stored on some sixth server down the
line somewhere far removed from the HTTP server responding to the client
request.

There is even a more basic issue: what if the client and server clocks are
different?  Clients have to use some common sense.  Let HTTP cache in
whatever way it does.  If a JRD is expired, use it, but discard it.  It
might be expired due to caching or just because the client and server clocks
are not aligned.

> >> 7) Section 4.4.5 "user's preferred link relation." --> "user's
> >> preferred link relation type." (and likely elsewhere).
> >
> > This is referring to multiple link relations of the same type.  If
> > there are multiple link relations of the same type, the first one is
> > the user's preferred link relation.
> >
> > That is, if I insert three link relations of type "avatar" into a JRD,
> > the first one if my preferred avatar.
> 

OK
 
> > Just replace "linked resource" with "target resource"?

Done.

> >> 9) Similarly, an important concept in 5988 is the "context" of the
> >> link; suggest saying that the context of all of these links is the
> subject(s).
> >
> The "links" array has any number of member objects, each of which
> represents a link [RFC5988]. Each of these link objects can have the
> following members:
> 
> * rel
> * type
> * href
> * titles
> * properties
> 
> The "rel" and "href" members are strings representing the link's
> relation type and the target IRI, respectively. The context of the link
> is the subject [ref to subject].
> 
> The "type" member is a string indicating what the media type of the
> result of dereferencing the link ought to be.
> """

OK.. I added that text.

> BTW, 4.4.5 uses "elements" several times. JSON doesn't have elements;
> the only containment relationships are object members and array members.

Arrays have "elements".  Presently, there is only one use of the word
"elements" in 4.4.5 now and it is in reference to the things in the links
array.  So, I think it's OK.
 
> >> 10) What if a target resource supports multiple media types for the
> >> same relation? Suggest allowing multiple values in "type."
> >
> > This would require a change in the syntax, which I'd rather not do at
> > this point.  However, this can be accomplished by defining two array
> > elements, both having the same "rel" value, but having a different
> "type" value.
> 

Buried in here? :)  I might be the only one reading this deep.  Do feel free
to raise it up if you want, but we did go down the path of changing the
syntax and such.  I don't think this particular issue was raised before,
though.

Is this legal in the Web Linking spec?  It appears the ABNF would allow for
multiple "type" parameters, but I've never seen that.  The contents of a
type parameter, though, appears to be a single type.  Perhaps I'm misreading
that at this late hour.

> specification. See earlier feedback.

OK.  I think the recent changes made to 4.1 will make that clearer.
Obviously, it's hard for me to see that what I wrote is not clear in someone
else's mind. ;-)
 
> >> not just the path /.well-known/webfinger, to make it clear that this
> >> is just over HTTPS.
> >

I got rid of those entirely yesterday, so they ought not be an issue.

> > The challenge there is that I need a hostname and I would not want to
> > put "example.com" there.  Perhaps it might be better to just say:
> >
> > But, that would not help clarify the use of HTTPS.  But, use of HTTPS
> > is stated so many times in the doc, I don't think people will screw
> that up.
> 
> However, I think I like your formulation better, provided that
> "webfinger resource" is well-defined (see above).

"resource" is OK, but we also have "WebFinger location" and "server" in
different places.  I like consistent terminology, but this is a "well-known
location" that happens to be a REST "resource" that works like a
client/server protocol.  Makes my head hurt.

Paul

---

From: James M Snell <[email-masked]>
Date: Thu, 7 Feb 2013 08:57:49 -0800

On Wed, Feb 6, 2013 at 9:44 PM, Mark Nottingham <[email-masked]> wrote:
> [snip]

IMHO, adding a media type for JRD is largely a harmless exercise. I'm
not convinced it would be used all that much but there's no harm in
having it and, if JRD does happen to be used in other contexts then
it'll make things easier down the road.

> That's a really weak justification. This spec can choose to deprecate it when used with WebFinger. What's it actually used for? Especially since that, by definition, this protocol ONLY works over H…

Generally agree with Mark on this one. I do see how the expires
attribute could be useful if you're locally storing copies of JRD
documents independent of an http cache but that's not a very important
use case for me. I'd prefer to just rely on http caching. It's not
something that I would lie down in the road for tho, I'd just simply
ignore the attribute.

[snip]
> I'd like to hear the WG response in addition to the editors' response.

I don't believe multiple values for type are going to be necessary...
nor have I really seen that pattern used extensively elsewhere. If
multiple types are support for given relation at a given target, just
provide two separate link objects in the JRD.

- James

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 7 Feb 2013 22:17:48 +1100

> information about people.  I think that's needed.

Agreed.

> leave them out (since they're referenced later), that's OK

Yep.

> second sentence seem entirely out of place.  It does not flow smoothly.

Perhaps. Your turn :)

> would work just fine, but one just has to have a client that knows what WF

Ah, interesting.

> still open to introducing something here to make your point.

OK.

> Why would that present an issue?  That's a different registry.

Right, but part of the guidance about what's appropriate as a link relation is that it's *not* format-specific.

> sure how to address your concern.

I referenced HTML, not HTTP.

> ` This specification defines parameters that are passed from the client to

s/are/can be/

> (see Section 3.4 of RFC 3986).  To construct the "query" component, the

no scare quotes needed

> percent-encoded as per Section 2.1 of RFC 3986.

This is the problem. "percent-encoded as per..." isn't specific enough, because you're not saying *what* has to be encoded. Is it every character? None? Every third one?

You need to say, roughly:

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

> Next, the client constructs
> equal sign, and the parameter value (percent-encoded as needed).

Strike the parenthetical "percent-encoded as needed"; it's vague and could be interepreted as requiring double-encoding.

>  The client

WFM.

> "Constructing a WebFinger Request URI"

Think so.

> if folks did  register every separate use of JSON.

Absolutely. However, this is going to be an IETF-defined standard format, for which you want interop and multiple implementations. There's a huge difference between this and the JSON document that Bobby Sue decides to slap up on the Web server.

> might be expired due to caching or just because the client and server clocks

Excellent point. HTTP's caching model takes clock drift into account. Does yours?

> array.  So, I think it's OK.

OK, my bad.

> Buried in here? :)  I might be the only one reading this deep.

LOL

> Do feel free

Well, I *hope* the WG chairs are paying attention, given that this is WGLC feedback, and they'll do the right thing. Let's see..

> type parameter, though, appears to be a single type.  Perhaps I'm misreading

It's probably best described as "possible, yet (or perhaps because it's) ill-defined."

That having been said, that's only the HTTP header serialisation (which was pre-defined before 5988). The model for linking defined by 5988 doesn't have any such constraints. Effectively, you're defining a new serialisation of that model.

> client/server protocol.  Makes my head hurt.

+1 on consistency being the high-order bit.

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 7 Feb 2013 15:48:31 -0500

Mark,

> >> """
> >> WebFinger is a protocol for locating information about various types
> >> of URIs that might not be usable as a locator otherwise. For example,
> >> accounts, but they do not provide an in-built way to discover and
> >> convey additional information about the identifier.
> >>
> >> Linking [ref] to provide this service, through a well-known [ref]
> >> HTTPS URI on the same host as the URI's authority. Note that
> >> WebFinger cannot be used to find information about URIs that do not
> >> have an authority (e.g., URNs).
> >> """
> >>
> 
> Perhaps. Your turn :)

I'd prefer to leave the intro alone, since we do cover every point you made,
I think. To address your initial point by modifying the abstract to read:

'This specification defines the WebFinger protocol, which can be used to
discover information about people or other entities on the Internet using
standard HTTP methods.  WebFinger discovers information for a URI that might
not be usable as a locator otherwise, such as account or email URIs.'

I welcome suggested changes, but I do like to use the word "discover" since
that means something to the human reader that is different than "locate".
Indeed, we're not just "locating" information.  A client does not
necessarily know what I am publishing via WF, so it truly is a "discovery"
process.

> >>>> <http://www.iana.org/assignments/link-relations/link-relations.xml>
> >>>> ; specifically, "blog" and "vcard". Naughty.
> >>>
> > OK, I can change them.  I'm not sure what to change them to, though.
> > I guess another URI.  I'd like to have at least one example that is
> not a URI.
> >> Register them or change them, before publishing. Since "text/vcard"
> >> is already a media type, you might want to re-think that one before
> >> doing so; it's likely to have problems as-is.
> >
> Right, but part of the guidance about what's appropriate as a link
> relation is that it's *not* format-specific.

Oh, I understand now.  I'll change it to this URI:
http://webfinger.example/rel/businesscard

I'll do the same for "blog".
 
(relating to section 4.1):
> > So, this is why I'm having trouble understanding what to change. You
> > call it an obvious bug, but it's not so obvious there is a bug to me.
> > I would prefer to not refer to the HTTP spec, as I think that is more
> > challenging to read than either the other RFC or the text currently in
> > the WF spec.  Not sure how to address your concern.
> 

Sorry... typo at 3am ;-)

OK
 
> > the server when issuing a request.  These parameters, "resource" and
> > "rel", and the parameter values are included in the "query" component
> > of the URI (see Section 3.4 of RFC 3986).  To construct the "query"
> > component, the
> 
> no scare quotes needed

I assume that's just around "query".  I do prefer to keep them around
"resource" and "rel" since those are being first formally introduced in this
section.
 
> This is the problem. "percent-encoded as per..." isn't specific enough,
> because you're not saying *what* has to be encoded. Is it every
> character? None? Every third one?
> 
> ...each parameter value is percent-encoded, as per Section 2.1 of RFC
> 3986, so that conforms to the query production in Section 3.4 of that
> specification, and additionally any instances of the "=" and "&"
> characters are also percent-encoded.
> """

Good.  I'll introduce that language.
 
> > a string to be placed in the query component by concatenating the name
> > of the first parameter together with an equal sign ("=") and the
> > percent-encoded parameter value.  For any subsequent parameters, the
> > client appends an ampersand ("&") to the string, the name of the next
> > parameter, an equal sign, and the parameter value (percent-encoded as
> needed).
> 
> Strike the parenthetical "percent-encoded as needed"; it's vague and
> could be interepreted as requiring double-encoding.

OK, done.
 
> > That might be doable, but I need to look through the whole document.
> > We use "server" in a lot of places.  We also use the word client a
> > lot, as the terminology used has been client/server centric.  So, I
> > need to ensure the wording sounds right.  I'm sure I'll mess that up
> > ;-)
> >

I changed the text to refer to "webfinger resource" or "resource".  Server
is used sparingly and I tried to use it only when referring to functions
provided by the web server.

> > There are tons of web services out there using JSON today and they
> > don't all have their own media types.  IANA would be employed all day
> > on that problem if folks did  register every separate use of JSON.
> 
> Absolutely. However, this is going to be an IETF-defined standard format,
> for which you want interop and multiple implementations. There's a huge
> difference between this and the JSON document that Bobby Sue decides to
> slap up on the Web server.

If we were to take the JRD format and use it elsewhere other than WebFinger
AND we would use that in a place where there might be alternative JSON
formats, I agree.  It's just not clear to me we would ever do that.

> >>>> information is already available? Have you considered the
> >>>> interaction between them?
...
> > There is even a more basic issue: what if the client and server clocks
> > are different?  Clients have to use some common sense.  Let HTTP cache
> > in whatever way it does.  If a JRD is expired, use it, but discard it.
> > It might be expired due to caching or just because the client and
> > server clocks are not aligned.
> 

First, be mindful that this is not mine. :-)  I'm just elaborating on what
has been defined already.

I do not understand how an HTTP client (browser or caching server) can
accommodate for clock differences.  If the client and server think the time
is 15 minutes apart, then the timestamps are wrong for one or the other or
both.  Of course, using the "max-age" parameter helps, as time is not given
in absolute terms.

Clock drift and merely having the wrong time are two different issues, too.
We deal with clock drift in NTP and real-time communications, but caching
servers do?  I'm confused.

In any case, the simplest solution is to ensure that the HTTP headers align
with the "Expires" value in the JRD.

Perhaps nobody even cares about the "expires" member.  I'll ask separately
if we should just remove it.

(related to multiple values in the "type" parameter)...
> > Is this legal in the Web Linking spec?  It appears the ABNF would
> > allow for multiple "type" parameters, but I've never seen that.  The
> > contents of a type parameter, though, appears to be a single type.
> > Perhaps I'm misreading that at this late hour.
> 
> That having been said, that's only the HTTP header serialisation (which
> was pre-defined before 5988). The model for linking defined by 5988
> doesn't have any such constraints. Effectively, you're defining a new
> serialisation of that model.

Honestly, I never gathered that from 5988 before.  RFC 5988 even says:
'The "type" parameter, when present, is a hint indicating what the media
type of the result of dereferencing the link should be.'

It sounds very singular to me.  If we were to allow multiple types, they
would either have to be space-separated or we would have to change "type" to
an array.  I suspect there would be resistence to that, especially since
"type" is merely a hint w.r.t. the media type that will be returned.

>>> But, that would not help clarify the use of HTTPS.  But, use of
> >>> HTTPS is stated so many times in the doc, I don't think people will
> >>> screw
> >> that up.
> >>
> > "resource" is OK, but we also have "WebFinger location" and "server"
> > in different places.  I like consistent terminology, but this is a
> > "well-known location" that happens to be a REST "resource" that works
> > like a client/server protocol.  Makes my head hurt.
> 

I've made an effort to do that.  Now, though, I don't like the parameter
name "resource".  Where it appears in prose, I put quotes around it so
people are not confused with the WebFinger resource.

I think SWD called this "principal".  Since JRD uses the term "subject",
perhaps we should rename the "resource" parameter to "subject".  Usually,
the "subject" passed in will be the "subject" returned, though not always.
In any case, I hate having the same word used two times to mean something
entirely different.

I raise that question to the list, too.  Not sure anybody scrolled this far.

Paul

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 8 Feb 2013 10:56:02 +1100

> not be usable as a locator otherwise, such as account or email URIs.'

Good.

...

Yes.

...

WFM.

...

> servers do?  I'm confused.

https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p6-cache.html#age.calculations

...

> "type" is merely a hint w.r.t. the media type that will be returned.

*mumble* The model in 5988 isn't very clear. In truth, the mapping of parameters (that word again) from different serialisations is ad hoc, at best.

...

> people are not confused with the WebFinger resource.

Sounds good.

Cheers and thanks,