Subject: [apps-discuss] draft-ietf-appsawg-webfinger-07

From: "Paul E. Jones" <[email-masked]>
Date: Sun, 2 Dec 2012 03:21:19 -0500

Folks,

I published another version of the WebFinger spec trying to bring closure to
the two open issues I see (resource representation and transport).  The new
version is here:

http://tools.ietf.org/html/draft-ietf-appsawg-webfinger-07

With respect to resource representation, I fully described the JSON Resource
Descriptor within the document.  There are no external references to RFC
6415 now, no need to go read the XRD spec, etc.  It's a fairly simple format
and I believe this text documents it sufficiently.  Combined with the visual
examples, I think this makes it pretty clear.  Have a look at the JRD
documentation in section 5.2 and provide your comments. 

With respect to HTTPS, it seems there is strong preference for "HTTPS only",
but some a fair bit of insistence for allowing HTTP.  I changed the wording
in 5.2 to try to capture opinions.  Previously, the text led with a
requirement to try HTTPS first.  That is still there.  I just added some
extra conditions that make it clearer that there are some instances where a
client must not utilize HTTP.  This might need further refinement, but I
think there is a balance we can strike here between the two camps without
introducing a lot of complex language.

I made some editorial changes through the document.

Comments are welcome, as always.  Seems I don't need to say that to this
group, though :-)

Paul

---

From: Mike Jones <[email-masked]>
Date: Sun, 2 Dec 2012 09:07:56 +0000

You're fast! :-)

________________________________
From: Paul E. Jones
Sent: 12/2/2012 12:22 AM
To: [email-masked]; [email-masked]
Subject: [apps-discuss] draft-ietf-appsawg-webfinger-07

Folks,

I published another version of the WebFinger spec trying to bring closure to the two open issues I see (resource representation and transport).  The new version is here:
http://tools.ietf.org/html/draft-ietf-appsawg-webfinger-07

With respect to resource representation, I fully described the JSON Resource Descriptor within the document.  There are no external references to RFC 6415 now, no need to go read the XRD spec, etc.  It’s a fairly simple format and I believe this text documents it sufficiently.  Combined with the visual examples, I think this makes it pretty clear.  Have a look at the JRD documentation in section 5.2 and provide your comments.

With respect to HTTPS, it seems there is strong preference for “HTTPS only”, but some a fair bit of insistence for allowing HTTP.  I changed the wording in 5.2 to try to capture opinions.  Previously, the text led with a requirement to try HTTPS first.  That is still there.  I just added some extra conditions that make it clearer that there are some instances where a client must not utilize HTTP.  This might need further refinement, but I think there is a balance we can strike here between the two camps without introducing a lot of complex language.

Comments are welcome, as always.  Seems I don’t need to say that to this group, though :-)

Paul

---

From: Tim Bray <[email-masked]>
Date: Sun, 2 Dec 2012 11:53:48 -0800

Thanks to Paul for the extra effort.  I’d like to suggest, in the interests
of courtesy and efficiency, that from here on on, contributions to this
discussion be “camera-ready”, that is to say, specific suggestions in the
style of a diff, including fully-written-out replacements language.

 -Tim

On Sun, Dec 2, 2012 at 12:21 AM, Paul E. Jones <[email-masked]>wrote:

> Folks,****
>
> ** **
>
> I published another version of the WebFinger spec trying to bring closure
> to the two open issues I see (resource representation and transport).  The
> new version is here:****
>
> http://tools.ietf.org/html/draft-ietf-appsawg-webfinger-07****
>
> ** **
>
> With respect to resource representation, I fully described the JSON
> Resource Descriptor within the document.  There are no external references
> to RFC 6415 now, no need to go read the XRD spec, etc.  It’s a fairly
> simple format and I believe this text documents it sufficiently.  Combined
> with the visual examples, I think this makes it pretty clear.  Have a look
> at the JRD documentation in section 5.2 and provide your comments. ****
>
> ** **
>
> With respect to HTTPS, it seems there is strong preference for “HTTPS
> only”, but some a fair bit of insistence for allowing HTTP.  I changed the
> wording in 5.2 to try to capture opinions.  Previously, the text led with a
> introducing a lot of complex language.****
>
> ** **
>
> I made some editorial changes through the document.****
>
> ** **
>
> Comments are welcome, as always.  Seems I don’t need to say that to this
> group, though :-)****
>
> ** **
>
> Paul****
>
> ** **
>
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>
>

---

From: "Paul E. Jones" <[email-masked]>
Date: Sun, 2 Dec 2012 15:59:08 -0500

Tim,

I didn't mean to be rude by introducing these changes, just trying to move
things along.  Most changes were fairly trivial, not worth mentioning, and
can be seen here:

http://tools.ietf.org/rfcdiff?difftype=--hwdiff
<http://tools.ietf.org/rfcdiff?difftype=--hwdiff&url2=draft-ietf-appsawg-web
finger-07.txt> &url2=draft-ietf-appsawg-webfinger-07.txt

The most significant changes were the re-write of section 5.2 and
modification to the language related to HTTPS in 5.1.  I suspect that is the
text to which you refer as preferring it to be "camera-ready".  (I would
assume the balance of the changes would not need to be presented as
"camera-ready", since they're minor editorial things.)

In any case, the most important text changes I would like folks to consider
is section 5.2 (which aims to fully document the JSON Resource Descriptor
object) and paragraphs 2 and 3 in section 5.1.

Paul

From: Tim Bray [mailto:[email-masked]] 
Sent: Sunday, December 02, 2012 2:54 PM
To: Paul E. Jones
Cc: [email-masked]; [email-masked]
Subject: Re: [apps-discuss] draft-ietf-appsawg-webfinger-07

Thanks to Paul for the extra effort.  I'd like to suggest, in the interests
of courtesy and efficiency, that from here on on, contributions to this
discussion be "camera-ready", that is to say, specific suggestions in the
style of a diff, including fully-written-out replacements language.

 -Tim

On Sun, Dec 2, 2012 at 12:21 AM, Paul E. Jones <[email-masked]>
wrote:

Folks,

Paul

---

From: Gonzalo Salgueiro <[email-masked]>
Date: Sun, 2 Dec 2012 16:48:56 -0500

A huge +1 to that.  We've been at this a looooong time and I think we are to the point in this discussion (and the draft that represents it) where actual text is much more valuable than high level opinions.

Cheers,

Gonzalo

On Dec 2, 2012, at 2:53 PM, Tim Bray wrote:

> Thanks to Paul for the extra effort.  I’d like to suggest, in the interests of courtesy and efficiency, that from here on on, contributions to this discussion be “camera-ready”, that is to say, specific suggestions in the style of a diff, including fully-written-out replacements language.
> 
>  -Tim
> 
> On Sun, Dec 2, 2012 at 12:21 AM, Paul E. Jones <[email-masked]> wrote:
> Folks,
> 
>  
>

---

From: Tim Bray <[email-masked]>
Date: Sun, 2 Dec 2012 13:57:19 -0800

No, we’re on the same side here. I’m suggesting taking webfinger-07 as a
baseline, and all *future* changes need to be proposed as a concrete delta
against it.  -T

On Sun, Dec 2, 2012 at 12:59 PM, Paul E. Jones <[email-masked]>wrote:

> Tim,****
>
> ** **
>
> I didn’t mean to be rude by introducing these changes, just trying to move
> can be seen here:****
> http://tools.ietf.org/rfcdiff?difftype=--hwdiff&url2=draft-ietf-appsawg-webfinger-07.txt
> ****
>
> ** **
>
> modification to the language related to HTTPS in 5.1.  I suspect that is
> the text to which you refer as preferring it to be “camera-ready”.  (I
> would assume the balance of the changes would not need to be presented as
> “camera-ready”, since they’re minor editorial things.)****
>
> ** **
>
> In any case, the most important text changes I would like folks to
> consider is section 5.2 (which aims to fully document the JSON Resource
> Descriptor object) and paragraphs 2 and 3 in section 5.1.****
>
> ** **
>
> Paul****
>
> ** **
>
> *From:* Tim Bray [mailto:[email-masked]]
> *Sent:* Sunday, December 02, 2012 2:54 PM
> *To:* Paul E. Jones
> *Cc:* [email-masked]; [email-masked]
> *Subject:* Re: [apps-discuss] draft-ietf-appsawg-webfinger-07****
>
> ** **
>
> Thanks to Paul for the extra effort.  I’d like to suggest, in the
> interests of courtesy and efficiency, that from here on on, contributions
> to this discussion be “camera-ready”, that is to say, specific suggestions
> in the style of a diff, including fully-written-out replacements language.
>
>  -Tim****
>
> wrote:****
>  ****
>  ****
>  ****
>  ****
>  ****
>  ****
>  ****
> https://www.ietf.org/mailman/listinfo/apps-discuss****
>
> ** **
>

---

From: Joseph Holsten <[email-masked]>
Date: Sun, 2 Dec 2012 16:02:07 -0800

Xrd was designed to fail fast under sax parsing conditions. Doesn't apply to Jrd at all.  

--
http://josephholsten.com

On Dec 2, 2012, at 15:48, Brad Fitzpatrick <[email-masked]> wrote:

> Why does the JRD have a recommended key/value order?
>

---

From: SM <[email-masked]>
Date: Sun, 02 Dec 2012 22:29:07 -0800

At 13:57 02-12-2012, Tim Bray wrote:
>No, we're on the same side here. I'm suggesting taking webfinger-07 
>as a baseline, and all *future* changes need to be proposed as a 
>concrete delta against it.  -T

That's my preference too.

Regards,
-sm

---

From: Brad Fitzpatrick <[email-masked]>
Date: Sun, 2 Dec 2012 15:48:00 -0800

---

From: "Paul E. Jones" <[email-masked]>
Date: Mon, 3 Dec 2012 16:03:04 -0500

Brad,

Things can be ordered in any way one wants since it’s a JSON object.  That said, placing things in a given order makes it easier for a human who might manually inspect the document.  I put that word in just to encourage a consistent format.

Paul

From: [email-masked] [mailto:[email-masked]] On Behalf Of Brad Fitzpatrick
Sent: Sunday, December 02, 2012 6:48 PM
To: [email-masked]
Cc: [email-masked]
Subject: Re: [apps-discuss] draft-ietf-appsawg-webfinger-07

Folks,

Paul

---

From: "Paul E. Jones" <[email-masked]>
Date: Mon, 3 Dec 2012 16:31:30 -0500

Good argument.  I’ll strike the wording.

From: Brad Fitzpatrick [mailto:[email-masked]] 
Sent: Monday, December 03, 2012 4:09 PM
To: Paul E. Jones
Cc: [email-masked]; [email-masked]
Subject: Re: [apps-discuss] draft-ietf-appsawg-webfinger-07

You want to make it easier for humans, but it will make it harder for humans.

Humans will waste time being distracted by that, trying to fight their JSON encoder to get the "recommended" ordering.  It also brings up confusion: "how can an unordered thing be ordered? Why did they write that? Surely they must mean something else and I'm just not getting it."

Most people will write their JSON with a library anyway, so almost nobody will implement that part.

It's a pointless burden IMO.

On Mon, Dec 3, 2012 at 1:03 PM, Paul E. Jones <[email-masked]> wrote:

Brad,

Paul

Folks,

Paul

---

From: Evan Prodromou <[email-masked]>
Date: Mon, 03 Dec 2012 21:52:15 -0500

Paul,

I hate to say this, but: removing /all/ reference to RFC 6415 and XRD 
seems to strip JRD of its context. Especially when we have a long gloss 
about the finger protocol still, I think some credit is due to the work 
that went before.

Maybe adding quick informative references to the two original documents 
in 5.2, like:

    /The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 [#] and based on the XRD format [#],//is a JSON object.../

-Evan

On 12-12-02 03:21 AM, Paul E. Jones wrote:
>
> Folks,
>
> I published another version of the WebFinger spec trying to bring 
> closure to the two open issues I see (resource representation and 
> transport).  The new version is here:
>
> Resource Descriptor within the document.  There are no external 
> references to RFC 6415 now, no need to go read the XRD spec, etc. 
>  It's a fairly simple format and I believe this text documents it 
> sufficiently. Combined with the visual examples, I think this makes it 
> pretty clear.  Have a look at the JRD documentation in section 5.2 and 
> provide your comments.
>
> With respect to HTTPS, it seems there is strong preference for "HTTPS 
> only", but some a fair bit of insistence for allowing HTTP.  I changed 
> the wording in 5.2 to try to capture opinions.  Previously, the text 
> led with a requirement to try HTTPS first.  That is still there.  I 
> just added some extra conditions that make it clearer that there are 
> some instances where a client must not utilize HTTP.  This might need 
> further refinement, but I think there is a balance we can strike here 
> between the two camps without introducing a lot of complex language.
>
> Comments are welcome, as always.  Seems I don't need to say that to 
> this group, though :-)
>
> Paul
>
>
>

---

From: "Paul E. Jones" <[email-masked]>
Date: Mon, 3 Dec 2012 22:43:35 -0500

Yeah, it has been suggested by a couple of people to at least have an
informative reference to RFC 6415.  Your suggestion is reasonable, I think.
I'll insert them only as informative references since all normative material
in within the WF spec itself.

Paul

From: [email-masked] [mailto:[email-masked]] On
Behalf Of Evan Prodromou
Sent: Monday, December 03, 2012 9:52 PM
To: [email-masked]
Cc: [email-masked]
Subject: Re: [apps-discuss] draft-ietf-appsawg-webfinger-07

Paul,

I hate to say this, but: removing all reference to RFC 6415 and XRD seems to
strip JRD of its context. Especially when we have a long gloss about the
finger protocol still, I think some credit is due to the work that went
before.

Maybe adding quick informative references to the two original documents in
5.2, like:

The JSON Resource Descriptor (JRD), originally introduced in RFC 6415 [#]
and based on the XRD format [#], is a JSON object...

-Evan

Folks,

Paul

---

From: Brad Fitzpatrick <[email-masked]>
Date: Mon, 3 Dec 2012 13:08:32 -0800

You want to make it easier for humans, but it will make it harder for
humans.

Humans will waste time being distracted by that, trying to fight their JSON
encoder to get the "recommended" ordering.  It also brings up confusion:
"how can an unordered thing be ordered? Why did they write that? Surely
they must mean something else and I'm just not getting it."

Most people will write their JSON with a library anyway, so almost nobody
will implement that part.

On Mon, Dec 3, 2012 at 1:03 PM, Paul E. Jones <[email-masked]> wrote:

> Brad,****
>
> ** **
>
> Things can be ordered in any way one wants since it’s a JSON object.  That
> said, placing things in a given order makes it easier for a human who might
> manually inspect the document.  I put that word in just to encourage a
> consistent format.****
>
> ** **
>
> Paul****
>
> ** **
>
> *From:* [email-masked] [mailto:
> [email-masked]] *On Behalf Of *Brad Fitzpatrick
> *Sent:* Sunday, December 02, 2012 6:48 PM
> *To:* [email-masked]
> *Cc:* [email-masked]
> Why does the JRD have a recommended key/value order?****
>