[AS2] Deprecate "url" in favor of "id" and "self" link relations

59 views
Skip to first unread message

James M Snell

unread,
Aug 21, 2014, 12:16:42 PM8/21/14
to public-s...@w3.org, activity...@googlegroups.com
In an activity streams document, the "url" property is typically used
to point to a displayable (typically HTML) representation of an
object. The "id" property is typically used to provide just an
identifier. With AS2's direct incorporation of IANA Link Relations, it
makes more sense to deprecate the use of "url" in favor of link
relations such as "self" or "alternate". Doing so simplifies things a
bit more and gives us better alignment with things like JSON-LD.

The change is fairly simple:

{
"objectType": "note",
"url": "http://example.org/foo"
}

Becomes

{
"objectType": "note",
"self": "http://example.org/foo"
}

In the AS2 document, the "url" property would be listed as deprecated
and treated as an alias for "self".

Thoughts?

- James

James M Snell

unread,
Aug 21, 2014, 2:35:20 PM8/21/14
to Erik Wilde, Andreas Kuckartz, public-s...@w3.org, activity...@googlegroups.com
Activity Streams 2.0 already has an "id" property that is mapped to
the JSON-LD "@id". While this property is required to be an absolute
IRI, it is not always dereferenceable and for backwards compatibility,
we cannot necessary declare that it must be. For most cases, however,
using "id" will be sufficient.

For instance,

{
"objectType": "image",
"url": "http://example.org/foo.jpg"
}

Would become,

{
"objectType": "image",
"id": "http://example.org/foo.jpg"
}

Which just works. When we apply the JSON-LD context, that maps to:

{
"@type": "image",
"@id": "http://example.org/foo.jpg"
}

However, in cases where id is not dereferenceable, such as:

{
"objectType": "person",
"id": "urn:example:person:123456",
"url": "http://example.org/~joe"
}

We'd use something like:

{
"objectType": "person",
"id": "urn:example:person:123456",
"self": "http://example.org/~joe"
}

(a more specific link relation like "profile" would work well in this
example also... instead of "self").

The point is that AS1 has always made a distinction between the static
never-changing identifier (id) and the reference to a displayable page
about the object (url). In cases where those are one and the same, id
works just fine.

- James

On Thu, Aug 21, 2014 at 11:24 AM, Erik Wilde <dr...@berkeley.edu> wrote:
> On 2014-08-21, 11:13 , Andreas Kuckartz wrote:
>>
>> We already briefly discussed this on GitHub, but why can't we replace
>> "url" by "@id" instead of "self" ?
>> https://github.com/jasnell/w3c-socialwg-activitystreams/issues/5
>> "@id" is the property specified by JSON-LD for such purposes.
>
>
> very good point, and this should be part of the bigger (and very necessary)
> discussion how to either adopt JSON-LD, or not. to me (and others, i
> assume), the current approach of "we're kind of doing JSON-LD, but not
> really" is not very helpful. if AS is using JSON-LD, it should be using it
> right, and then andreas' suggestion (and other alignments that would need to
> be made) probably are good starting points.
>
> cheers,
>
> dret.
>
> --
> erik wilde | mailto:dr...@berkeley.edu - tel:+1-510-2061079 |
> | UC Berkeley - School of Information (ISchool) |
> | http://dret.net/netdret http://twitter.com/dret |
>

Erik Wilde

unread,
Aug 21, 2014, 2:35:37 PM8/21/14
to Andreas Kuckartz, public-s...@w3.org, activity...@googlegroups.com

Andreas Kuckartz

unread,
Aug 21, 2014, 2:35:49 PM8/21/14
to public-s...@w3.org, activity...@googlegroups.com
We already briefly discussed this on GitHub, but why can't we replace
"url" by "@id" instead of "self" ?
https://github.com/jasnell/w3c-socialwg-activitystreams/issues/5

"@id" is the property specified by JSON-LD for such purposes.

Cheers,
Andreas
---

James M Snell:

Owen Shepherd

unread,
Aug 21, 2014, 3:10:06 PM8/21/14
to activity...@googlegroups.com, public-s...@w3.org
Precedent from some AS1 deployments is that link rel "self" is used in cases where the "id" property is a non-dereferencable URL to point to the activity streams document for this resource. As an example, see https://gist.github.com/oshepherd/8c879449b3a55316cd73 (which is taken from the real world example of Pump.io)

Three things I'd like to see:
  1. What is the algorithm for finding the dereferencable to an ActivityStreams document URI?
  2. What is the algorithm for finding the dereferencable to a human readable document URI?
  3. What is the algorithm for finding the embedded content URI? (For image, video, etc objects)
For AS1, these are:
  1. obj["links"]["self"]["href"] || obj["id"]
  2. obj["url"] (unless it's a collection, in which case you're screwed - SPECBUG!)
  3. obj[type]["url"] 
As much as I appreciate simplifying the spec, we should make sure that use of the spec remains simple. I am not convinced that this is the case for some of the changes in AS2

---

As a side note: I'm not a fan of the way that AS2 seems to be causing unnamed Objects to proliferate where in AS1 Media Links would have been used. We should remember the distinction between objects - things which form the vertices of a graph (or, which on a website would have distinct web pages)  and the embedded content thereof  - what AS1 called media links.

This is very important to the many applications and clients which place the objects as distinct entries in a database, because this proliferation of objects makes their lives so much harder.


Owen Shepherd

James M Snell

unread,
Aug 21, 2014, 3:30:16 PM8/21/14
to activity...@googlegroups.com, public-s...@w3.org
On Thu, Aug 21, 2014 at 12:10 PM, Owen Shepherd <owen.s...@e43.eu> wrote:
[snip]
>
> Precedent from some AS1 deployments is that link rel "self" is used in cases
> where the "id" property is a non-dereferencable URL to point to the activity
> streams document for this resource. As an example, see
> https://gist.github.com/oshepherd/8c879449b3a55316cd73 (which is taken from
> the real world example of Pump.io)
>

This precedent is just fine with the suggested change.

> Three things I'd like to see:
>
> What is the algorithm for finding the dereferencable to an ActivityStreams
> document URI?

{
"self": {
"id": "http://example.org/foo",
"mediaType": "application/activity+json"
}
}

> What is the algorithm for finding the dereferencable to a human readable
> document URI?

{
"alternate": {
"id": "http://example.org/foo",
"mediaType": "text/html"
}
}

> What is the algorithm for finding the embedded content URI? (For image,
> video, etc objects)

{
"image": {
"id": "http://example.org/foo.jpg",
"mediaType": "image/jpeg"
}
}

"self", "alternate" and "image" are all link relations.

If necessary, because of how Link Values are defined, we can also do:

{
"self": [
{
"id": "http://example.org/foo",
"mediaType": "application/activity+json"
},
{
"id": "http://example.org/foo.html",
"mediaType": "text/html"
}
],
"image": "http://example.org/foo.jpg"
}

Again, you look for the link relations you care about, then look for
the mediaType you care about. The algorithm really is not all that
complicated.

>
> For AS1, these are:
>
> obj["links"]["self"]["href"] || obj["id"]
> obj["url"] (unless it's a collection, in which case you're screwed -
> SPECBUG!)
> obj[type]["url"]
>
> As much as I appreciate simplifying the spec, we should make sure that use
> of the spec remains simple. I am not convinced that this is the case for
> some of the changes in AS2
>

Such as?

> ---
>
> As a side note: I'm not a fan of the way that AS2 seems to be causing
> unnamed Objects to proliferate where in AS1 Media Links would have been
> used. We should remember the distinction between objects - things which form
> the vertices of a graph (or, which on a website would have distinct web
> pages) and the embedded content thereof - what AS1 called media links.
>
> This is very important to the many applications and clients which place the
> objects as distinct entries in a database, because this proliferation of
> objects makes their lives so much harder.
>

Can you please give some concrete examples? I'll see if I can explain
the rationale for the changes using those examples.

- James

>

> Owen Shepherd
> http://owenshepherd.net | owen.s...@e43.eu
>
> --
> You received this message because you are subscribed to the Google Groups
> "Activity Streams" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to activity-strea...@googlegroups.com.
> To post to this group, send email to activity...@googlegroups.com.
> Visit this group at http://groups.google.com/group/activity-streams.
> For more options, visit https://groups.google.com/d/optout.

Andreas Kuckartz

unread,
Aug 21, 2014, 3:30:31 PM8/21/14
to public-s...@w3.org, activity...@googlegroups.com
James M Snell:
> Activity Streams 2.0 already has an "id" property that is mapped to
> the JSON-LD "@id". While this property is required to be an absolute
> IRI, it is not always dereferenceable and for backwards compatibility,
> we cannot necessary declare that it must be. For most cases, however,
> using "id" will be sufficient.
...
> {
> "objectType": "person",
> "id": "urn:example:person:123456",
> "url": "http://example.org/~joe"
> }
...
> The point is that AS1 has always made a distinction between the static
> never-changing identifier (id) and the reference to a displayable page
> about the object (url). In cases where those are one and the same, id
> works just fine.

Thanks, now I see where the core of the problem is: There is a property
which is unique but might not be dereferenceable and another optional
property which is unique (is it?) and dereferenceable.

I am not happy with that and hope that we can simplify this without
endangering backwards compatibility.

What can be done if we differentiate between requirements for clients
and servers ?

Can id and url be combined then for new servers to something like either
"@id": "http://example.org/person/123456"
or
"@id": "http://example.org/~joe"
?

Cheers,
Andreas

Owen Shepherd

unread,
Aug 21, 2014, 4:16:01 PM8/21/14
to activity...@googlegroups.com, public-s...@w3.org
Algorithm. Preferably in pseudo code (Or JavaScript-ish would work, since we are dealing with JSON objects here). Taking into account cases where the id of the object is not dereferencable, etc. (You might probably make the same simplification I did, in that in my pseudo code I took the view that obj[key] == null when obj == null, to simplify matters)
 
>
> For AS1, these are:
>
> obj["links"]["self"]["href"] || obj["id"]
> obj["url"] (unless it's a collection, in which case you're screwed -
> SPECBUG!)
> obj[type]["url"]
>
> As much as I appreciate simplifying the spec, we should make sure that use
> of the spec remains simple. I am not convinced that this is the case for
> some of the changes in AS2
>

Such as?


This is why I asked for the algorithms above :-)
 
> ---
>
> As a side note: I'm not a fan of the way that AS2 seems to be causing
> unnamed Objects to proliferate where in AS1 Media Links would have been
> used. We should remember the distinction between objects - things which form
> the vertices of a graph (or, which on a website would have distinct web
> pages)  and the embedded content thereof  - what AS1 called media links.
>
> This is very important to the many applications and clients which place the
> objects as distinct entries in a database, because this proliferation of
> objects makes their lives so much harder.
>

Can you please give some concrete examples? I'll see if I can explain
the rationale for the changes using those examples.


I hope you will understand if I say this will take a bit of extra time to put together. I'll try to do so soonish :-)

One simple example, a video object in AS1 looks like

 {
    "objectType": "video",
    "displayName": "Cute little kittens",
    "embedCode": "<video width='320' height='240' controls='controls'>...</video>",
    "stream": {
      "url": "http://example.org/my_video.mpg"
    },
    "image": { "url": "http://example.com/my_video.mpg.jpg"},
}

 
Per your AS2 examples, this image would go from being a Media Link to an Object. Therefore, it would "decompose" into a separate object, and would require fetching from the database by processors.

This object is not meaningful. It has no purpose on it's own, and no identifier. In other words, it is pointless it being an object; hence why I like the distinction between media links and objects, because they avoid such meaningless objects.

James M Snell

unread,
Aug 21, 2014, 4:36:38 PM8/21/14
to activity...@googlegroups.com, public-s...@w3.org
On Thu, Aug 21, 2014 at 1:15 PM, Owen Shepherd <owen.s...@e43.eu> wrote:
[snip]
>>
>> Can you please give some concrete examples? I'll see if I can explain
>> the rationale for the changes using those examples.
>>
>
> I hope you will understand if I say this will take a bit of extra time to
> put together. I'll try to do so soonish :-)
>

+1

> One simple example, a video object in AS1 looks like
>
> {
> "objectType": "video",
> "displayName": "Cute little kittens",
> "embedCode": "<video width='320' height='240'
> controls='controls'>...</video>",
> "stream": {
> "url": "http://example.org/my_video.mpg"
> },
> "image": { "url": "http://example.com/my_video.mpg.jpg"},
> }
>
>
>
> Per your AS2 examples, this image would go from being a Media Link to an
> Object. Therefore, it would "decompose" into a separate object, and would
> require fetching from the database by processors.

How I would represent this in AS2 would be:

{
"objectType": "video",
"displayName": "Cute little kittens",
"content": "<video width='320' height='240'> controls='controls'>...</video>",
"id": "http://example.org/my_video.mpg",
"image": "http://example.com/my_video.jpg"
}

"image" is defined as a Link Value, which means it can be either an
IRI or an Object. The object form is only required if you wish to
define additional properties about the referenced resource.

>
> This object is not meaningful. It has no purpose on it's own, and no
> identifier. In other words, it is pointless it being an object; hence why I
> like the distinction between media links and objects, because they avoid
> such meaningless objects.

Unless you're specifying additional properties for the linked
resource, it shouldn't need to be expressed as a JSON object at all
(as in my example above).

- James

James M Snell

unread,
Aug 21, 2014, 8:07:46 PM8/21/14
to Goix Laurent Walter, activity...@googlegroups.com, public-s...@w3.org
On Thu, Aug 21, 2014 at 3:13 PM, Goix Laurent Walter
<laurentwa...@telecomitalia.it> wrote:
>
> Hi all,
>
> i have to say that i am a bit lost here in seeing all these alternative proposals. in particular i am bit skeptical about the mix of AS-defined property names (objectType, id, etc) with potentially *any* iana link rel to be used as property name at the same level. I envision syntactic and semantic conflicts/overlaps in the future as we don’t know how the iana link rel registry will evolve…
>

A couple of points on this:

1. The AS2 draft deals with this issue in Section 3.4
(http://jasnell.github.io/w3c-socialwg-activitystreams/activitystreams2.html#linkValues).
Specifically, any valid RFC 5988 compliant link relation can be used
as an object property unless the link relation conflicts with the
definition of any of the core attributes. In other words, the AS2
vocabulary is given precedence.

2. If new link relations are added to the IANA registry over time, and
those happen to conflict with any of the properties defined by the AS2
vocabulary, the AS2 vocabulary wins.

3. Deprecation or Update of a currently registered link relation would
require the successful publication of an IETF RFC... which means the
requester would have to make a pretty darn good case as to why the
existing link relation ought to be changed or removed. To date, no one
has done this, especially since it's easier just to mint a new link
relation and ignore ones you don't want to use.

> in that sense it would be safer to separate, semantically & syntactically, what relates to the true object characteristics (basically type & id, displayName maybe and little more), from any “link” that represents or relates to it (for which link rels are powerful)
> Two alternative could (at least) be:
>
> via a specific *container* “links” property at object level (which syntax may be taken from webfinger’s jrd or simplified), which would embed all the link rels
> by leveraging possibly json-ld to distinguish the “true object properties” from the additional properties at the same level (which at this point could stay as per James’ latest proposal of using directly link rels)
>

I personally don't see much real distinction between "true object
properties" and the link relations. There are many of the existing
properties that double perfectly well as link relations.

For instance, compare:

{
"objectType": "note",
"id": "http://example.org/notes/1",
"author": "urn:example:person:joe",
"icon": "http://example.org/img/note.png"
}

To:

{
"objectType": "note",
"id": "http://example.org/notes/1",
"links": [
{
"rel": "author",
"href": "urn:example:person:joe"
},
{
"rel": "icon",
"href": "http://example.org/img/note.png"
}
]
}

In both cases, we can interpret the "author" and the "icon" in exactly
the same way.

If you look at the vocabulary
[http://jasnell.github.io/w3c-socialwg-activitystreams/activitystreams2-vocabulary.html]
all of the properties defined as type LinkValue work equally well as
Link Relations (which is why they're defined as Link Values :-) ...).
The approach that AS2 takes is far more concise. Yes, in theory, there
is a *possible* risk of conflicts rising up in the future but those
are not likely to cause any real problem in practice.

- James

>
> walter
>
> De : James M Snell
> Envoyé : ‎jeudi‎ ‎21‎ ‎août‎ ‎2014 ‎22‎:‎37
> À : activity...@googlegroups.com
> Cc : public-s...@w3.org
> Questo messaggio e i suoi allegati sono indirizzati esclusivamente alle persone indicate. La diffusione, copia o qualsiasi altra azione derivante dalla conoscenza di queste informazioni sono rigorosamente vietate. Qualora abbiate ricevuto questo documento per errore siete cortesemente pregati di darne immediata comunicazione al mittente e di provvedere alla sua distruzione, Grazie.
>
> This e-mail and any attachments is confidential and may contain privileged information intended for the addressee(s) only. Dissemination, copying, printing or use by anybody else is unauthorised. If you are not the intended recipient, please delete this message and any attachments and advise the sender by return e-mail, Thanks.
>
> Rispetta l'ambiente. Non stampare questa mail se non è necessario.

Owen Shepherd

unread,
Aug 22, 2014, 3:57:52 PM8/22/14
to activity...@googlegroups.com, public-s...@w3.org

21 August 2014 21:36

How do I find the video link when its' not the post's ID? What about if I want to publish multiple alternate versions of the video (analogous to HTML5's <source> element)?

How do I know this IRI corresponds to the actual media, and not an object I have to dereference to find the actual media?

Removing the media link from the spec may make the specification simpler, but it seems to make using it a hell of a lot harder.

Aside: Why is there a video element in the content? This is certainly different from AS1, where content corresponds to just the "textual"/"html" content (for a video, it would be "the description", for example).

This object is not meaningful. It has no purpose on it's own, and no
identifier. In other words, it is pointless it being an object; hence why I
like the distinction between media links and objects, because they avoid
such meaningless objects.
Unless you're specifying additional properties for the linked
resource, it shouldn't need to be expressed as a JSON object at all
(as in my example above).

- James

Quite often (for purposes of speeding up page layout, for example), it is preferable to include information like the image's width and height (thereby allowing the browser to precompute the page layout before it has the image). I can think of other reasons one would want metadata.

You still haven't given me the algorithm to get the information I asked for before. Why? Is that difficult to do? Would it take more than a line of pseudo-code to explain?

I reiterate, given that somebody has handed me arbitrary ActivityStreams 2 JSON, how do I, without fail,
  • Find the URI I can ask for an updated version of this AS2 JSON (if such an URI exists)
  • Find the URI I can send the user's web browser to in order to display this object (if such a URI exists), noting that such a display is not necessarily a text/html URI (as one random example, it might be application/xhtml+xml, if the webmaster is bizzare)
  • Find the URI for the embedded content (image, video, audio, whatever) in order for me to display it in my user interface (if such content is present in the post)
I gave you the pseudo-code for AS1:
    • obj["links"]["self"]["href"] || obj["id"]
    • obj["url"] *(unless it's a collection, in which case you're screwed - SPECBUG!)
    • obj[*type*]["url"]
    You will note that they each are both a single line, and trivial to explain. Now, I'd expect some extra complexity for features like the ability to express multiple media tracks (this is OK - this is a very useful feature), but right now I have no idea how I'm supposed to do any of them. And that's important, because those are some of the most basic bits of information anybody wants from an ActivityStreams object!

    For AS2, I'd really love to simplify this to
    • obj["self"] || obj["id"]
    • obj["url"] || obj["id"]
    • Returning a list of "Media link"/ "Source" objects:
      if(obj[type] is an URI) -> [{"src": obj["type"]}]
      else if(obj[type] is an object) -> [obj["type"]]
      else if(obj[type] is an array) -> obj["type"]
    Maybe this makes the spec slightly bigger, but it pus the information that I - as an implementor - need right there in front of me.

    And that's really important. Conceptual simplicity has never won out over actual simplicity in the real world.

    Kevin Marks

    unread,
    Aug 22, 2014, 4:30:08 PM8/22/14
    to activity-streams

    This is semantic purity at the expense of clarity and utility.

    When deriving the original Activity Streams properties,  we reviewed the published formats that we were attempting to unify, and found url in most of them.
    If we are going to consider breaking changes, we should redo that review, and document it more clearly this time, rather than reasoning from other sparsely implemented specs.

    Markus Lanthaler

    unread,
    Aug 25, 2014, 9:05:36 AM8/25/14
    to public-s...@w3.org, activity...@googlegroups.com
    On 21 Aug 2014 at 18:16, James M Snell wrote:
    > In an activity streams document, the "url" property is typically used
    > to point to a displayable (typically HTML) representation of an
    > object. The "id" property is typically used to provide just an
    > identifier. With AS2's direct incorporation of IANA Link Relations, it
    > makes more sense to deprecate the use of "url" in favor of link
    > relations such as "self" or "alternate". Doing so simplifies things a
    > bit more and gives us better alignment with things like JSON-LD.

    Why do you think the tokens "self" or "alternate" give "better alignment with things like JSON-LD"?

    It is interesting to note that Schema.org (likely the most widely used vocabulary) has a "url" [1] property which matches quite well with what "url" in AS1 was supposed to do. In fact, I think it is the better match than IANA's "self".


    Cheers,
    Markus


    [1] http://schema.org/url


    --
    Markus Lanthaler
    @markuslanthaler

    James M Snell

    unread,
    Aug 25, 2014, 1:47:31 PM8/25/14
    to activity...@googlegroups.com, public-s...@w3.org
    On Mon, Aug 25, 2014 at 6:05 AM, Markus Lanthaler
    <markus.l...@gmx.net> wrote:
    > On 21 Aug 2014 at 18:16, James M Snell wrote:
    >> In an activity streams document, the "url" property is typically used
    >> to point to a displayable (typically HTML) representation of an
    >> object. The "id" property is typically used to provide just an
    >> identifier. With AS2's direct incorporation of IANA Link Relations, it
    >> makes more sense to deprecate the use of "url" in favor of link
    >> relations such as "self" or "alternate". Doing so simplifies things a
    >> bit more and gives us better alignment with things like JSON-LD.
    >
    > Why do you think the tokens "self" or "alternate" give "better alignment with things like JSON-LD"?
    >

    My apologies, I was not clear enough on this point. This had to do
    with how Link Value's were defined, not with the "self" or "alternate"
    link relations in general. Previously, there was ambiguity in the way
    Link Value's used either url or id. That ambiguity has been cleared
    up.

    > It is interesting to note that Schema.org (likely the most widely used vocabulary) has a "url" [1] property which matches quite well with what "url" in AS1 was supposed to do. In fact, I think it is the better match than IANA's "self".
    >

    Based on the feedback, I've taken another pass on this that does not
    deprecate url, but goes through an specifically defines it's
    relationship to "id", "self" and "alternate". While it's just a first
    pass and should still be considered a draft, I believe the new
    language works better:

    See: http://jasnell.github.io/w3c-socialwg-activitystreams/activitystreams2.html#object-links

    - James

    >
    > Cheers,
    > Markus
    >
    >
    > [1] http://schema.org/url
    >
    >
    > --
    > Markus Lanthaler
    > @markuslanthaler
    >

    Markus Lanthaler

    unread,
    Sep 4, 2014, 6:40:54 AM9/4/14
    to public-s...@w3.org, activity...@googlegroups.com
    On 25 Aug 2014 at 19:47, James M Snell wrote:
    Hmm... so we now have

    id = @id
    duplicates (points to ids)
    self (dereferenceable IRIs)

    url ("preferred" alternate)
    alternate (more alternates)

    multiple "embedded links"

    Sorry, but this sounds overly complex to me. Could you please explain briefly what use cases this design is trying to address?


    Thanks,
    Markus



    --
    Markus Lanthaler
    @markuslanthaler



    James M Snell

    unread,
    Sep 4, 2014, 11:09:01 AM9/4/14
    to activity...@googlegroups.com, public-s...@w3.org
    On Sep 4, 2014 3:40 AM, "Markus Lanthaler" <markus.l...@gmx.net> wrote:
    >
    [snip]
    >
    > Hmm... so we now have
    >
    > id = @id
    > duplicates (points to ids)
    > self (dereferenceable IRIs)
    >

    duplicates is largely an artifact from 1.0 that I've never seen an
    adequate use of (actually, in 1.0 the situation was worse). I'd
    happily be willing to drop "duplicates" entirely.

    "self" would only really be useful/necessary if the "id" is not
    dereferenceable. I have no problem recommending that "id" always be
    dereferenceable.

    > url ("preferred" alternate)
    > alternate (more alternates)
    >
    > multiple "embedded links"
    >
    > Sorry, but this sounds overly complex to me. Could you please explain briefly what use cases this design is trying to address?
    >

    Can be illustrated by example:

    {
    "id": "http://api.example.org/notes/1",
    "displayName": "A Note",
    "content": "This is a note",
    "mediaType": "text/html",
    "url": "http://www.example.org/notes/1",
    "alternate": {
    "id": "http://www.example.org/notes/1.pdf",
    "mediaType": "application/pdf"
    },
    "icon": "http://cdn.example.org/images/note.png",
    "image": "http://cdn.example.org/notes/1/img1.png"
    }

    * "id" is the Identity;
    * "url" and "alternate" provide representations of the note itself;
    * and "icon"/"image" provide links to embedded content (rel="icon", rel="image")

    Interpreting this ought to be straightforward and unambiguous. There
    really isn't much room for simplification (all you'd end up doing is
    shifting bits around without actually eliminating anything). For
    instance, suppose we decided to go with the "links" object approach
    used elsewhere, we'd end up with something like (unless I've
    misunderstood something):

    {
    "id": "http://api.example.org/notes/1",
    "displayName": "A Note",
    "content": "This is a note",
    "links": [
    {
    "src": "http://www.example.org/notes/1",
    "type": "text/html",
    "rel": "alternate"
    },
    {
    "src": "http://www.example.org/notes/1.pdf",
    "type": "application/pdf",
    "rel": "alternate"
    },
    {
    "src": "http://cdn.example.org/images/note.png",
    "rel": "icon"
    },
    {
    "src": "http://cdn.example.org/notes/1/img1.png",
    "rel": "image"
    }
    ]
    }

    - James

    >
    > Thanks,
    > Markus
    >
    >
    >
    > --
    > Markus Lanthaler
    > @markuslanthaler
    >
    >
    >

    Nick Jennings

    unread,
    Sep 4, 2014, 11:43:57 AM9/4/14
    to activity...@googlegroups.com, public-s...@w3.org



    On Thu, Sep 4, 2014 at 5:08 PM, James M Snell <jas...@gmail.com> wrote:


    {


    Is it just me, or does the second example seem more concise, for both humans and machines?

    In the first example, it seems the property names themselves indicate type (or do you not need to know that, for example `uri` is HTML,  or `alternate.id` is a PDF, etc. ?).

    James M Snell

    unread,
    Sep 4, 2014, 12:15:20 PM9/4/14
    to activity...@googlegroups.com, public-s...@w3.org
    On Thu, Sep 4, 2014 at 8:40 AM, Nick Jennings <ni...@silverbucket.net> wrote:
    [snip]
    >
    >
    > Is it just me, or does the second example seem more concise, for both humans
    > and machines?
    >

    For me, the first is more concise, but it's a subjective view. We both
    may be suffering from a familiarity bias [1]

    [1] http://en.wikipedia.org/wiki/Familiarity_heuristic

    > In the first example, it seems the property names themselves indicate type
    > (or do you not need to know that, for example `uri` is HTML, or
    > `alternate.id` is a PDF, etc. ?).

    The property names indicate purpose, not type. The "mediaType"
    property provides a hint about the type.

    - James
    Reply all
    Reply to author
    Forward
    0 new messages