Subject: [apps-discuss] Draft -07 mod proposal: Remove top-level "properties" in JRD

From: Tim Bray <[email-masked]>
Date: Sun, 2 Dec 2012 17:14:34 -0800

This is actively harmful.  Link relations are an excellent way to express
properties of a resource, and having two competing mechanisms will distract
developers and hurt interoperability.

Proposal:

1. Introduction: s/link relations, properties,  titles/link relations,
titles/
3. Overview: same
4.1 remove "properties:" member of JRD
4.1 last para s/and properties//
4.2 remove "properties:" member of JRD
4.2 s/any aliases and properties/any aliases/
4.3 remove "properties" top-level member of JRD
5.2 remove "properties" from bullet list after 1st para
5.2 s/"properties" is an object comprised of name/value pairs whose values
are strings//
5.2.4 Remove section
5.3 example, remove top-level "properties" member
5.4 s/and properties//

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
> 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****
>
> ** **
>
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>
>

---

From: James M Snell <[email-masked]>
Date: Sun, 2 Dec 2012 21:37:27 -0800

-1. While I personally would not have added "properties" in were I
designing the basic format, it must be recognized that there are existing
implementations that are making use of "properties" and use cases have been
put forward that show where it can be useful to reduce the number of
roundtrips necessary for various configurations. Yes, ultimately, it may
prove out that "properties" isn't as useful or helpful as the original
authors intended but that's something that will only truly come to light
once the spec is out in the hands of implementors. For now, I don't believe
it's been adequately demonstrated to be "actively harmful" and rather than
bike shedding on the format any longer, let's go with this and see what
implementors actually do with it in the wild.

- James

---

From: Tim Bray <[email-masked]>
Date: Sun, 2 Dec 2012 21:42:28 -0800

What’s it for? -T

On Sun, Dec 2, 2012 at 9:37 PM, James M Snell <[email-masked]> wrote:

>> 5.2 s/"properties" is an object comprised of name/value pairs whose
>> values are strings//
>> 5.2.4 Remove section
>>> 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:****
>>>

---

From: "Paul E. Jones" <[email-masked]>
Date: Mon, 3 Dec 2012 02:10:59 -0500

Tim,

I don't think we should get rid of properties that relate to the subject or
properties that relate to a link relation.  I'd argue we should keep the
presently-defined JRD exactly as it is (modulo correcting any errors in my
text).

Properties that describe the JRD can be used for useful things like
conveying a person's name as I showed in the example here:

https://tools.ietf.org/html/draft-ietf-appsawg-webfinger-07#section-5.2.4

Properties in link relations can provide a client with information so that
it does not have to issue subsequent queries to learn information.  The
entire email client configuration example shows how that could be done:

https://tools.ietf.org/html/draft-ietf-appsawg-webfinger-07#section-4.3

Yes, those details could be pushed off into a yet-to-be-described, separate
document that has to be queried, but why do that if we can succinctly
describe what we need right within the JRD?  A generic client looking for
user information just ignores this stuff, after all.

Paul

From: Tim Bray [mailto:[email-masked]] 
Sent: Sunday, December 02, 2012 8:15 PM
To: Paul E. Jones
Cc: [email-masked]; [email-masked]
Subject: Draft -07 mod proposal: Remove top-level "properties" in JRD

Proposal:

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
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: "Markus Lanthaler" <[email-masked]>
Date: Mon, 3 Dec 2012 11:33:40 +0100

Tim,

I’m not sure I understand what you are proposing. Is it a) remove properties
completely, i.e., there’s no way to express properties in a JRD document or
b) move those properties to the “links” object and express them by using
link relations as property names?

Cheers,
Markus

----
From: [email-masked] [mailto:[email-masked]]
On Behalf Of Tim Bray
Sent: Monday, December 03, 2012 2:15 AM
To: Paul E. Jones
Cc: [email-masked]; [email-masked]
Subject: [apps-discuss] Draft -07 mod proposal: Remove top-level
"properties" in JRD

Proposal:

 
 
6415 now, no need to go read the XRD spec, etc.  It’s a fairly simple format
 
With respect to HTTPS, it seems there is strong preference for “HTTPS only”,

 
Paul