url vs href for media links
Will Norris
why does media link (section 4.3.1) use the property "url" for the target URL? If we're already defining standard links in the spec, which use "href", what's the value in doing something different for media links? Shouldn't Media Link just be a specialized form of Standard Link with some implied semantics based on the property name of the media link?
So for example, a Representative Image:
"image": {
"href": "http://photos.example.com/123"
}
is really just a standard link with the rel and type values implied by the definition of "Representative Image". So it would be semantically equivalent to:
links: [
{
"href": "http://photos.example.com/123",
"rel": "preview",
"type": "image"
}
]
This is how Permalink URL is already defined today, but since it is just a URL value, it doesn't have to worry with a separate property for the URL. For Media Link, I think there is more value in being consistent with standard Links.
Martin Atkins
> (pardon all these individuals I'll be sending over the next few days...
> I've just finally gotten the chance to really start focusing on
> improving the JSON Activity implementation in Google Buzz, so this is
> the first I've dug in to the JSON spec in a few months)
>
> why does media link (section 4.3.1) use the property "url" for the
> target URL? If we're already defining standard links in the spec, which
> use "href", what's the value in doing something different for media
> links? Shouldn't Media Link just be a specialized form of Standard Link
> with some implied semantics based on the property name of the media link?
>
This is really just an accident of the order in which decisions were
made. Originally we were calling all URLs "url" in the JSON
serialization, but then we added the "standard link" construct and I
debated a bunch whether to call it url to follow everything else or to
call it href to follow how links work elsewhere, and I ultimately
settled on "href" since that's the terminology used in Web Linking.
Amusingly, the permalink property was later renamed to "link" at some
point, muddling the terminology even more.
I think we have to do one of the following:
* Rename the property for Permalink URL back to "url" or
"permalinkUrl" (I think the former was preferred in earlier discussion)
and change the standard link property to be "url" along with it.
* Rename all of the link url properties to "href" to match Standard
Link and rename the Permalink URL property to "href" too.
Of these, I think I prefer the former in general, although it does erk
me a little bit to differ from the terminology in Web Linking for the
part of the spec that refers to it.
Will Norris
actually leaving permalink as "link" doesn't bother me too much. In fact, that makes it consistent with the FB Graph API. Plus, using "href" outside the context of a link structure seems a little strange.
At least at first glance, I don't really have a problem with:
{
"link": {permalink},
"image": {
"href": {url of representative image}
}
"links": [
{
"href": {url},
"rel": {rel value},
"type": {media type}
}
]
Is that too strange?
Martin Atkins
>
> At least at first glance, I don't really have a problem with:
>
> {
> "link": {permalink},
> "image": {
> "href": {url of representative image}
> }
> "links": [
> {
> "href": {url},
> "rel": {rel value},
> "type": {media type}
> }
> ]
>
> Is that too strange?
>
It does seem pretty strange to have both the singular "link" and the
plural "links" but have one mean something pretty different to the other.
(Also, that's not how the standard link construct is required to be
serialized per the current spec; the links are actually serialized as
separate arrays keyed on relation type to make it easy to quickly find
all of the ones with a given rel value without post-processing the data
structure.)
Will Norris
Target attributes are a set of key/value pairs that describe the link
or its target; for example, a media type hint. This specification
does not attempt to coordinate their names or use, but does provide
common target attributes for use in the Link HTTP header.
Finally, this specification does not define a general syntax for
expressing links, nor mandate a specific context for any given link;
it is expected that serialisations of links will specify both
aspects. One such serialisation is communication of links through
HTTP headers, specified in Section 5.
Will Norris
that was actually something else I was going to ask about. Buzz currently uses this dictionary notation (which we have affectionately been referring to as "Panzer links"). In practice, this notation tends to make many use cases more difficult than they ought to be (simple things like, "give me a list of all the links"), and doesn't actually make the "common case" that much simpler.
Will Norris
Martin Atkins
>
> okay, actually the more I look at this and start to play with it,
> it's starting to bother me. Looking back at your first suggestion,
> standardizing on the property "url", it looks like this isn't
> actually inconsistent with Web Linking...
>
> Target attributes are a set of key/value pairs that describe the
> link
> does not attempt to coordinate their names or use*, but does provide
> common target attributes for use in the Link HTTP header.
>
> Finally, this specification does not define a general syntax for
> expressing links, nor mandate a specific context for any given link;
> it is expected that serialisations of links will specify both
> aspects. One such serialisation is communication of links through
> HTTP headers, specified in Section 5.
>
>
> although json schemas uses "href". http://json-schema.org/json-ref
>
I think the de-facto standard for linking in JSON is still up for grabs
at this point, so I think we should primarily strive for internal
consistency in the activity streams serialization and appropriateness
for our use-cases rather than consistency with external specs and
protocols that are themselves still evolving.
Will Norris
that's certainly fair. I think many of us on the Google Buzz team are pretty well convinced that using the "Panzer links" in the Buzz API was a mistake, and we'd much prefer to move to a simple array of objects. So as far as that part is concerned, we like what json-ref uses. As for parameter naming, and maintaining internal consistency for JSON Activities, I'm at least initially inclined to agree to using "url" instead of "href" for standard links.
Monica Wilkinson
--
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.
Nathan
> links: [
> {
> "href": "http://photos.example.com/123",
> "rel": "preview",
> "type": "image"
> }
> ]
or..
preview-image: "http://photos.example.com/123"
as-in
rel: href
where rel has a domain/range, so in the case of "preview-image" the
range would be something that is an image.
John Panzer
--