Question on JSON format, generator entry, custom properties

[Tatu Saloranta]

Quick question on JSON definition
(http://activitystrea.ms/head/json-activity.html): it looks like
location of 'generator' entry differs between text and (non-normative,
I know) sample.
In text it is claimed to belong in 'Activity', but in sample within
main stream item. To me latter makes more sense, for what that is
worth. But it would be good to resolve this.

Also: a related question is this: since there are things that I need
to return along with standard data, I am wondering if there are
planned extension points (generator object would seem like a place to
add extra stuff in, for example)? Properties I need to add relate to
stream itself so I could just wrap AS data as a property within
wrapper, but if there are ways to embed such opaque data that would be
better.
I guess it is also possible that the whole model is viewed as "open
content", meaning that any additional properties would be allowed; but
given that JSON has namespaces it would be difficult to distinguish
such custom extensions from standard properties.

-+ Tatu +-

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

Hi Tatu,

On 05/14/2010 03:40 PM, Tatu Saloranta wrote:
> Quick question on JSON definition
> (http://activitystrea.ms/head/json-activity.html): it looks like
> location of 'generator' entry differs between text and (non-normative,
> I know) sample.
> In text it is claimed to belong in 'Activity', but in sample within
> main stream item. To me latter makes more sense, for what that is
> worth. But it would be good to resolve this.
>

The generator feature (along with a new "service provider" property
designed at StreamCamp) still needs work in the spec. What we have there
right now is really just a placeholder for it.

Thanks for pointing out that it's inconsistently placed, though. The
main thing that motivates the decision about whether something like this
belongs at the activity level or not is whether we expect it to be
carried over when something is favorited or otherwise taken out of
context of its activity. In this case, I think you're right that
generator belongs at the object level because the generator of a thing
is a property of that thing.

To be concrete, generator is expected to be used to represent the client
application or platform application that generated the item. So in the
case of Twitter, you might find "TweetDeck" in here as you do in
Twitter's own API.

> Also: a related question is this: since there are things that I need
> to return along with standard data, I am wondering if there are
> planned extension points (generator object would seem like a place to
> add extra stuff in, for example)? Properties I need to add relate to
> stream itself so I could just wrap AS data as a property within
> wrapper, but if there are ways to embed such opaque data that would be
> better.
> I guess it is also possible that the whole model is viewed as "open
> content", meaning that any additional properties would be allowed; but
> given that JSON has namespaces it would be difficult to distinguish
> such custom extensions from standard properties.
>

Since JSON lacks any formal extension mechanism I'd suggest that if you
are adding truly private things that are only of interest between you
and your specific consumers just invent names that are unlikely to
conflict with other things added in future, perhaps by prefixing them
with your product name.

If you think that what you're designing might be useful to others then
you might consider writing a spec or even just a short proposal and
throwing it out for comment; if you actually document the names you've
used in a way that others can see it then it's less likely that there
will be collisions.

[Tatu Saloranta]

On Fri, May 14, 2010 at 3:58 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:
>
> Hi Tatu,
>
> On 05/14/2010 03:40 PM, Tatu Saloranta wrote:
>>
>> Quick question on JSON definition
>> (http://activitystrea.ms/head/json-activity.html): it looks like
>> location of 'generator' entry differs between text and (non-normative,
>> I know) sample.
>> In text it is claimed to belong in 'Activity', but in sample within
>> main stream item. To me latter makes more sense, for what that is
>> worth. But it would be good to resolve this.
>
> The generator feature (along with a new "service provider" property designed
> at StreamCamp) still needs work in the spec. What we have there right now is
> really just a placeholder for it.

Ok.

> Thanks for pointing out that it's inconsistently placed, though. The main
> thing that motivates the decision about whether something like this belongs
> at the activity level or not is whether we expect it to be carried over when
> something is favorited or otherwise taken out of context of its activity. In
> this case, I think you're right that generator belongs at the object level
> because the generator of a thing is a property of that thing.
>
> To be concrete, generator is expected to be used to represent the client
> application or platform application that generated the item. So in the case
> of Twitter, you might find "TweetDeck" in here as you do in Twitter's own
> API.

Right, that's what I thought. And in my case the whole feed is created
by something I have implemented, and same for all contained activity
entries.

...

> Since JSON lacks any formal extension mechanism I'd suggest that if you are
> adding truly private things that are only of interest between you and your
> specific consumers just invent names that are unlikely to conflict with
> other things added in future, perhaps by prefixing them with your product
> name.

XML does not have any formal extension mechanism itself (Schemas do
provide some of that) so I don't think that is a problem (sure, there
are mechanisms like namespaces [and even basic attribute/element
distinction] that make it somewhat easier to logically divide data --
this is where JSON has issues)

But what I was thinking was more mentioning whether additional
properties are allowed or not (sounds like they are?); and this could
differ between object types.
For example, maybe generator object is thought of as extensible
object, whereas others might not be.
It sounds however that idea is that any object is assumed extensible:
so use of a prefix seems a practical solution.

> If you think that what you're designing might be useful to others then you
> might consider writing a spec or even just a short proposal and throwing it
> out for comment; if you actually document the names you've used in a way
> that others can see it then it's less likely that there will be collisions.

Sure. My needs are quite simple; basically I am exposing chunks of
logical stream (pagination, kind of), but in addition to activities
contained there are also ones that may be filtered out. As such I just
want to pass additional activity id to indicate "head" of stream (last
entry that was skipped and not included in response); which can be
passed back to avoid having to re-read significant portions of
in-memory stream for next result chunk.

I am just starting implementation so I will make sure to ask more
questions & suggest things once I find them.
I like specification updates so far -- JSON spec is now much more
useful, esp. due to sample document.

-+ Tatu +-

[Martin Atkins]

On 05/14/2010 04:32 PM, Tatu Saloranta wrote:
> ...
>> Since JSON lacks any formal extension mechanism I'd suggest that if you are
>> adding truly private things that are only of interest between you and your
>> specific consumers just invent names that are unlikely to conflict with
>> other things added in future, perhaps by prefixing them with your product
>> name.
>
> XML does not have any formal extension mechanism itself (Schemas do
> provide some of that) so I don't think that is a problem (sure, there
> are mechanisms like namespaces [and even basic attribute/element
> distinction] that make it somewhat easier to logically divide data --
> this is where JSON has issues)
>

Sure. I was actually comparing to Atom, which does define several
extension points which Activity Streams itself already uses, and you are
free to continue to extend in your own Activity Streams extensions.

> But what I was thinking was more mentioning whether additional
> properties are allowed or not (sounds like they are?); and this could
> differ between object types.
> For example, maybe generator object is thought of as extensible
> object, whereas others might not be.
> It sounds however that idea is that any object is assumed extensible:
> so use of a prefix seems a practical solution.
>

Yeah, I don't think anyone's going to yell at you for adding extra
properties as long as you name them with an eye to how this might impact
other people extending the spec.

>
> Sure. My needs are quite simple; basically I am exposing chunks of
> logical stream (pagination, kind of), but in addition to activities
> contained there are also ones that may be filtered out. As such I just
> want to pass additional activity id to indicate "head" of stream (last
> entry that was skipped and not included in response); which can be
> passed back to avoid having to re-read significant portions of
> in-memory stream for next result chunk.
>

So if I'm understanding correctly what you're trying to include is some
token that will allow a client to ask for the "next page" of activities.
This seems like something that should be included in the "Activity
Streams JSON API" stack, since I expect lots of publishers will share
this need.

[Tatu Saloranta]

On Fri, May 14, 2010 at 4:52 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:
> On 05/14/2010 04:32 PM, Tatu Saloranta wrote:
>>
>> ...

>> XML does not have any formal extension mechanism itself (Schemas do
>> provide some of that) so I don't think that is a problem (sure, there
>> are mechanisms like namespaces [and even basic attribute/element
>> distinction] that make it somewhat easier to logically divide data --
>> this is where JSON has issues)
>
> Sure. I was actually comparing to Atom, which does define several extension
> points which Activity Streams itself already uses, and you are free to
> continue to extend in your own Activity Streams extensions.

Oh I see, yes, correct.

...

>> Sure. My needs are quite simple; basically I am exposing chunks of
>> logical stream (pagination, kind of), but in addition to activities
>> contained there are also ones that may be filtered out. As such I just
>> want to pass additional activity id to indicate "head" of stream (last
>> entry that was skipped and not included in response); which can be
>> passed back to avoid having to re-read significant portions of
>> in-memory stream for next result chunk.
>>
>
> So if I'm understanding correctly what you're trying to include is some
> token that will allow a client to ask for the "next page" of activities.
> This seems like something that should be included in the "Activity Streams
> JSON API" stack, since I expect lots of publishers will share this need.

Makes sense. Another minor thing I add is 'isThereMore' boolean flag;
since access can be both in 'live' direction (for new events) as well
as historic one (sort of most-recent events view), there's definite
end in one direction. This too is an optimization more than anything;
client can request more, but it can avoid some processing if it knows
no more items are available (either ever, for historic, or right now,
for live data).

It would definitely be interesting to collaborate on Java API side.
And it is going to be easier once I get something working; that's a
good way to see how closely standards and specs cover and support real
world use cases.

-+ Tatu +-

[John Panzer]

How would the continuation token differ, if at all, from the standard
Atom rel=next link?

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

[Tatu Saloranta]

On Fri, May 14, 2010 at 9:23 PM, John Panzer <jpa...@google.com> wrote:
> How would the continuation token differ, if at all, from the standard
> Atom rel=next link?

I will have to read some more on Atom to know for sure -- maybe there
is no difference an I could actually use it? I am starting with an
existing format, and working towards Activity version, so it may be
that I just missed an obvious match.

One possible difference, however, is that token being given can be
out-of-band -- due to filtering, item referenced by 'last processed'
(or 'latest one that is part of the full stream') may not actually be
included in results. But I don't know if that would be problematic per
se.