Subject: [apps-discuss] WebFinger payload as array or object

From: Tim Bray <[email-masked]>
Date: Thu, 29 Nov 2012 08:19:36 -0800

This thread has bifurcated, so I’m going to formalize that with a
subject change.

On this thread, please argue about turning the WebFinger payload inside out:

Plan A:

"links" : [
 { "rel":  "rel1", "href" : "http://example/1", "type" : "text/plain" },
 { "rel":  "rel2", "href" : "http://example/2"  "type" : "application/json" }
]

Plan B:

"links" : {
 "rel1" : { "href" : "http://example/1", "type" : "text/plain" },
 "rel2" : { "href" : "http://example/2"  "type" : "application/json" }
 }

My take: It doesn’t matter very much.  Plan A feels a little cleaner
to me, but it’s not worth the time/energy to argue over.  -T

On Thu, Nov 29, 2012 at 8:02 AM, Melvin Carvalho
<[email-masked]> wrote:
>
>
> On 29 November 2012 16:50, James M Snell <[email-masked]> wrote:
>>
>> +1 to everything Tim and Joe have said. Simpler is better.
>>
>> Fwiw, the approach I took with JSON activity streams [1] was to use rel
>> values as member names to make client code more efficient, and have the
>> values be arrays of link objects to allow multiple links...
>>
>> E.g....
>>
>> {
>>   "blog": [
>>     {"href": "http://...", ...},
>>     {"href": "http://...", ...}
>>   ]
>> }
>>
>> I know this part mostly comes down to a style choice, but this structure
>> ends up being very efficient when it comes to picking out just the link
>> relations you want while ignoring everything else.
>
> You may find this reference page valuable
>
> http://www.w3.org/2011/rdf-wg/wiki/JSON-Serialization-Examples
>
> It contains various json serialization standards
>
> 1.2.1 Shared Example for Serialization Lineup (Turtle)
> 1.2.2 Linked Data API
> 1.2.3 JRON
> 1.2.4 JSN3
> 1.2.5 JSON-LD (CURIEs)
> 1.2.6 JSON-LD (terms)
> 1.2.7 JTriples
> 1.2.8 RDF/JSON
> 1.2.9 RDFj
> 1.2.10 SPARQL Query Results in JSON
> 1.2.11 Flat triples approach to RDF graphs in JSON
>
> Essentially the common parts are part of the Entity Attribute Value model
> (aka subject predicate object)
>
> Activity streams is also a neat serialization with its own content type.
>
> Personally I think JRD is one of the weaker serializations out there.
> Though it seems incredibly tightly coupled to webfinger, for historical, and
> perhaps some social, reasons.  I've yet to hear the full rationale for this,
> articulated.
>>
>> - james
>>
>> On Nov 29, 2012 6:11 AM, "Joe Gregorio" <[email-masked]> wrote:
>>>
>>> On Thu, Nov 29, 2012 at 12:36 AM, Paul E. Jones <[email-masked]>
>>> wrote:
>>> > Joe,
>>> >
>>> > But, the JRD syntax is already defined.  Just pretend XRD never
>>> > existed.
>>> > Look at JRD on its own.  It's simple.  Why go make a bunch of changes
>>> > to it
>>> > now?
>>>
>>> I don't think Tim's proposal is a large number of changes, his
>>> proposal drops expires which
>>> doesn't belong in the file, and it drops properties.
>>>
>>> I don't think properties, at the links level, are a good thing and the
>>> sample from the spec
>>> for configuring a printer is a perfect example:
>>>
>>>     {
>>>       "rel" : "http://example.net/rel/smtp-server",
>>>       "properties" :
>>>       {
>>>         "host" : "smtp.example.com",
>>>         "port" : "587",
>>>         "login-required" : "yes",
>>>         "transport" : "starttls"
>>>       }
>>>     },
>>>
>>> That really should be:
>>>
>>>     {
>>>       "rel" : "http://example.net/rel/smtp-server",
>>>       "href": "https://smtp.packetizer.com/config.dat"
>>>     },
>>>
>>>
>>> Where https://smtp.packetizer.com/config.dat is a file format that
>>> contains
>>> the information in the properties, such as host, port, transport, etc.
>>>
>>> I think that keeps the WebFinger story simple, the file format is basic
>>> information about the entity you queried about (subject, alias,
>>> properties),
>>> and then links related to that entity.
>>>
>>> I don't believe WebFinger won't get wide adoption if you can't put
>>> SMTP configuration
>>> info directly into the WF response.
>>>
>>> I don't believe WebFinger won't get wide adoption if you have to do
>>> two requests to
>>> find that SMTP configuration info.
>>>
>>> I do believe WebFinger will get wide adoption if the format is as
>>> simple as possible.
>>>
>>> I would be fine with keeping the top level properties object.
>>>
>>> >
>>> > I can appreciate documenting all of JRD fully in the spec.  Who wants
>>> > to do
>>> > that?  I don't want to write that.  Was Tim volunteering?
>>>
>>> Yes, I believe Tim was volunteering to do that, but he can answer for
>>> himself.
>>>
>>>   -joe
>>>
>>> >
>>> > Paul
>>> >
>>>
>>>
>>>
>>> --
>>> Joe Gregorio        http://bitworking.org
>>> _______________________________________________
>>> apps-discuss mailing list
>>> [email-masked]
>>> https://www.ietf.org/mailman/listinfo/apps-discuss
>>
>>
>> _______________________________________________
>> apps-discuss mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/apps-discuss
>>
>
>
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Joe Gregorio <[email-masked]>
Date: Thu, 29 Nov 2012 11:29:28 -0500

>  { "rel":  "rel2", "href" : "http://example/2"  "type" : "application/json" }

I like Plan A because it allows more than one href per rel. If I have more
than one blog and there's a link relation for 'blog' then I can only have
one blog listed in webfinger using Plan B.

   -joe

---

From: Melvin Carvalho <[email-masked]>
Date: Thu, 29 Nov 2012 17:29:47 +0100

> to me, but it’s not worth the time/energy to argue over.  -T

Leaving the syntax aside.  I think it's better to allow the flexibility to
allow multiple value in for a relation.  For example, on social network
profile sites you often get a field that can have multiple values, such as
"People you'd like to meet", or some people may have more than one contact
number.  Perhaps these two are not the most compelling examples, but, in
the general case, it would seem more extensible to allow multiple values.
So if I've understood correctly, that means Plan A.

> >>> On Thu, Nov 29, 2012 at 12:36 AM, Paul E. Jones <[email-masked]
> >
> >>> wrote:
> >>> > Joe,
> >>> >

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Nov 2012 08:29:52 -0800

>  "rel2" : { "href" : "http://example/2"  "type" : "application/json" }
Plan C:

"links" : {
 "rel1" : [{ "href" : "http://example/1", "type" : "text/plain" },
             { "href" : "http://example/ <http://example/1>2", "type" :
"text/plain" }],
 "rel2" : [{ "href" : "http://example/ <http://example/2>3"  "type" :
"application/json" }]
 }

For me, the options are Plan A or Plan C, as those are the only ones that
allow multiple instances of a single link relation. Plan A requires you to
process through the whole set of links to find all instances of a single
link relation. Plan C allows you to select individual link relations and
then process that specific array of links.

> to me, but it’s not worth the time/energy to argue over.  -T
Agreed. Again, this mainly just comes down to painting the barn really.

- James

---

From: Melvin Carvalho <[email-masked]>
Date: Thu, 29 Nov 2012 17:37:01 +0100

> then process that specific array of links.

Like Plan C also ... seems very similar (perhaps isomorphic?) to plan A
with a slightly neater syntax.

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Nov 2012 11:41:39 -0500

jumping in here...

keep in mind that JSON/Javascript does not retain ordering for hash
dictionaries, but *does* retain ordering for arrays.

for this reason, i have adopted a style similar to your "Plan A" when
sending link collections in the JSON format; esp. when that collection
might vary over time (or via context details of the request).

Cheers.

mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

---

From: Mike Kelly <[email-masked]>
Date: Thu, 29 Nov 2012 16:56:02 +0000

Hey Mike,

I'm not sure I understand the use-case for selecting a link on the
basis of the order in which it appears in the representation.. not
over and above selecting by rel anyway. I think it might help me to
see an example where a client would need to select a link this way.

Are you bringing this up as a small point of difference or a
fundamental advantage?

Cheers,
M

On Thu, Nov 29, 2012 at 4:41 PM, mike amundsen <[email-masked]> wrote:
> sending link collections in the JSON format; esp. when that collection might
> vary over time (or via context details of the request).
>
> Cheers.
>
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Thu, Nov 29, 2012 at 11:37 AM, Melvin Carvalho <[email-masked]>
> wrote:
>>
>>
>>
>>>              { "href" : "http://example/2", "type" : "text/plain" }],
>>>  "rel2" : [{ "href" : "http://example/3"  "type" : "application/json" }]
>>>  }
>>>

-- 
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Nov 2012 12:04:04 -0500

small point of diff and, IIRC, you and i have covered this ground in
previous threads or IRC convos.

my only offering here is the following:
*if* the order of the links matters and the hash table is the chosen
implementation ("Plan B" in this thread), it would be wise to add support
in clients for an "order" property on a link objects.

Cheers.

mamund
+1.859.757.1449
skype: mca.amundsen

On Thu, Nov 29, 2012 at 11:56 AM, Mike Kelly <[email-masked]> wrote:

> might
> >>>> On this thread, please argue about turning the WebFinger payload
> inside
> >>>> out:
> >>>>
> >>>> Plan A:
> >>>>
> >>>> "links" : [
> >>>> > perhaps some social, reasons.  I've yet to hear the full rationale
> for
> >>>> > this,
> >>>> > articulated.
> >>>> >>
> >>>> >> - james
> >>>> >>

---

From: Mike Kelly <[email-masked]>
Date: Thu, 29 Nov 2012 17:31:16 +0000

> to me, but it’s not worth the time/energy to argue over.  -T

This is the actual interface clients work against, so I'm surprised
you don't think it matters.

Plan B makes the best use of the JSON object model and is therefore
much easier for clients to work with. E.g. picking the first link with
the rel 'widgets' looks like this in JS:

Plan B:

links.widget[0]

Plan A:

// will not work on IE < 9 as missing Array.filter
links.filter(function(link) { link.rel === "widget" })[0]

Cheers,
M

---

From: Mike Kelly <[email-masked]>
Date: Thu, 29 Nov 2012 17:43:29 +0000

> links.filter(function(link) { link.rel === "widget" })[0]

Sorry there's a bug in that I missed a return in the filter function! :)

links.filter(function(link) { return link.rel === "widget" })[0]

Cheers,
M

---

From: Joseph Holsten <[email-masked]>
Date: Thu, 29 Nov 2012 11:01:09 -0800

+0 don't care, leave the bikeshed primer grey. 

It's spectacularly easy to implement either way.

It's this way because it descended from XRD, where we felt <Link> elems with a single rel and href were pleasantly similar to HTML. 

--
http://josephholsten.com

---

From: "Paul E. Jones" <[email-masked]>
Date: Thu, 29 Nov 2012 14:43:13 -0500

Several times, people have asked "how do I know which of n things is the
most preferred".  Ordering is a good way to indicate preference.

Paul

> -----Original Message-----
> From: [email-masked] [mailto:apps-discuss-
> [email-masked]] On Behalf Of Mike Kelly
> Sent: Thursday, November 29, 2012 11:56 AM
> To: mike amundsen
> Cc: Joe Gregorio; IETF Apps Discuss; [email-masked]
> Subject: Re: [apps-discuss] WebFinger payload as array or object
> 
> Hey Mike,
> 
> I'm not sure I understand the use-case for selecting a link on the basis
> of the order in which it appears in the representation.. not over and
> above selecting by rel anyway. I think it might help me to see an
> example where a client would need to select a link this way.
> 
> Are you bringing this up as a small point of difference or a fundamental
> advantage?
> 
> Cheers,
> M
> 
> >>>> This thread has bifurcated, so I'm going to formalize that with a
> >>>> subject change.
> >>>>
> >>>>  { "rel":  "rel1", "href" : "http://example/1", "type" :
> >>>> "text/plain" },  { "rel":  "rel2", "href" : "http://example/2"
> "type" :
> >>>> "application/json" }
> >>>> ]
> >>>>
> >>>> Plan B:
> >>>>
> >>>> "links" : {
> >>>> "rel2" : { "href" : "http://example/2"  "type" : "application/json"
> >>>> }  }
> >>>>
> >>>
> >>> Plan C:
> >>>
> >>> "links" : {
> >>>              { "href" : "http://example/2", "type" : "text/plain"
> >>> }],  "rel2" : [{ "href" : "http://example/3"  "type" :
> >>> "application/json" }]  }
> >>>
> >>> For me, the options are Plan A or Plan C, as those are the only ones
> >>> that allow multiple instances of a single link relation. Plan A
> >>> requires you to process through the whole set of links to find all
> >>> instances of a single link relation. Plan C allows you to select
> >>> individual link relations and then process that specific array of
> links.
> >>
> >>
> >> Like Plan C also ... seems very similar (perhaps isomorphic?) to plan
> >> A with a slightly neater syntax.
> >>
> >>>
> >>>
> >>>
> >>>> My take: It doesn't matter very much.  Plan A feels a little
> >>>> cleaner to me, but it's not worth the time/energy to argue over.
> >>>> -T
> >>>>
> >>>
> >>>> >> Fwiw, the approach I took with JSON activity streams [1] was to
> >>>> >> use rel values as member names to make client code more
> >>>> >> efficient, and have the values be arrays of link objects to
> >>>> >> allow multiple links...
> >>>> >>
> >>>> >> E.g....
> >>>> >>
> >>>> >> {
> >>>> >>   "blog": [
> >>>> >> I know this part mostly comes down to a style choice, but this
> >>>> >> structure ends up being very efficient when it comes to picking
> >>>> >> out just the link relations you want while ignoring everything
> >>>> >> else.
> >>>> >
> >>>> > Essentially the common parts are part of the Entity Attribute
> >>>> > Value model (aka subject predicate object)
> >>>> >
> >>>> > Though it seems incredibly tightly coupled to webfinger, for
> >>>> > historical, and perhaps some social, reasons.  I've yet to hear
> >>>> > the full rationale for this, articulated.
> >>>> >>
> >>>> >> - james
> >>>> >>
> >>>> >>> > But, the JRD syntax is already defined.  Just pretend XRD
> >>>> >>> > never existed.
> >>>> >>> > Look at JRD on its own.  It's simple.  Why go make a bunch of
> >>>> >>> > changes to it now?
> >>>> >>>
> >>>> >>> proposal drops expires which doesn't belong in the file, and it
> >>>> >>> drops properties.
> >>>> >>>
> >>>> >>> I don't think properties, at the links level, are a good thing
> >>>> >>> and the sample from the spec for configuring a printer is a
> >>>> >>> perfect example:
> >>>> >>>
> >>>> >>>     {
> >>>> >>> Where https://smtp.packetizer.com/config.dat is a file format
> >>>> >>> that contains the information in the properties, such as host,
> >>>> >>> port, transport, etc.
> >>>> >>>
> >>>> >>> I think that keeps the WebFinger story simple, the file format
> >>>> >>> is basic information about the entity you queried about
> >>>> >>> (subject, alias, properties), and then links related to that
> >>>> >>> entity.
> >>>> >>>
> >>>> >>> I don't believe WebFinger won't get wide adoption if you can't
> >>>> >>> put SMTP configuration info directly into the WF response.
> >>>> >>>
> >>>> >>> I don't believe WebFinger won't get wide adoption if you have
> >>>> >>> to do two requests to find that SMTP configuration info.
> >>>> >>>
> >>>> >>> I do believe WebFinger will get wide adoption if the format is
> >>>> >>> as simple as possible.
> >>>> >>>
> >>>> >>> > I can appreciate documenting all of JRD fully in the spec.
> >>>> >>> > Who wants to do that?  I don't want to write that.  Was Tim
> >>>> >>> > volunteering?
> >>>> >>>
> >>>> >>> Yes, I believe Tim was volunteering to do that, but he can
> >>>> >>> answer for himself.
> >>>> >>>
> >>>> >>>   -joe
> >>>> >>>
> >>>> >>> >
> >>>> >>> > Paul
> >>>> >>> >
> >>>> >>>
> >>>> >>>
> >>>> >>>
> >>>> >>> --

---

From: Mike Kelly <[email-masked]>
Date: Thu, 29 Nov 2012 21:22:11 +0000

That makes sense, I was wondering what kind of application behaviour
would need a way to indicate preference between links of different
rel? I can't envisage that use-case.

--
Mike

---

From: Joseph Holsten <[email-masked]>
Date: Thu, 29 Nov 2012 13:55:16 -0800

"I want a pretty icon to represent this account," says the web app. "I know, I'll see what their webfinger says!"

    { ...
        "links": [
            {"rel": "apple-touch-icon-precomposed", "href": "/big-n-shiny.png"},
            {"rel": "icon", "href": "/tiny.png"}
        ]
    }

--
http://josephholsten.com

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Nov 2012 14:00:55 -0800

Better approach where order doesn't matter...

    { ...
        "links": [
            {"rel": "icon", "href": "/tiny.png"},
            {"rel": "icon", "href": "/big-n-shiny.png", "media": "only
screen and (min-device-pixel-ratio : 2)"}
        ]
    }

On Thu, Nov 29, 2012 at 1:55 PM, Joseph Holsten <[email-masked]>wrote:

> "I want a pretty icon to represent this account," says the web app. "I
> know, I'll see what their webfinger says!"
>
>     { ...
>         "links": [
> basis
> fundamental

---

From: Mike Kelly <[email-masked]>
Date: Fri, 30 Nov 2012 10:12:24 +0000

>             {"rel": "icon", "href": "/tiny.png"}

Surely that is an example of selection by rel and _not_ by order?

---

From: Joseph Holsten <[email-masked]>
Date: Fri, 30 Nov 2012 02:23:35 -0800

> Surely that is an example of selection by rel and _not_ by order?

Lets say it also includes pavatar and photo rels. Semantically equivalent to the application, but for reasons of history differently named. Istanbul, Constantinople. Gas, petrol.

But mostly it's not my bike shed. 

--
http://josephholsten.com

---

From: Mike Kelly <[email-masked]>
Date: Fri, 30 Nov 2012 11:07:10 +0000

> Lets say it also includes pavatar and photo rels. Semantically equivalent to the application, but for reasons of history differently named. Istanbul, Constantinople. Gas, petrol.

Again, the client preference there should still be driven primarily by
the rel first, and then by quality/order/type/whatever second.

> But mostly it's not my bike shed.

Sure, got it, you did the "bikeshed" thing a few posts up - which begs
the question, why are you still involved in the discussion?

This isn't bikeshedding. It's a fundamental part of the interface
you're presenting to clients. Having picked JSON.. "we want to copy
html" is a weak reason to not make the most of JSON's object model
here; particularly when doing so equally expressive, carries no
apparent drawbacks, and is significantly more intuitive to deal with
as the links can be addressed using standard JSON traversal.

Cheers,
M

---

From: "Markus Lanthaler" <[email-masked]>
Date: Fri, 30 Nov 2012 12:40:35 +0100

Melvin brought this discussion to my attention. So let me jump in here.

> as the links can be addressed using standard JSON traversal.

I completely agree with Mike on this. Developers definitely want to use
standard JSON traversal instead of having to use filters for this basic use
case -- at least that was a common feedback we got when designing JSON-LD.

To simplify client development even further I would also require that the
value of such a rel property is always an array, even if there's just a
single item; just as James proposed [1] in "Plan C":

"links" : {
  "rel1": [
     { "href" : "http://example/1", "type" : "text/plain" },
     { "href" : "http://example/2", "type" : "text/plain" }
  ],
  "rel2": [
    { "href" : "http://example/3", "type" : "application/json" }
  ]
}

This gives you a nice, uniform data structure and if you want, you can rely
on ordering at the array level.

Btw. Have there been discussions about the media type of such a response? I
haven't been able to find anything and both the current draft and RFC6415
seem to be using application/json. I think it would be much better to create
a specific media type such as application/webfinger+json for such documents.

Cheers,
Markus

[1] http://www.ietf.org/mail-archive/web/apps-discuss/current/msg08170.html
[2] https://tools.ietf.org/html/draft-ietf-appsawg-webfinger-06
[3] http://tools.ietf.org/html/rfc6415
[4] http://tools.ietf.org/html/draft-wilde-profile-link-04

--
Markus Lanthaler
@markuslanthaler

---

From: ☮ elf Pavlik ☮ <[email-masked]>
Date: Fri, 30 Nov 2012 11:49:37 +0000

> case -- at least that was a common feedback we got when designing JSON-LD.
[just brainstorming] would you see sense in evaluating use of JSON-LD ? :)

---

From: Mike Kelly <[email-masked]>
Date: Fri, 30 Nov 2012 12:38:12 +0000

> [just brainstorming] would you see sense in evaluating use of JSON-LD ? :)

application/hal+json is also another option :)

http://tools.ietf.org/html/draft-kelly-json-hal-03

---

From: "Markus Lanthaler" <[email-masked]>
Date: Fri, 30 Nov 2012 14:16:32 +0100

On Friday, November 30, 2012 12:50 PM, ☮ elf Pavlik ☮
> [just brainstorming] would you see sense in evaluating use of JSON-LD ?

That depends on what you mean by evaluating use of JSON-LD!?

If you mean exposing "generic" JSON-LD, i.e., JSON-LD without any restrictions on the shape of the data (JSON-LD serializes graphs and most of the time there are multiple ways to transform a graph to a tree) I don't think it would make much sense.

However, if you mean to ensure that a webfinger response can be transfomred to a JSON-LD document I think it would make a lot of sense. Especially considering how trivial the "required" changes are. Actually those changes are not required in the traditional sense but are required to extract data that is easy to consume. The current structure would yield to data whose structure is quite unusual and difficult to consume. 

After a quick glance it looks like that moving the rels out of the link objects would be all that's required. If you want to push this a bit further you could rename href to subject as those objects than basically again represent subjects. Perhaps you would even like to go as far as removing the "properties" and "links" keys and put that data directly in the top-level object. After all, both are properties of the subject.

Hope this helps,
Markus

--
Markus Lanthaler
@markuslanthaler

---

From: [email-masked]
Date: Thu, 29 Nov 2012 22:04:16 +0000 (GMT)

>            {"rel": "icon", "href": "/tiny.png"}

I can't imagine client code that actually works in a preference way
here, that would need a list. The client code would think like this:

   can I get an 'apple-touch-icon-precompose'?
   no, damn, try 'icon'?

In which case the list is meaningless. In fact using a list can really
only be meaningful when the rel is either the same or meaning the same
thing. In order for the latter case to be usable, only things which
mean the same can be in the list.

Otherwise you need to interpret the rel value.

The better system is the one that limits ambiguity in interpretation
of the information.

(BTW, doesn't anybody actually trim their email anymore?)
-- 
Chris Dent                                   http://burningchrome.com/
                                 [...]

---

From: Nick Jennings <[email-masked]>
Date: Thu, 29 Nov 2012 20:08:25 +0100

I like Plan C the best, but Plan A works fine as well. Plan B seems
unnecessarily restrictive and limits potential future use-cases.