JSON JSON JSON

[Chris Messina]

I've become pretty convinced (ok, entirely convinced) that
ActivityStreams in JSON should be our top priority.

There was some very important work done at StreamCamp (and I'm totally
bummed that I was sick and couldn't be there for most of it) and I'm
stoked that we've developed such a diverse community. That said, in
order to really make good on the value of the work we've done to date,
we can't make much more progress without also clearly specifying and
defining how people should consume and publish activities in JSON.

We've had this page for a while, but it's totally meager:

http://wiki.activitystrea.ms/JSON

We need more. And I know that we've been talking about this issue for
months here on this list, and at our individual companies. I'd like to
hear some ideas or strawmen on how to make progress here and come
together on a spec that's simple, elegant, and implementable for JSON
— and in a reasonable time period.

I don't believe that getting the 1.0 general spec out by the end of
the month is necessarily achievable at this point, though we've made
considerable positive progress on it.

Given that — and the improvements that folks like Mart, Will, Monica,
Rob, and others have contributed to it, I'd like to shift our focus a
bit to getting defining the JSON representation.

I'm open to thoughts on the best way to move forward here.

Chris

--
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.

[Christian Crumlish]

On Wed, Apr 28, 2010 at 6:39 PM, Chris Messina <chris....@gmail.com> wrote:

I've become pretty convinced (ok, entirely convinced) that
ActivityStreams in JSON should be our top priority.

 

+1

    --xian

-- 

http://mediajunk.ie

[John Panzer]

Very general suggestion that avoids the need to re-invent a bunch of syntax and semantics:

"links": [

  {"rel": "alternate", "href": "http://foo.example.com/", "type": "text/html"},

  {"rel": "photo", "href": "http://foo.example.com/photo1.jpg", "type": "image/jpeg"},

]

"links" to be reserved field name for this purpose in all JSON objects (anything constructed of name/value pairs).

Semantics are exactly the same as atom:link.

[Martin Atkins]

John Panzer wrote:
> Very general suggestion that avoids the need to re-invent a bunch of syntax
> and semantics:
>
> "links": [
> {"rel": "alternate", "href": "http://foo.example.com/", "type":
> "text/html"},
> {"rel": "photo", "href": "http://foo.example.com/photo1.jpg", "type":
> "image/jpeg"},
> ]
>
> "links" to be reserved field name for this purpose in all JSON objects
> (anything constructed of name/value pairs).
>
> Semantics are exactly the same as atom:link.
>

I only just finished recovering from the last time I made this mistake:
http://devblog.typepad.com/typepad-dev-blog/2010/04/no-more-links-array.html

JSON consumers favors data structures that don't require post-processing
in order to do the expected operations. A links array is unfortunate
because it requires consumers to scan the list to find the links they
are interested in and it does not make explicit the cardinality of each
link type.

[Monica Keller]

Hey Guys
Still updating the JSON Activity Streams spec to submit for full review but wanted to share a proposal for what the JSON could look like

http://activitystrea.ms/head/json-activity.html#Example

Proposed changes:
-Allowing id to be omitted if a permalinkUrl is provided. We always struggle coming up with this universal ids and they are generally the same as the permalinkUrl
-No longer having an array of objects per entry
-Using singular names for "verb" and "objectType" to avoid confusion. Its really one verb or object type with fallbacks

I am not crazy about using "displayName" to describe a user's life stream. I think "title" may be better

Thoughts ?

{
	"id": "http://www.bestsite.com/willy9/stream",
	"language" : "en-US",
	"displayName" : "Willy Wonka's Activity Stream on The Best Site",

	"subject" :
	{
		"id": "http://bestsite.com/user/608201527",
		"displayName" : "Willy Wonka",
		"image" : "http://www.bestsite.com/willy9/picture",

		"permalinkUrl" : "http://www.bestsite.com/willy9",
		"objectType": ["http://activitystrea.ms/schema/1.0/person"]

	},
	"generator" :
	{
		"permalinkUrl" : "http://www.bestsite.com",
		"displayName" : "The Best Site"
	},
	"entries":

	[{
		"id": "http://bestsite.com/activity/608201527_118700288155735",
		"permalinkUrl" : "http://www.bestsite.com/608201527/posts/118700288155735",

		"postedTime": "2010-04-27T06:02:36+0000",
		"title" : "Willy Wonka just RSVPed for Mozilla Labs Night - April 2010",
		"actor" : { "id": "http://bestsite.com/user/608201527"},

		"verb" : ["http://activitystrea.ms/schema/1.0/rsvp-yes"],
		"object" :
		{
			"id": "http://www.meetup.com/Mozilla-Labs-Meetup/calendar/13194973/",

			"displayName" : "Mozilla Labs Meetup (Mountain View, CA)",
			"permalinkUrl" : "http://www.meetup.com/Mozilla-Labs-Meetup/calendar/13194973/i3/site",

			"objectType": ["http://activitystrea.ms/schema/1.0/event", "http://events.com/schema/1.0/meetup"],

			"dtStart" : "2010-04-29T06:02:00+0000",
			"location" : {
				"id": "http://www.mozilla.org/locations/mtv",

				"displayName" : "Mozilla Office in Mountain View, CA",
				"streetAddress": "650 Castro St",
				"locality" : "Mountain View",
				"region": "CA",

				"country" : "US"
			}
		},
		"serviceProvider" :
		{
			"permalinkUrl" : "http://www.meetup.com",
			"displayName" : "Meetup",

			"icon" : "http://photos-b.ak.fbcdn.net/photos-ak-sf2p/v43/97/2403839689/app_2_2403839689_2546.gif"

		}
	},
	{
		"id": "http://bestsite.com/activity/608201527_118700288155740",
		"permalinkUrl" : "http://www.bestsite.com/608201527/posts/118700288155740",

		"postedTime": "2010-04-25T06:02:36+0000",
		"title" : "Willy Wonka uploaded a photo to the Incredible Shots album on Flickr",
		"actor" : { "id": "http://bestsite.com/user/608201527"},

		"verb" : ["http://activitystrea.ms/schema/1.0/post"],
		"object" :
		{
			"displayName" : "Burning Tree",

			"permalinkUrl" : "http://www.flickr.com/willy/photo/29382938293",
			"objectType": ["http://activitystrea.ms/schema/1.0/photo"],

			"thumbnail" : "http://www.flickr.com/willy/photo/29382938293/small.jpg",
			"fullImage" : "http://www.flickr.com/willy/photo/29382938293/large.jpg"

		},
		"target" :
		{
			"permalinkUrl" : "http://www.flickr.com/willy/album/2323232",
			"displayName" : "Incredible Shots",

			"thumbnail" : "http://www.flickr.com/willy/photo/29382938293/small.jpg",
			"objectType": ["http://activitystrea.ms/schema/1.0/photo-album"]

		},
		"serviceProvider" :
		{
			"permalinkUrl" : "http://www.flickr.com",
			"displayName" : "Flickr",
			"icon" : "http://www.flickr.com/favicon.ico"

		}
	}]
}

[Ed Summers]

On Thu, Apr 29, 2010 at 1:28 AM, Martin Atkins <ma...@degeneration.co.uk> wrote:
> JSON consumers favors data structures that don't require post-processing
> in order to do the expected operations. A links array is unfortunate
> because it requires consumers to scan the list to find the links they
> are interested in and it does not make explicit the cardinality of each
> link type.

So in your tight binding solution would there be any way to
automatically detect typed hyperlinks? Clients would have to be custom
written to process JSON from a particular source? Is this
intentionally getting away from REST's notion of Hypertext as the
Engine of Application State [1,2].

Also, is the general idea that activitystream json would be layered
into something like json-c [3]

//Ed

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
[3] http://www.subbu.org/blog/2008/10/explaining-state-in-hateoas
[3] http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html

[Chris Chabot]

On Thu, Apr 29, 2010 at 4:28 AM, Ed Summers <e...@pobox.com> wrote:

Also, is the general idea that activitystream json would be layered
into something like json-c [3]

I love that idea, would make it conceptually compatible with poco's json implementation as well

[Monica Keller]

The proposal should be compatible with poco's json types. That is what we have been modeling it after. In particular the address and person elements

On whether we call this JSON or JSON-C either one is fine. I read the documentation and it seemed like the reason YouTube in this case needed a new name was because they had modeled their JSON after their ATOM feeds and wanted to provide a simple and compact representation.  We also are focusing on providing a simple and compact representation but I feel that should be the norm for JSON responses, particularly from apis but if we think this term will help us with adoption like "hey they are using the good kind of json" then I am all for it :)

About the response being RESTful you are right its not actually RESTful because we have expanded certain elements to avoid consumers having to make additional requests and it would be valuable to identify which hyperlinks can be used to obtain additional resources which means that the Service Provider would need to support multiple endpoints to fetch things like photos, videos, users, etc
 There is no way to drill in programmatically - yet

So we can remove the references to REST and not support drilling in or we can extend the json activity object schema to provide hyperlinks to the full resources in addition to the summary data.  We would end up being RESTful with fat hyper links which is also where I think the web is moving. Seems to me like users today don't just want a web page with a series of links to click. There is a bit of information overload so being able to see summaries of the pages the links go to either inline or as you hover saves them time and helps them decide what to drill in.  This is part of the reason why activities are so popular...

Thoughts ?

[Martin Atkins]

On 04/29/2010 04:28 AM, Ed Summers wrote:
> On Thu, Apr 29, 2010 at 1:28 AM, Martin Atkins<ma...@degeneration.co.uk> wrote:
>> JSON consumers favors data structures that don't require post-processing
>> in order to do the expected operations. A links array is unfortunate
>> because it requires consumers to scan the list to find the links they
>> are interested in and it does not make explicit the cardinality of each
>> link type.
>
> So in your tight binding solution would there be any way to
> automatically detect typed hyperlinks? Clients would have to be custom
> written to process JSON from a particular source? Is this
> intentionally getting away from REST's notion of Hypertext as the
> Engine of Application State [1,2].
>
> Also, is the general idea that activitystream json would be layered
> into something like json-c [3]
>

I'm completely comfortable with requiring consuming software to
understand the activity streams JSON format in order to process activity
streams serialized in JSON.

To be clear, the proposal is not to remove links entirely but rather to
put them in named properties such as "permalinkUrl" and "imageLink". So
no, you can't just say "what all are the links in this thing?" without
knowing what links you are looking for, but I'm not convinced that it's
a problem.

[John Panzer]

I would be just as happy with the more convenient, 99%-use-case two-level structure:

"links": {

   "alternate" : [

    {"href": "http://foo.example.com/", "type": "text/html"},

    {"href": "http://bar.example.com/me.jpg", "type": "image/jpeg"

  ],

  "photo": [

    {"href": "http://foo.example.com/photo1.jpg"}

  ]

}

...leading to JS code like

url = links.alternate[0].href

which addresses the major pain point Martin raises in his post.  (Martin, your post seems to be about a proprietary API not an open specification which has broader extensibility needs.)

You can also drop the "type" field -- you can do this already with "link" and it's advisory anyway, but it is needed sometimes (see the rel-alternate example above).  So you only pay for it if you need it.

But there's still a 1:1 mapping.  You can even handle URI rel values relatively cleanly if you have to, though I don't like them:  links["http://example.org/ns/foo"][0].href

You do have to deal with an array of things even when the rel value documentation says that it has to be unique.  I think a regular syntax for this is a feature and the future-proofing well worth the trade-offs.

This is also pretty much what the feedparser.py library does for links, and it's quite usable.

Generic links provide a nice, constrained, very generic mechanism that already has registry and extensibility structures in place that the JSON format should re-use.

-John

On Wed, Apr 28, 2010 at 10:28 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:

[John Panzer]

On Thu, Apr 29, 2010 at 10:08 AM, Martin Atkins <ma...@degeneration.co.uk> wrote:

On 04/29/2010 04:28 AM, Ed Summers wrote:

On Thu, Apr 29, 2010 at 1:28 AM, Martin Atkins<ma...@degeneration.co.uk>  wrote:

JSON consumers favors data structures that don't require post-processing
in order to do the expected operations. A links array is unfortunate
because it requires consumers to scan the list to find the links they
are interested in and it does not make explicit the cardinality of each
link type.

So in your tight binding solution would there be any way to
automatically detect typed hyperlinks? Clients would have to be custom
written to process JSON from a particular source? Is this
intentionally getting away from REST's notion of Hypertext as the
Engine of Application State [1,2].

Also, is the general idea that activitystream json would be layered
into something like json-c [3]

I'm completely comfortable with requiring consuming software to understand the activity streams JSON format in order to process activity streams serialized in JSON.

 

To be clear, the proposal is not to remove links entirely but rather to put them in named properties such as "permalinkUrl" and "imageLink". So no, you can't just say "what all are the links in this thing?" without knowing what links you are looking for, but I'm not convinced that it's a problem.

Who maintains the registry of these things?  How do you map from the existing registries to this new registry?  How do I know that my library is going to pass through my new, experimental or private links to my code (will all libraries pass through all unknown fields of all unknown structures to clients?  In C++ and Java?)  Do we have to invent new named properties like pubsubhubbbUri?  Are we going to argue about whether links should be named xxxLink or xxxUri or xxxUrl?  

These are all pretty much solved with links.  Because they're constrained, even C libraries can pass them through without problems.  It's hard to get them wrong or do things that are _too_ crazy.  Activity Streams should not be trying to re-invent this wheel.

[Joseph Holsten]

John Panzer wrote:

Martin Atkins wrote:

To be clear, the proposal is not to remove links entirely but rather to put them in named properties such as "permalinkUrl" and "imageLink". So no, you can't just say "what all are the links in this thing?" without knowing what links you are looking for, but I'm not convinced that it's a problem.

Who maintains the registry of these things?  How do you map from the existing registries to this new registry?  How do I know that my library is going to pass through my new, experimental or private links to my code (will all libraries pass through all unknown fields of all unknown structures to clients?  In C++ and Java?)  Do we have to invent new named properties like pubsubhubbbUri?  Are we going to argue about whether links should be named xxxLink or xxxUri or xxxUrl?  

These are all pretty much solved with links.  Because they're constrained, even C libraries can pass them through without problems.  It's hard to get them wrong or do things that are _too_ crazy.  Activity Streams should not be trying to re-invent this wheel.

+1

[Monica Keller]

>>Who maintains the registry of these things?

The JSON Activity Stream spec would define each property, this definition would include indicating whether its a url for human consumption, machine consumption, etc

Since we have a generic object representation we should not need to define that many specific properties for links....

[John Panzer]

That would mean that every external spec needs to lobby the JSON Activty Stream spec to get included.  PubSubHubbub and Salmon would be the first two.  This is of course on top of the other registrations they have to do already.  Isn't that a bit silly?

[DeWitt Clinton]

One thought -- and forgive me if you've heard this one before -- is to stick with John's (correct, imo) proposal to continue to use the array of link tuples and the _existing_ atom/html5 rel value registry:

  "links": [

    {"rel": "alternate", "href": "http://foo.example.com/", "type": "text/html"},

    {"rel": "photo", "href": "http://foo.example.com/photo1.jpg", "type": "image/jpeg"},

  ]

And add an ActivityStream specific registry for well-known names in addition to the above links.

  photoUrl: "http://foo.example.com/photo1.jpg",

  permalinkUrl: "http://foo.example.com/"

(Note that the above URLs are untyped...  I just made up the key names, though.  Actual names would be up to the AS community / the registry to define.)

The truth is, clients want both forms in this particular case.   99% of the time I'd argue just using for the latter approach in JSON, but link tuples are such a well established and critical part of any restful API that it is important to preserve them as is even for "dumb" clients.

-DeWitt

[Martin Atkins]

On 04/29/2010 12:09 PM, John Panzer wrote:
>
> Who maintains the registry of these things? How do you map from the
> existing registries to this new registry? How do I know that my library
> is going to pass through my new, experimental or private links to my
> code (will all libraries pass through all unknown fields of all unknown
> structures to clients? In C++ and Java?) Do we have to invent new
> named properties like pubsubhubbbUri? Are we going to argue about
> whether links should be named xxxLink or xxxUri or xxxUrl?
>
> These are all pretty much solved with links. Because they're
> constrained, even C libraries can pass them through without problems.
> It's hard to get them wrong or do things that are _too_ crazy.
> Activity Streams should not be trying to re-invent this wheel.
>

As I noted previously, I adopted this design for the first iteration of
the (proprietary) TypePad JSON API for the reasons you state here.
However, I've received strong feedback from all stakeholders that this
design puts unnecessary burden on consumers and so spent the last couple
months in a deprecation cycle to switch to a scheme that's more natural
inside JSON's data model and more friendly to the way consumers usually
consume JSON.

In the end I don't feel incredibly strongly about it, since the design
priorities for an open specification are obviously different than for a
proprietary API with strong service coupling; I only offer the activity
streams community my experience from having already been down this same
road in a different context.

[Monica Keller]

On Thu, Apr 29, 2010 at 12:37 PM, John Panzer <jpa...@google.com> wrote:

That would mean that every external spec needs to lobby the JSON Activty Stream spec to get included.  PubSubHubbub and Salmon would be the first two.  This is of course on top of the other registrations they have to do already.  Isn't that a bit silly?

The case for JSON activity streams is different than the case for Atom activity streams. For Atom we already had parsers that handled things like parsing a collection of links with types and we were just extending what was already there. For JSON the beauty is we don't have to shoehorn anything. JSON has such low barrier of entry that its not like people have to worry about writing parsers and have to reuse code to extract links.
If we want to leverage the benefits of a compact and simple JSON response from an api then modeling if after atom is not the answer.
Martin's feedback is valuable. Consumers can loop through an array finding the appropriate rel type or just read the appropriate property directly

This does not mean publishers can't extend their json response with additional properties. I admit its trickier given the lack of namespaces so there is a risk of extending the response with a property that will later be defined to mean something else in the spec.
Prefixing could solve this but the focus should be on readability. I think OpenSocial has had similar challenges
So I don't think its silly to ask for the JSON Activity Stream spec or any JSON specification to ignore atom link types or any other more verbose previous convention. Portable contacts also defines properties for links.

I'll be glad to chat about best practices for extending JSON in person at IIW

For now the goal is to work on a representation that is easily understood by the majority of developers

[DeWitt Clinton]

Timeline wise, without saying more than I should, IIW is May 17-19, and there are a number of Buzz API talks scheduled at Google I/O on May 19-20....  Connect the dots as one will.  : )

Without being more explicit, this is a rather pressing interest of ours right now.  While I fully expect that whatever happens over the next few weeks will later need to be updated to converge with wherever the official AS spec lands, coming up with something is definitely on our very immediate todo list.

Regarding the proper JSON serialization of link relations -- one thing we're also thinking a lot about is how to serialize feeds in JSON in general (see the above comments about JSONC).  It would be nice if the same link pattern worked in both the feed level and the AS level.

-DeWitt

[John Panzer]

On Thu, Apr 29, 2010 at 2:12 PM, Monica Keller <monica...@gmail.com> wrote:

On Thu, Apr 29, 2010 at 12:37 PM, John Panzer <jpa...@google.com> wrote:

That would mean that every external spec needs to lobby the JSON Activty Stream spec to get included.  PubSubHubbub and Salmon would be the first two.  This is of course on top of the other registrations they have to do already.  Isn't that a bit silly?

The case for JSON activity streams is different than the case for Atom activity streams. For Atom we already had parsers that handled things like parsing a collection of links with types and we were just extending what was already there. For JSON the beauty is we don't have to shoehorn anything. JSON has such low barrier of entry that its not like people have to worry about writing parsers and have to reuse code to extract links.
If we want to leverage the benefits of a compact and simple JSON response from an api then modeling if after atom is not the answer.
Martin's feedback is valuable. Consumers can loop through an array finding the appropriate rel type or just read the appropriate property directly

Note that Martin was addressing a proprietary API from one vendor, whereas here we're creating a multi-vendor protocol format.  The problems are somewhat different.

I'm not that worried about the syntax -- just that there is a well understood and _lightweight_ way to add links of both known and new types.  The "links" proposal gives you that for free, but there are probably other ways to do it too.

 

Just to be clear, I'm perfectly happy with the JSON format defining common fields as photoUrl etc. as it seems warranted on a case by case basis.  My proposal is mainly that there be a structure reserved in the schema for links, and further that it be made to map conceptually in an obvious way from the same solutions in HTML and Atom.

[DeWitt Clinton]

BTW, I agree completely about making the JSON feel like JSON, and not worrying about full fidelity representations of Atom feeds in JSON.

This post explains some of our/my thinking on the topic:

  http://www.google.com/buzz/dclinton/KLdmwpsYu94/Idiomatic-JSON-data-serialization-using-the-Google

-DeWitt

[Monica Keller]

:) nice ! I am excited to see plans for json support in Buzz and I think it would be good to meet and review the proposed spec vs what you have if you can share.
Anyone going to the meetup at mozilla labs tonight ? http://www.meetup.com/Mozilla-Labs-Meetup/calendar/13194973/

[Martin Atkins]

John Panzer wrote:
>
> I'm not that worried about the syntax -- just that there is a well
> understood and _lightweight_ way to add links of both known and new types.
> The "links" proposal gives you that for free, but there are probably other
> ways to do it too.
>
> Just to be clear, I'm perfectly happy with the JSON format defining common
> fields as photoUrl etc. as it seems warranted on a case by case basis. My
> proposal is mainly that there be a structure reserved in the schema for
> links, and further that it be made to map conceptually in an obvious way
> from the same solutions in HTML and Atom.
>

If I'm understanding your original argument correctly, you suggested
that others may wish to extend this format but you're concerned that not
having an array of links makes it likely that the extension elements
will be lost when round-tripping through intermediaries.

I agree that extensibility is desirable and that getting extensions
through intermediaries has traditionally been a problem in many
contexts, including Atom and RSS feeds.

However, I'm not convinced that putting links in their own object,
distinct from everything else, solves this problem at all. The inability
to round-trip extensions is not a problem caused by the serialization
used by the publisher, it's a problem of the data storage format used by
the intermediary. Today many Atom intermediaries will drop off link
elements with a rel "foo" because their underlying data store is limited
to the basic RSS data model... it makes no difference whether your link
is in an atom:link element or a random:foo element.

Furthermore, this only addresses properties that are link-shaped. What's
so special about link properties that makes them deserve their own
little namespace distinct from all of the other properties?

[John Panzer]

Links are special because they're the foundation of the Web. They're
just one level of indirection away from anything, and as we all know,
anything can be solved with a level of indirection: ).

More importantly, they've proved themselves in the wild multiple times
in different formats.

--
--
John Panzer / Google
jpa...@google.com / abstractioneer.org / @jpanzer

[Tatu Saloranta]

On Thu, Apr 29, 2010 at 9:09 AM, Monica Keller <monica...@gmail.com> wrote:
> The proposal should be compatible with poco's json types. That is what we
> have been modeling it after. In particular the address and person elements
>
> On whether we call this JSON or JSON-C either one is fine. I read the
> documentation and it seemed like the reason YouTube in this case needed a
> new name was because they had modeled their JSON after their ATOM feeds and
> wanted to provide a simple and compact representation.  We also are focusing

Yes -- reading through long description it's like their "JSON-C" mean
"actual plain old JSON", and their "JSON" means "JSON-syntax produced
from XML input". Quite confusing, and rather bad naming choice: in
other contexts it would be called "natural JSON" or "native JSON" or
something along those lines.

So I would not use JSON-C in other context as it seems to be specific
to youtube. Better kill bad naming meme before it spreads. :-)

-+ Tatu +-

[Martin Atkins]

John Panzer wrote:
> Links are special because they're the foundation of the Web. They're
> just one level of indirection away from anything, and as we all know,
> anything can be solved with a level of indirection: ).
>
> More importantly, they've proved themselves in the wild multiple times
> in different formats.
>

I agree that links are good and useful, I'm just not sure I agree that
this serialization is right.

What exactly do you expect implementations to do with this special links
object/array that they couldn't do with "normal" JSON properties
containing URLs?

[Darren Bounds]

FYI, we just threw up a pre-production JSON Activity Streams emitter at:

http://api.cliqset.com/as/v1/user/USERNAME/posts

We'll be iterating on it as the schema solidifies. The JSON output isn't pretty so I suggest dropping it in http://jsonformatter.curiousconcept.com/ or the like to parse it as a human. Feel free to mess with it and provide feedback.

Example output for: http://api.cliqset.com/as/v1/user/dbounds/posts

{
  "title":"Activity Stream of: Darren Bounds",
  "id":"https://api.cliqset.com/as/v1/user/dbounds/posts",
  "subject":{
     "id":"dbounds",
     "displayName":"Darren Bounds",
     "permalinkUrl":"http://cliqset.com/dbounds",

     "objectType":[
        "http://activitystrea.ms/schema/1.0/person"
     ]
  },
  "generator":{

     "permalLink":"http://cliqset.com/",
     "displayName":"Cliqset"
  },
  "entries":[
     {
        "permaLink":"http://cliqset.com/user/dbounds/zv5YcgVcetg1ygee",
        "postedTime":"Apr 30, 2010 9:29:30 AM",
        "title":"dbounds liked : factoryjoe shared : billmaher posted a note on Twitter",
        "verb":"http://activitystrea.ms/schema/1.0/like",
        "actor":{
           "id":"http://cliqset.com/user/dbounds",
           "displayName":"Darren Bounds",
           "permaLink":"http://cliqset.com/user/dbounds",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/person"
           ],
           "thumbnail":"http://dynamic.cliqset.com/avatar/dbounds?s\u003d80"
        },
        "object":{
           "summary":"Every asshole who ever chanted \u0027Drill baby drill\u0027 should have to report to the Gulf coast today for cleanup duty",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/note"
           ]
        },
        "serviceProvider":{
           "permalinkUrl":"http://cliqset.com/",
           "displayName":"Cliqset",
           "icon":"https://cliqset-applications.s3.amazonaws.com/605fcb40fef7c5b1ba5fed445ebda34d_icon"
        }
     },
     {
        "permaLink":"http://cliqset.com/user/dbounds/qz9DkKa3tfQtrgee",
        "postedTime":"Apr 30, 2010 8:54:22 AM",
        "title":"dbounds posted a photo on Cliqset",
        "verb":"http://activitystrea.ms/schema/1.0/post",
        "actor":{
           "id":"http://cliqset.com/user/dbounds",
           "displayName":"Darren Bounds",
           "permaLink":"http://cliqset.com/user/dbounds",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/person"
           ],
           "thumbnail":"http://dynamic.cliqset.com/avatar/dbounds?s\u003d80"
        },
        "object":{
           "displayName":"Interesting cloud formations this morning",
           "permaLink":"http://media.cliqset.com/f00f523ee136527e6370afd6cb3ce578.jpg",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/photo"
           ],
           "thumbnail":"http://media.cliqset.com/f00f523ee136527e6370afd6cb3ce578_thumb.jpg"
        },
        "serviceProvider":{
           "permalinkUrl":"http://cliqset.com/",
           "displayName":"Cliqset",
           "icon":"https://cliqset-applications.s3.amazonaws.com/605fcb40fef7c5b1ba5fed445ebda34d_icon"
        }
     },
     {
        "permaLink":"http://cliqset.com/user/dbounds/omExp6d15eCNpgee",
        "postedTime":"Apr 28, 2010 6:44:09 PM",
        "title":"dbounds favorited a video on YouTube",
        "verb":"http://activitystrea.ms/schema/1.0/favorite",
        "actor":{
           "id":"http://cliqset.com/user/dbounds",
           "displayName":"Darren Bounds",
           "permaLink":"http://cliqset.com/user/dbounds",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/person"
           ],
           "thumbnail":"http://dynamic.cliqset.com/avatar/dbounds?s\u003d80"
        },
        "object":{
           "displayName":"\u0027The Expendables\u0027 Trailer HD",
           "permaLink":"http://www.youtube.com/watch?v\u003dC6RU5y2fU6s\u0026feature\u003dyoutube_gdata",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/video"
           ],
           "thumbnail":"http://media.cliqset.com/da623282d8e448240785550c9899b4aa_thumb.jpg"
        },
        "serviceProvider":{
           "permalinkUrl":"http://youtube.com",
           "displayName":"youtube",
           "icon":"http://cliqset-services.s3.amazonaws.com/youtube.png"
        }
     },
     {
        "permaLink":"http://cliqset.com/user/dbounds/3iFDfKRCtSNT8gee",
        "postedTime":"Apr 28, 2010 2:06:39 PM",
        "title":"dbounds posted a note on Twitter",
        "verb":"http://activitystrea.ms/schema/1.0/favorite",
        "actor":{
           "id":"http://cliqset.com/user/dbounds",
           "displayName":"Darren Bounds",
           "permaLink":"http://cliqset.com/user/dbounds",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/person"
           ],
           "thumbnail":"http://dynamic.cliqset.com/avatar/dbounds?s\u003d80"
        },
        "object":{
           "summary":"mcuban: Hey, make sure to check out  @HappyTownTV and my boy  @geoffstults tonight on ABC, 10pm EST. GREAT show. Kill em Geoff",
           "objectTypes":[
              "http://activitystrea.ms/schema/1.0/note"
           ]
        },
        "serviceProvider":{
           "permalinkUrl":"http://twitter.com",
           "displayName":"twitter",
           "icon":"http://cliqset-services.s3.amazonaws.com/twitter.png"
        }
     }
  ]

}

> stoked that we've developed such a diverse community. That said, in
> order to really make good on the value of the work we've done to date,
> we can't make much more progress without also clearly specifying and
> defining how people should consume and publish activities in JSON.
>
> We've had this page for a while, but it's totally meager:
>
> http://wiki.activitystrea.ms/JSON
>
> We need more. And I know that we've been talking about this issue for
> months here on this list, and at our individual companies. I'd like to
> hear some ideas or strawmen on how to make progress here and come
> together on a spec that's simple, elegant, and implementable for JSON
> — and in a reasonable time period.
>
> I don't believe that getting the 1.0 general spec out by the end of
> the month is necessarily achievable at this point, though we've made
> considerable positive progress on it.
>
> Given that — and the improvements that folks like Mart, Will, Monica,
> Rob, and others have contributed to it, I'd like to shift our focus a
> bit to getting defining the JSON representation.
>
> I'm open to thoughts on the best way to move forward here.
>
> Chris
>
> --
> 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.
>
>

--
darren bounds
dar...@cliqset.com

[Monica Keller]

You guys are so fast ! Very cool you probably noticed comments(replies) were missing :) So chatted with John, Will and Chris yesterday and this is what we came up with for comments which allows you to syndicate all or a subset of comments as well as the link where to fetch the remaining comments

// link to comments feed
"comments" = {
  "url": "http://.../comments.json",
  "count": 20,
  "data": [
    {
      "author" = {
    "id": "",
    "displayName": "",
    "profileUrl": "",
  }
  "id": ""
      "content": "...",
      "permalinkUrl": ""
  "postedTime": ""
  "selfLink": ""
    },
{ /* another comment */ }
  ]
}

 Also

1. They liked keeping verb and objectType singular and potentially not using an array if it only has 1 element. I think its ok to have the array so its clear how it can be extended
   
2. They also agreed with not having to specify the full uri for these. So instead of "http://www.activitystrea.ms/schema/1.0/person" you would use "person". For other objectTypes or verbs outside the spec you can use the full path
3. Agreed on having properly grouped arrays . Example: actions - links for humans to interact with the object
   

"actions" : [
  {
    "title": "Post to Google Buzz",
    "url": "http://foo.example.com/",
    "count": 42,
    "verb": "share",
    "icon": "http://g/icon.png"
  },
  {
    "displayName": "Like on Facebook",
    "url": "http://fb/",
    "count": 42,
    "verb": "share",
    "icon": "http://fb/icon.png"
  }
],

In Atom we would have
<link rel="action" href="http://fb/" title="Like on Facebook" activity:count="42" activity:verb="share" activity:icon=""/>
<link rel="action" href="http://g/" title="Post to Buzz" activity:count="42" activity:verb="share" />

Thoughts ?

[John Panzer]

(Note: I had to cut out early from the meeting, so didn't see the comments proposal thinking...)

o I really like the way this makes it easy to include none, all, or an [arbitrary?] subset of the comments.  It's nice and clean.

o How would one represent other things analagous to comments?  Likers (people who liked this), ratings (Joe rated this 3 out of 5), etc.?  This seems extensible.

o Why not use the basic Activity structure for comments?  Comments are activities too.

[Martin Atkins]

On 04/30/2010 04:01 PM, John Panzer wrote:
> o Why not use the basic Activity structure for comments? Comments are
> activities too.
>

Comments are objects. There is an implied activity that the comment was
posted, but I don't really see any point in including that activity here
explicitly since you can infer all of its important properties from the
object alone.

[John Panzer]

On Fri, Apr 30, 2010 at 4:05 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:

On 04/30/2010 04:01 PM, John Panzer wrote:

o Why not use the basic Activity structure for comments?  Comments are
activities too.

Comments are objects.

Wait, they're at least actors + objects, no?

If the equation is Comment = actor + object that'd be fine.  Not sure how that's different from saying that it's an activity with an implied verb=comment?

 

There is an implied activity that the comment was posted, but I don't really see any point in including that activity here explicitly since you can infer all of its important properties from the object alone.

--

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.

[Martin Atkins]

On 04/30/2010 04:11 PM, John Panzer wrote:
> On Fri, Apr 30, 2010 at 4:05 PM, Martin Atkins <ma...@degeneration.co.uk
> <mailto:ma...@degeneration.co.uk>> wrote:
>
> On 04/30/2010 04:01 PM, John Panzer wrote:
>
> o Why not use the basic Activity structure for comments?
> Comments are
> activities too.
>
>
> Comments are objects.
>
>
> Wait, they're at least actors + objects, no?
>
> If the equation is Comment = actor + object that'd be fine. Not sure
> how that's different from saying that it's an activity with an implied
> verb=comment?
>

It's an object with an author.

The implied post activity for an object, which is sadly defined in a
very atom-specific way in the spec right now, is an activity that:

* has the verb "post"
* has a time matching the publication time of the object.
* has an actor matching the author of the object
* has the object as its object.

As part of merging in JSON to the AtomActivity spec we'll probably need
to define the implied activity in conceptual terms rather than in
Atom-specific syntactic terms.

[Monica Keller]

Oh sorry forgot to clarify that this is an example where the feed of a single subject is requested hours after the activities occurred. Those comments are inside the activity

if the subject had commented on someone else's stuff we would include that here like a traditional activity in the "entries" array same for pubsub

Here is an example with a more traditional looking object. This could be good to handle video replies, reviews, etc ?


"replies" = {
  "url": "http://.../replies.json",

  "count": 20,
  "data": [
  {
    "author" = {

    "id": "232323211111",
    "displayName": "Mary",
    "profileUrl": "",
  },
 "object": {
   "id": "2323232"
  "objectType" : "comment",
  "content": "I love your posts Peter",

},
"permalinkUrl": ""
"postedTime": ""
"selfLink": ""
    },
{ /* another comment */ }
  ]
}

[Darren Bounds]

Confused about the use of 'replies' here. Are you making a distinction between comments and replies in this example or is that just a typo?

Also, how would we go about representing additional, but similar concepts such as Likes or Shares?

Darren

--
darren bounds
dar...@cliqset.com

[Monica Keller]

Renamed "comments" to "replies" to suggest you can reply with more than a comment....

[John Panzer]

So there's agreement that generalized, extensible links are useful.

Here are the requirements as I see them.  We want the data to be serialized in a simple way, that's constrained enough for all libraries to pass it through correctly (even static languages like Java), and easily extensible without needing to go through a committee.

The proposal at hand is to allow optional re-use of the existing linking mechanism that works well for HTML, Atom, HTTP, and RSS.  This addresses extensibility; adding a new link relation is a proven extension mechanism and AS-JSON can leverage all existing link relations as appropriate.

The specific syntax can be worked out, but I agree with Martin that having to do a search to retrieve the link(s) for a given relation type is silly (would go against the simple serialization requirement).  You could promote all links to the top level, e.g, { "fooLink": ..., }, but that would work against both "constrained enough" and "extensible" requirements -- libraries would have to have a registry of all link types to know which things are links that can be safely deserialized vs. unknown things that they have to ignore, and such a registry (a) doesn't exist and (b) would need to be hard-coded into each library which (c) would never be up to date.  So, as a very simple mechanism, we define exactly one property name that libraries need to know -- "links" -- and reserve its use for links.

To make things regular and easy to read, you make a totally regular structure and access it like this: links.relvaluename[0..n].href.  In JSON this looks like:

"links" : {

  "relvaluename" : [{"href": "http://example.com"}]

}

Of course, links that the AS spec requires libraries to know about, that are unitary, and that don't have variable MIME types are just left at the top level:

"photoUrl": "http://example.com"

(or you could have an array of IDs, or whatever else the spec calls for -- that's up to the AS JSON spec.)

But if you have a URL link that doesn't fit one of these, you don't need to invent a new top-level name, you just stick it inside the "links" sub-object with your relvalue.  And the relvalues are shared with the rest of the Web, including the Atom syntax of Activity Streams, so you can use the same link extension mechanism no matter what your serialization is.

[Monica Keller]

Hey John
Sorry if I missed something but I am not following your last thread. I don't think we agreed to using a "links" array and to bucket new links there in the simple json response. Obviously any publisher can extend so you guys could support this.

I thought what we had actually agreed was to support specific collections like actions, replies, related objects (related links)

I prefer trying to model links as objects so that publishers can attach all the metadata they have like a name, thumbnail, objectType, etc. Specially anticipating the fact that we are going to have more pages marked up with metadata

So if a link is shared and the Service Provider can parse ogp or microformats or has the url already classified they can give a richer representation...

I feel that if we have a blanket array of links that will encourage syndicating activities with less detail and the links array will end up looking messy with some links being for humans, some for machines

[Kevin Marks]

As we're discussing a JSON version of what was previously an Atom-focused spec, the JSON-C work is relevant. I recommend reading DeWitt's post on this:

http://www.google.com/buzz/dclinton/KLdmwpsYu94/Idiomatic-JSON-data-serialization-using-the-Google

and the JSON style guide is worth a look too:

http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.html

the  talk at i?O last yer on this was also illuminating:

http://www.youtube.com/watch?v=W68XQEiPjEA

the other part of this thinking is a clear way to request just the subset of properties that you care about, rather than the giganto-json approach that, say, twitter takes.

[John Panzer]

Hi Monica,

I may have been reading too much into Martin's "I agree that links are good and useful, I'm just not sure I agree that
this serialization is right."  I hoped that we were all in agreement that it was important to allow any type of link in AS-JSON just like we have with HTML, HTTP, Atom, and RSS.

I've given the main arguments for having generic "links" in core as opposed to an extension in prior emails.  I think they're pretty compelling, but I'd be happy to debate them, if that's the scope of the discussion.

None of this obviates the need for specific collections like actions, replies, etc. where specific constructs including links are specified in core.

-John

[Monica Keller]

Thanks Kevin
We have looked at json-c as well as the json output of Facebook's Graph Api where you can select fields like this

http://graph.facebook.com/arjun/feed?fields=message,picture,comments
or
http://graph.facebook.com/arjun/feed?fields=message,likes

This is part of the reason why json properties help otherwise we would need something like
http://site.com/user/feed?fields=message,picture,links.related.html

So how about this we update the spec with replies,actions and related objects and from json-c we have selfLink and send it out for people to see how it feels. We were bummed the other day that json-c uses the ending link because are using the end "Url". href we didn't like as much but that was just 4 people by then... fun

[David Recordon]

Why not make title part of the object?

On Fri, Apr 30, 2010 at 11:03 AM, Darren Bounds <dar...@cliqset.com> wrote:

[Darren Bounds]

Part of the base object? Not sure it belongs there. It is a necessary part of extended objects though.

"object":{
            "id":"tag:cliqset.com,2010-05-01:/user/dbounds/ROgITLzcb3y7eAee"
            "title":"A pink rifle for Mother\u0027s Day?",
            "description":"",
            "permaLink":"http://media.cliqset.com/9eb344ea0ba16268c3775b2ae68465e3.jpg",
            "thumbnail":"http://media.cliqset.com/9eb344ea0ba16268c3775b2ae68465e3_thumb.jpg",
            "objectTypes":[
               "photo"
            ]
         }

[Martin Atkins]

Monica Keller wrote:
>
> So how about this we update the spec with replies,actions and related
> objects and from json-c we have selfLink and send it out for people to see
> how it feels. We were bummed the other day that json-c uses the ending link
> because are using the end "Url". href we didn't like as much but that was
> just 4 people by then... fun
>

I was using the suffix "Url" to mean "string containing a URL" and the
suffix "Link" to mean "object containing a href property and maybe some
other stuff"... though none of the "Link" ones were actually in the JSON
spec because they only came into play in schema land, such as for image
links which have width/height properties.

[Bob Aman]

> I was using the suffix "Url" to mean "string containing a URL" and the
> suffix "Link" to mean "object containing a href property and maybe some
> other stuff".

+1 to being consistent about this distinction.

-Bob