Proposed Activity Streams Extension (cross-posted to Opensocial)

[James M Snell]

I have written up a new proposed extension to Activity Streams that introduces a generalized concept of linking per RFC 5988.

Unlike the "nextLink" and "selfLink" conventions used by Google+ (for example) this uses a more generic "${rel}" syntax that more naturally supports the use of both registered and extension link relations and supports the use of multiple links per link relation.

The initial draft is available here

https://docs.google.com/open?id=0Bx2OM4n1QsxTeWJseFBkM0YwX2M

This would, for instance, provide a common model for paging that is based on the existing paging link relations already in the iana registry.. e.g.

{
"$next" : "http://.../nextpage",
"$previous" : "http://.../previouspage",
"$first": "http://.../firstpage",
"$last": "http://.../lastpage",
"items": [...}
}

As always, comments are quite welcome and requested.

- James

[James M Snell]

I can understand the concern. Several notes...

Using symbol-prefixed property names is certainly not a new idea:
- http://www.mnot.net/blog/2011/11/25/linking_in_json
- http://json-ld.org/

The main thing to note is that it will be generally unusual for most
developers to crawl through processing individual links unless it's
within the context of a generalized code library like Abdera2. Most
typically, developers will look for the specific property they need
(e.g. "$self" or "$next") as opposed to cycling through all "$" fields
looking for the one that happens to have "self" or "next", etc.

From my experience, in most applications that utilize the json format
for stuff, the more complex link structure has been unnecessary. In
fact, there are quite a few examples of links within json that are
nothing more than a single string value (e.g. nextLink, selfLink,
$ref, etc).

Ultimately, I just think that the more complex link structure you
illustrate is more complex that what is strictly necessary.

- James

On Wed, Apr 25, 2012 at 1:16 PM, Evan Prodromou <ev...@status.net> wrote:
> James,
>
> Those magic-symbol "$" properties make me a little queasy. Doing string
> comparisons of property names to determine their nature seems like a hack.
>
> We've had a "links" element in previous drafts, which worked like this:
>
>   {
>        "links": [{"rel": "next",
>                      "href": "http://example.com/page/3"},
>                    {"rel": "prev",
>                      "href": "http://example.com/page/1"},
>                    {"rel": "first",
>                      "href": "http://example.com/page/1"},
>                    {"rel": "last",
>                      "href": "http://example.com/page/8"}]
>        "items": [ ...]
>    }
>
> One nice part about this is that this link-rel-href pattern has a lot of
> precedents on the Web: the Link header in HTTP, <link> and <a> elements in
> HTML, Atom's <link>, and XRD's <Link>.
>
> -Evan

>> --
>> You received this message because you are subscribed to the Google Groups
>> "Activity Streams" group.
>> To post to this group, send email to activity...@googlegroups.com.
>> To unsubscribe from this group, send email to
>> activity-strea...@googlegroups.com.
>> For more options, visit this group at
>> http://groups.google.com/group/activity-streams?hl=en.
>
>
>
> --
> Evan Prodromou, CEO and Founder, StatusNet Inc.
> 1124 rue Marie-Anne Est #32, Montreal, Quebec, Canada H2J 2B7
> E: ev...@status.net P: +1-514-554-3826
>

[Martin Atkins]

On 04/25/2012 12:13 PM, James M Snell wrote:
>
> {

> "$next" : "http://.../nextpage",
> "$previous" : "http://.../previouspage",
> "$first": "http://.../firstpage",
> "$last": "http://.../lastpage",
> "items": [...}
> }
>

I enjoy the terseness of this syntax, and I like the compromise of
making them normal keys but prefixing them to avoid namespace collisions.

However, I do have some thoughts:

* The string/array duality of these properties is an elegant solution to
the problem of some relations expecting multiple links and others
expecting only one, but I expect this to trip up careless implementers
who will work from examples where a single string is used and then fail
when they encounter a list.

* This proposal omits the advisory MIME type usually present on links.
For many relation types this is implied or unnecessary, but for others
such as "alternate" it can be an important decision-making aid to allow
implementations to avoid fetching resources they don't support.

Neither of these are strong objections; I don't think either is
necessarily a blocker. The former is a potential compatibility
constraint on future versions based on faulty implementations and the
latter removes part of the usual featureset of links, but arguably not a
part that is commonly-used.

[James M Snell]

The challenge with that is properly anticipating the subset of link
relations that will be useful in the long term. The risk is that
splitting it the way you describe, implementors would then have to
check for links in two separate places (either top level "blessed"
links or within an arbitrary collection of extension links). Such a
distinction seems unnecessary.

On Wed, Apr 25, 2012 at 1:34 PM, Evan Prodromou <ev...@status.net> wrote:
>> [snip]
> What about selecting, as we've done with verbs, a few rel-types that are
> frequently used, and just using their names as-is? So "next" instead of
> "$next", "license" instead of "$license".
>
> As with verbs and object types, if you absolutely positively need to use one
> not on the standard list, use a namespaced URL instead.
>
> Another possibility is {"links": {"next": "...", "prev": "..."}, ...}. So,
> collection.links.next, collection.links.prev. That would keep us from having
> namespace conflicts with the RFC 5988 registered relation type list.
>
> -Evan

[James M Snell]

On Wed, Apr 25, 2012 at 1:34 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:
>
> On 04/25/2012 12:13 PM, James M Snell wrote:
>>
>>
>> {
>> "$next" : "http://.../nextpage",
>> "$previous" : "http://.../previouspage",
>> "$first": "http://.../firstpage",
>> "$last": "http://.../lastpage",
>> "items": [...}
>> }
>>
>
> I enjoy the terseness of this syntax, and I like the compromise of making
> them normal keys but prefixing them to avoid namespace collisions.
>
> However, I do have some thoughts:
>
> * The string/array duality of these properties is an elegant solution to the
> problem of some relations expecting multiple links and others expecting only
> one, but I expect this to trip up careless implementers who will work from
> examples where a single string is used and then fail when they encounter a
> list.
>

Agreed, it certainly is a risk. In general, I tend to think that this
is more something that developers will handle on a
relation-by-relation type basis. For instance, "$self" will almost
always be a single string; as would "$canonical". "$alternative"
should generally be assumed to potentially offer multiple choices (and
thus multiple links). The specific application contexts within which
these style of links would be used should be expected to accurately
document their applications specific use, providing accurate examples
that developers can draw from and referencing the spec appropriately.
We can only hold people's hands so much ;-)

> * This proposal omits the advisory MIME type usually present on links. For
> many relation types this is implied or unnecessary, but for others such as
> "alternate" it can be an important decision-making aid to allow
> implementations to avoid fetching resources they don't support.
>

True. This is one that I have debated with myself. In most of the
practical, deployed-code scenarios that I have reviewed that utilize
JSON-encoded data, the media type has either been completely optional
or entirely absent. I have rarely seen "alternate" used in a generic
way within JSON, for instance; as opposed to a specifically named
field (e.g. our "url" property to reference the text/html
representation of an Activity Stream object).

Note that in the language in the draft, I do leave the possibility
open that alternative values for the $rel fields can be used. For now,
they're simply ignored and not processed as links, but we can change
that behavior in the future. For instance, if we absolutely felt that
the ability to specify a media type was essential, we would do
something like: "$alternate":{"href":"http:///","type":"text/plain"}
at some point down the road. However, given that I have not seen any
deployed-code scenarios in which the media type was absolutely
required, I'd rather avoid the more complex syntax for now in favor of
the Simplest Thing That Could Possibly Work.

- James

> Neither of these are strong objections; I don't think either is necessarily
> a blocker. The former is a potential compatibility constraint on future
> versions based on faulty implementations and the latter removes part of the
> usual featureset of links, but arguably not a part that is commonly-used.
>
>

[James M Snell]

Ok... thanks for clarifying that :-) ....

When writing code to access this... what's the real difference between:

var m = foo.links.next

and

var m = foo["$next"]

Either way, you have to know in advance that either "links.next" or
the $next field identifies a next link.

On Wed, Apr 25, 2012 at 1:52 PM, Evan Prodromou <ev...@status.net> wrote:
>[snip]

>    {
>        "links": {
>                      "next": "http://example.com/page/3",
>                      "prev": "http://example.com/page/1",
>                      "http://example.org/my/extension/rel/type":
> "http://example.com/another"
>                    },
>        "items": [...]
>    }
>
> Nice thing about the second option is that it makes it clear that extension
> link rel types are, in fact, rel types, and not some other kind of extended
> properties.

[Martin Atkins]

On 04/25/2012 01:50 PM, James M Snell wrote:
>>
>> * The string/array duality of these properties is an elegant solution to the
>> problem of some relations expecting multiple links and others expecting only
>> one, but I expect this to trip up careless implementers who will work from
>> examples where a single string is used and then fail when they encounter a
>> list.
>>
>
> Agreed, it certainly is a risk. In general, I tend to think that this
> is more something that developers will handle on a
> relation-by-relation type basis. For instance, "$self" will almost
> always be a single string; as would "$canonical". "$alternative"
> should generally be assumed to potentially offer multiple choices (and
> thus multiple links). The specific application contexts within which
> these style of links would be used should be expected to accurately
> document their applications specific use, providing accurate examples
> that developers can draw from and referencing the spec appropriately.
> We can only hold people's hands so much ;-)
>

If the singular/plural distinction is a per-rel thing as you suggest
(which I'd agree it effectively is) then I wonder if there is any
possibility of changing the type registry to comment on the number of
each relation type so that this specification can give more specific
instructions to use a single string for singular links and an array for
plural links.

Leaving this open but assuming that people will just naturally make the
right choice about how to serialize each relation based on their
intuition seems risky.

However, it may be too late now to change the link type registry to
include this, and I could also accept the argument that today's
singleton might be tomorrow's plural for some of the link relation
types, and so I think most relation types ("self" being possibly the
only exception) would just err on allowing multiple targets.

>> * This proposal omits the advisory MIME type usually present on links. For
>> many relation types this is implied or unnecessary, but for others such as
>> "alternate" it can be an important decision-making aid to allow
>> implementations to avoid fetching resources they don't support.
>>
>
> True. This is one that I have debated with myself. In most of the
> practical, deployed-code scenarios that I have reviewed that utilize
> JSON-encoded data, the media type has either been completely optional
> or entirely absent. I have rarely seen "alternate" used in a generic
> way within JSON, for instance; as opposed to a specifically named
> field (e.g. our "url" property to reference the text/html
> representation of an Activity Stream object).
>
> Note that in the language in the draft, I do leave the possibility
> open that alternative values for the $rel fields can be used. For now,
> they're simply ignored and not processed as links, but we can change
> that behavior in the future. For instance, if we absolutely felt that
> the ability to specify a media type was essential, we would do
> something like: "$alternate":{"href":"http:///","type":"text/plain"}
> at some point down the road. However, given that I have not seen any
> deployed-code scenarios in which the media type was absolutely
> required, I'd rather avoid the more complex syntax for now in favor of
> the Simplest Thing That Could Possibly Work.
>

Agreed. rel="alternate" tends to have an awkward processing model
anyway, and I think Activity Streams' use of a special "url" property
implying link rel="alternate" type="text/html" (or something close to
it) is a nicer approach.

[Evan Prodromou]

On 04/25/2012 04:59 PM, James M Snell wrote:

Ok... thanks for clarifying that :-) ....

When writing code to access this... what's the real difference between:

  var m = foo.links.next

and

  var m = foo["$next"]

Either way, you have to know in advance that either "links.next" or
the $next field identifies a next link.

1. One is explicit ("links" is where the links are) and the other is implicit ("$" isn't a well-known symbol for links, so you have to know what it means).
2. The word "link" is used for the same set of relationships in HTTP, HTML, and Atom. I'm not familiar with other usage where "$" implies a link relationship.
3. You can focus on, or ignore, links much more easily with a hierarchical relationship. With the prefix, you have to look for, or filter out, attributes based on key.
4. "links" is a string that works as a structure member or object attribute for most modern languages I know of. The $-prefixed properties will have to be escaped or used with alternate syntax for those languages where "$" is not a legal identifier character (JavaScript being an exception here). See attachment for a PHP example.
   
5. We use composition like this in other parts of Activity Streams. We don't use prefixed property names elsewhere.

[Jack Repenning]

On Apr 25, 2012, at 1:24 PM, James M Snell wrote:

> The main thing to note is that it will be generally unusual for most
> developers to crawl through processing individual links unless it's
> within the context of a generalized code library like Abdera2. Most
> typically, developers will look for the specific property they need
> (e.g. "$self" or "$next") as opposed to cycling through all "$" fields
> looking for the one that happens to have "self" or "next", etc.

It seems to me that one important user story for these links is not their successful use in a working client, but rather what they contribute to the developer experience when the client fails in some way. The client developer will have in her hands the complete response that was actually received (possibly an error, but also possibly something not marked as an error yet not meeting expectations, such as an empty result from a search). Since the links are provided by the server developer on the basis of some understanding of the resource being returned and its context, and since the two developers have evidently failed their "meeting of the minds" about that, the links give the client-developer further hints as to what the heck the server-developer is thinking.

In this context, I very much do expect the client-developer to "crawl" (visually, not in code) through the link-like terms of the response. In fact, my own experience is that I "paw over them" fairly thoroughly and repeatedly, trying to puzzle out why this server-developer would say such a thing to me! Given, further, that I generally find myself looking at Hash objects (specifically Ruby, and indeed most specifically order-preserving, indifferent-access Ruby 1.9 / Rails 3 Hashes), I really would have to search through an unordered set of keys, digging out "the ones that start with $," trying to find the hopefully hint-full ones. It really would be easier for me, in this scenario, if they were all gathered together in their own "links" block.



Jack Repenning

Things should be made as simple as possible --
and no simpler!
-- Albert Einstein

[Evan Prodromou]

On 04/25/2012 04:24 PM, James M Snell wrote:
> I can understand the concern. Several notes...
>
> Using symbol-prefixed property names is certainly not a new idea:
> - http://www.mnot.net/blog/2011/11/25/linking_in_json
> - http://json-ld.org/
>
> The main thing to note is that it will be generally unusual for most
> developers to crawl through processing individual links unless it's
> within the context of a generalized code library like Abdera2. Most
> typically, developers will look for the specific property they need
> (e.g. "$self" or "$next") as opposed to cycling through all "$" fields
> looking for the one that happens to have "self" or "next", etc.
>
> From my experience, in most applications that utilize the json format
> for stuff, the more complex link structure has been unnecessary. In
> fact, there are quite a few examples of links within json that are
> nothing more than a single string value (e.g. nextLink, selfLink,
> $ref, etc).
>
> Ultimately, I just think that the more complex link structure you
> illustrate is more complex that what is strictly necessary.
>
> - James
>

What about selecting, as we've done with verbs, a few rel-types that are
frequently used, and just using their names as-is? So "next" instead of
"$next", "license" instead of "$license".

As with verbs and object types, if you absolutely positively need to use
one not on the standard list, use a namespaced URL instead.

Another possibility is {"links": {"next": "...", "prev": "..."}, ...}.
So, collection.links.next, collection.links.prev. That would keep us
from having namespace conflicts with the RFC 5988 registered relation
type list.

-Evan

[Evan Prodromou]

On 04/25/2012 04:34 PM, Evan Prodromou wrote:
> Another possibility is {"links": {"next": "...", "prev": "..."}, ...}.
> So, collection.links.next, collection.links.prev. That would keep us
> from having namespace conflicts with the RFC 5988 registered relation
> type list.

A quick review doesn't show any such conflicts that I can see; are there
any I'm missing? Of course, they're entirely possible as both lists evolve.

[Evan Prodromou]

On 04/25/2012 04:39 PM, James M Snell wrote:
> The challenge with that is properly anticipating the subset of link
> relations that will be useful in the long term. The risk is that
> splitting it the way you describe, implementors would then have to
> check for links in two separate places (either top level "blessed"
> links or within an arbitrary collection of extension links). Such a
> distinction seems unnecessary.
>

I guess I didn't make myself clear. I wasn't suggesting using different
places to keep links. I agree that that's sub-optimal.

I suggest that instead of using "$next" either a) just use "next":

{
"next": "http://example.com/page/3",
"prev": "http://example.com/page/1",
"http://example.org/my/extension/rel/type":
"http://example.com/another",
"items": [...]
}

Or b) use a "links" property to identify and hold all of them:

{
"links": {
"next": "http://example.com/page/3",
"prev": "http://example.com/page/1",
"http://example.org/my/extension/rel/type":
"http://example.com/another"
},
"items": [...]
}

Nice thing about the second option is that it makes it clear that
extension link rel types are, in fact, rel types, and not some other
kind of extended properties.

[Evan Prodromou]

James,

Those magic-symbol "$" properties make me a little queasy. Doing string
comparisons of property names to determine their nature seems like a hack.

We've had a "links" element in previous drafts, which worked like this:

{
"links": [{"rel": "next",
"href": "http://example.com/page/3"},
{"rel": "prev",
"href": "http://example.com/page/1"},
{"rel": "first",
"href": "http://example.com/page/1"},
{"rel": "last",
"href": "http://example.com/page/8"}]
"items": [ ...]
}

One nice part about this is that this link-rel-href pattern has a lot of
precedents on the Web: the Link header in HTTP, <link> and <a> elements
in HTML, Atom's <link>, and XRD's <Link>.

-Evan

> --
> You received this message because you are subscribed to the Google
> Groups "Activity Streams" group.
> To post to this group, send email to activity...@googlegroups.com.
> To unsubscribe from this group, send email to
> activity-strea...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/activity-streams?hl=en.

[James M Snell]

All noted. Ok... let me see what additional feedback comes in then
I'll take another look.

On Wed, Apr 25, 2012 at 2:22 PM, Evan Prodromou <ev...@status.net> wrote:
[snip]

[Jeff Martin]

I have a question on this type of thing - it may be out side of the specific scope of the spec but its related.

Our service that provides activity streams provides the latest n number of activities.   

Should the "self" assume the latest at the point of time being requested or the request that would get same result back from the service (which in our case could be done by specifying a "beforeDate" parameter (ie, give me the 5 items that happened before this date.)

As far as the spec goes, I don't know if I like the option of being an array or string - seems like we should pick one or the other.  Having either or seems like it would add an un-neccessary complication to client code.

-Jeff 

[James M Snell]

On Apr 25, 2012 5:36 PM, "Jeff Martin" <je...@jeffmartin.com> wrote:
>
> I have a question on this type of thing - it may be out side of the specific scope of the spec but its related.
>
> Our service that provides activity streams provides the latest n number of activities.   
> Should the "self" assume the latest at the point of time being requested or the request that would get same result back from the service (which in our case could be done by specifying a "beforeDate" parameter (ie, give me the 5 items that happened before this date.)
>

"self" is always the latter. Use "current" to point to the latest at the current point in time.

> As far as the spec goes, I don't know if I like the option of being an array or string - seems like we should pick one or the other.  Having either or seems like it would add an un-neccessary complication to client code.
>

Assume it's always an array perhaps?

[Jeff Martin]

thanks for the tip on "current"

how about make it a single string by default.

if there is more than one URL that covers the "rel" in question then that rel is repeated?   What are the conditions/reasons/requirements where you would want more than one URL for any given "rel" ?

-Jeff

[James M Snell]

On Thu, Apr 26, 2012 at 6:49 AM, Jeff Martin <je...@jeffmartin.com> wrote:
> thanks for the tip on "current"
>
> how about make it a single string by default.
> if there is more than one URL that covers the "rel" in question then that
> rel is repeated?   What are the conditions/reasons/requirements where you
> would want more than one URL for any given "rel" ?
>

The challenge is that properties cannot be repeated within a JSON
document... that is, if we have two "alternate" links, we CANNOT do..

{
"alternate": "link-1",
"alternate": "link-2"
}

Whether or not multiple links with the same relation are appropriate
depends entirely on the semantics of the specific link relation. For
instance, web pages can have multiple stylesheet links; a document may
have multiple "license" links if the content has been dual-licensed;
an object may have multiple available alternate representations. At
the same time tho, a document should only ever have a single "self"
link; a single "canonical" link, etc.

If we support links generically within a json document, when we have
to be prepared to deal with variable cardinality.

[Jack Repenning]

On Apr 25, 2012, at 1:34 PM, Evan Prodromou wrote:

> What about selecting, as we've done with verbs, a few rel-types that are frequently used, and just using their names as-is? So "next" instead of "$next", "license" instead of "$license".

I wondered why the "$" was there, myself -- and the proposal doesn't explain that (unless I missed something). This response suggested a reason to me: is the reason for proposing "$" to reduce conflicts with existing code/resources/field-names?

Jack Repenning

I was born not knowing, and have had only a little time to remedy that since then.

-- Richard Feynman

[Jeff Martin]

it seems like that in order to make the specification consistent, that it would need to get into the business of defining which "rel" could be array vs single value unless there is some other spec somewhere that defines such a thing.   Iana has a fairly extensive list, but doesn't define where it makes sense to have more than one link of a particular type for a particular resource.

http://www.iana.org/assignments/link-relations/link-relations.xml

Maybe some "well-known" rel's could be defined in the Base Schema Spec or be part of the Registry that defines the various objects, verbs in activity streams. 

On the other hand a client author could just be forced to make her reader flexible by not providing that definition in the spec, but it does seem to be a weakness.

Maybe for the "rel' defined by RFC5005, those could be explicitly defined.

-Jeff

[James M Snell]

The $ is there to clearly indicate that the field is a link and that
the remaining portion of the field name is intended to be interpreted
as a Link relation. Without the prefix, we run the risk of naming
conflicts with other, non-link fields.

For instance, within the Activity streams object serialization, we
have a field named "author" whose value is an Object. Within the IANA
Registry of Link Relations [1], there is an "author" link relation.
While it is a bit of a stretch to imagine both being used within a
single object, the names conflict with each other. Including the
prefix avoids the conflict... i.e.

{
"objectType":"note",
"author": { "objectType":"person", "id":"acct:j...@example.org"},
"$author": "http://www.example.org/profiles/joe"
}

The Link Registry will continue to evolve independently of the
activity streams specification and we cannot predict what new link
relations will be created and come into common use, nor can we predict
how those will potentially be applied to the activity streams format
in the future. The prefix buffers us from future conflicts.

[1] http://www.iana.org/assignments/link-relations/link-relations.xml

[James M Snell]

I don't believe that having a blessed list of "well-known" rels is
going to work long term because we simply cannot predict what
applications are going to do or what will become "well-known" and most
useful in the future. I would be more inclined to simply say that
${rel} property values must always be arrays, even if there is only a
single value... that allows developers to code to the more general
case while still allowing for the simplest case and not sacrificing
forward-compatibility.

[James M Snell]

Ok... I've been giving some thought to the single string vs array
value issue and think I've come to a decision to leave the spec as
is... here's why...

When working with specific link relations, the context in which it is
being used will generally drive the choice of whether a single value
or multiple value is being used. Use of particular link relations
within an Activity stream object is largely going to be a very
context-laden, application specific decision.

For example, suppose we want to add paging links to an activity stream
document...

{
"$next": "http://.../next-page",
"$previous": "http://.../previous-page",
"items": [ ... ]
}

With this, at some point there's going to be some documentation
somewhere that says "This is how you do paging with an activity
stream"... and that document is going to need to describe whether
$next and $previous are going to be single value or multiple...
however, it should be obvious given the context that these will nearly
always be single values.. so developers are generally safe to treat
them as such. If some specific application chooses to use multiple
values for $next and $previous, they're going to have to explain that
model to developers and those who care about that application will
write their code to just do the right thing.

(I certainly hope that makes sense... I had no fewer than four
interruptions while writing that last paragraph... lol)

The point is that no one is simply going to throw arbitrary link
relations into an activity stream without having some kind of
application specific use for those links. That use will define whether
single or multiple values are used and application developers will
generally code to that use case. For those of us who write general
purpose code utilities to work with data formats on a generic,
non-application specific level, the responsibility falls on us to
follow the spec and allow the necessary level of flexibility in the
design of our libraries.

Does that make sense or do I need to drink more coffee and try that again?

- James

[Evan Prodromou]

I don't know what the future of the links document is, but in its current state with the $-prefix format, it has my -1, for all the reasons laid out in this thread.

-Evan

[Pelle Wessman]

I'm a bit late to the party but I have to say that I agree with Evan, I'm -1 on the state of the proposal discussed in here.

I think this implementation of link relations is too different from the ones in HTML, Atom and HTTP.

In HTML, Atom and HTTP each link has a single "href", the possibility to have multiple relations and some common attributes like type, title etc.

In this proposal each link has a single relation, the possibility to have multiple "hrefs" and no other common attributes.

I also have to disagree with James Snell's conclusion that "no one is simply going to throw arbitrary link relations into an activity stream without having some kind of application specific use" - I think one of the larger benefits of link relations is that you can describe them once and then have them used in whatever context they make sense in without any specific documentation for that specific file format. That freedom means that people not normally involved in standardization can invent new flows by just piecing together two already defined things.

I'm currently drafting on some recommended guidelines for our Flattr community that describes how we think it should be implementing rel-payment links to Flattr. Currently I'm recommending them to specify both title and type. The title is useful to differentiate between different payment links in a UI and the type is useful for a UI to be able to know which links that are targeting HTML-pages and thus possible to open in a browser.

Since I don't want to recommend others to do something that I'm not doing myself I have been implementing those guidelines in Flattr itself - but when I came to including it in the JSON Activity Streams I came across this issue.

I'm much more favor of what Evan mentioned earlier:

  {
    "links": [{"rel": "payment",
               "href": "http://flattr.com/example/123",
               "title": "Flattr this",
               "type": "text/html"},
              {"rel": "payment",
               "href": "http://example.com/pay/123",
               "title": "Pay for this on Example.com",
               "type": "text/html"},
              {"rel": "first prev",
               "href": "http://example.com/page/1"}],
    "items": [ ...]
  }

/ Pelle Wessman

[James M Snell]

Hey Pelle! Welcome and thanks for jumping in! Before anything else,
note that the original separate links draft has been discontinued in
favor of the approach described in the current draft of the core
schema document here:
http://activitystrea.ms/specs/json/schema/activity-schema.html#links

That said, a few comments inline...

On Wed, Jun 27, 2012 at 3:15 AM, Pelle Wessman <voxp...@gmail.com> wrote:
> I'm a bit late to the party but I have to say that I agree with Evan, I'm -1
> on the state of the proposal discussed in here.
>
> I think this implementation of link relations is too different from the ones
> in HTML, Atom and HTTP.
>
> In HTML, Atom and HTTP each link has a single "href", the possibility to
> have multiple relations and some common attributes like type, title etc.
>

In Atom, links have only a single relation...

> In this proposal each link has a single relation, the possibility to have
> multiple "hrefs" and no other common attributes.

With the current proposal, links would be expressed as...

{
...,
"links": {
"self": "http://example.org/1",
"alternate": [
"http://example.org/2",
"http://example.org/3"
]
},
...
}

This particular example defines *three* distinct links. The use of the
array does not imply that a single link has two hrefs.. just that
there are two separate links that each use the same link relation.

>
> I also have to disagree with James Snell's conclusion that "no one is simply
> going to throw arbitrary link relations into an activity stream without
> having some kind of application specific use" - I think one of the larger
> benefits of link relations is that you can describe them once and then have
> them used in whatever context they make sense in without any specific
> documentation for that specific file format. That freedom means that people
> not normally involved in standardization can invent new flows by just
> piecing together two already defined things.

Yes, but whoever chooses to use the link relation within the stream is
going to have some sense of why they're doing so.

>
> I'm currently drafting on some recommended guidelines for our Flattr
> community that describes how we think it should be implementing rel-payment
> links to Flattr. Currently I'm recommending them to specify both title and
> type. The title is useful to differentiate between different payment links
> in a UI and the type is useful for a UI to be able to know which links that
> are targeting HTML-pages and thus possible to open in a browser.
>
> Since I don't want to recommend others to do something that I'm not doing
> myself I have been implementing those guidelines in Flattr itself - but when
> I came to including it in the JSON Activity Streams I came across this
> issue.
>
> I'm much more favor of what Evan mentioned earlier:
>
>   {
>     "links": [{"rel": "payment",
>                "href": "http://flattr.com/example/123",
>                "title": "Flattr this",
>                "type": "text/html"},
>               {"rel": "payment",
>                "href": "http://example.com/pay/123",
>                "title": "Pay for this on Example.com",
>                "type": "text/html"},
>               {"rel": "first prev",
>                "href": "http://example.com/page/1"}],
>     "items": [ ...]
>   }
>

The challenge with this approach is that it makes the most common
simple cases quite a bit more difficult to implement. For instance,
providing links like "self", "canonical", "next", "prev", "first",
"last", "edit"... each of these are typically singletons within a
document. Why should I have to crawl through an array of an arbitrary
collection of links or parse every possible combination of relations
to find them? Doing so significantly increases the complexity. I think
an argument can be (and has been) made for using an object to
represent links rather than JUST the hrefs. Based on the feedback I've
seen, the majority consensus seems to be that objects are better.

To balance out the various goals, I would suggest the following...

  {
    "links": {
"payment": [
{"href": "http://flattr.com/example/123",

         "title": "Flattr this",
         "type": "text/html"},

        {"href": "http://example.com/pay/123",

         "title": "Pay for this on Example.com",
         "type": "text/html"}
],

"first": {
"href": "http://example.com/page/1"
},
"prev": {

"href": "http://example.com/page/1"
}
},
    "items": [ ...]
  }

Yes, it's more verbose, but I believe it provides a good compromise
given everything that I've seen in the various cases. It allows the
simple cases to remain as simple as possible while providing for the
additional extensibility and flexibility you (and others) suggest is
required... (which I agree with also.. I just wanted to make sure the
additional complexity was absolutely necessary).

- James