LAST CALL: Atom Activities 1.0
Will Norris
Please submit any final comments to this mailing list before October 31, 2010.
-will
Singpolyma
mRSS?
Will Norris
that's certainly a valid question, and what one that was discussed at length back in March-ish of this year I think. Martin was working on an Atom Media spec which was an attempt to simplify mRSS and make it a little more atom-like. rel="preview" comes from Atom Media.
A lot of the recent discussions about Activity Streams seem to indicate that many people are favoring the JSON format for APIs, and using the Atom format mainly as a syndication format. In light of that, it may be worth revisiting this at the very least to see if we still feel the same way as we did earlier in the year.
Chris Messina
--
Chris Messina
Open Web Advocate, Google
Personal: http://factoryjoe.com
Follow me on Buzz: http://buzz.google.com/chrismessina
...or Twitter: http://twitter.com/chrismessina
This email is: [ ] shareable [X] ask first [ ] private
John Panzer
a question:
One issue we've run across in implementing this at Google is a tension
between <content> and <target> in the common case of simple posts.
There is duplication if you want to provide the best experience both
to traditional Atom processors, readers, and software, and also
augment with additional metadata. At the moment, there are two
choices, both bad:
(1) Create a summary, say a paragraph, and put that in entry/content,
while putting the full content of the post into the object/summary
element. Good: Not too big. Bad: You can provide only a
partial-content feed for standard Atom processors, libraries, and
readers.
(2) Duplicate the full content in both entry/content and
object/summary. Good: Best experience in terms of data, processors
can access everything they are capable of accessing. Bad: Doubles
the size of every post in the case where the content is substantial
(as it often is for things that are really posts).
We tried (2) and the overhead was unacceptable. We tried (1) and
degraded the experience for people using standard Atom processors.
Since we're only exposing posts at the moment, this means that feeds
that are otherwise completely process-able by standard Atom agents are
nearly useless. We think this is also unacceptable.
There is another choice, (3), which is to drop back to the Implied
Activity Shorthand for these posts. However, this means that we
cannot provide the additional <object> element with AS metadata to
enrich the activity.
So, we want to provide a single feed that provides the best
experience, we want to merge these two fields in a way that is
understandable by both AS-aware processors and standard Atom
processors. This is definitely a special case for the "post" verb,
because that's basically the implied verb in basic Atom. But by the
same token it's worth special casing this.
Proposal: This could be solved with a new inheritance rule for the
Full Activity Entry. For the "post" verb only, if an object does not
contain a <summary>, it inherits its <summary> from the enclosing Atom
entry/content. The current spec says that the Summary of the
activity "is represented by the atom:content element of the entry"
which is fine. This new rule says that the actual object/summary can
also optionally be assumed equal to the Activity Summary, signalled by
the absence of an object/summary element.
This puts the burden on AS-aware processors to copy the entry/content
to the entry/object/summary data if the latter is omitted, in the case
of a "post" verb. We feel this burden is more than justified by the
compatibility and space savings that this change allows.
As a query to the working group: If there are no other options
available, would it be considered out of spec for us to document this
variant and implement it ourselves?
Regards,
John Panzer
Martin Atkins
>
> There is another choice, (3), which is to drop back to the Implied
> Activity Shorthand for these posts. However, this means that we
> cannot provide the additional<object> element with AS metadata to
> enrich the activity.
>
The implied activity shorthand is intended to be the solution to this
problem. I'd be interested to hear more about what you were unable to
represent this way, perhaps with examples.
John Panzer
My understainding: The issue with the implied activity shorthand is
that you cannot provide the <object> tag and therefore cannot provide
any metadata that belongs inside <object>.
Specifically here's an example, in which the entry/content is
truncated to avoid duplicating object/content:
https://www.googleapis.com/buzz/v1/activities/dclinton/@public?pp=1&max-results=1
Why do we need object? We add more object metadata (visibility,
attachment) that does logically belong in object for AS-aware
processors. But we also want this stuff to work smoothly (degrade
gracefully) with non-AS-aware processors. There doesn't seem to be a
way to do that without moving these extensions -- which clearly belong
with the object -- outside the object. Presumably the same would be
true of any non-proprietary extensions to object as well.
If we could just skip providing object/content, with an implied
"inherit from entry/content", we'd be good to go.
>
> --
> 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.
>
>
DeWitt Clinton
Martin Atkins
> On Wed, Nov 3, 2010 at 12:56 PM, Martin Atkins<ma...@degeneration.co.uk> wrote:
>> On 11/03/2010 12:44 PM, John Panzer wrote:
>>>
>>> There is another choice, (3), which is to drop back to the Implied
>>> Activity Shorthand for these posts. However, this means that we
>>> cannot provide the additional<object> element with AS metadata to
>>> enrich the activity.
>>>
>>
>> The implied activity shorthand is intended to be the solution to this
>> problem. I'd be interested to hear more about what you were unable to
>> represent this way, perhaps with examples.
>
> My understainding: The issue with the implied activity shorthand is
> that you cannot provide the<object> tag and therefore cannot provide
> any metadata that belongs inside<object>.
>
When using the implied activity shorthand, the contents of the
atom:entry element are, aside from some exceptions as noted in the spec,
equivalent to the contents of activity:object in the non-shorthand case,
so there should be no loss of fidelity on the object itself. You do,
however, lose fidelity on the activity by virtue of it being implied
rather than explicit.
> Specifically here's an example, in which the entry/content is
> truncated to avoid duplicating object/content:
>
> https://www.googleapis.com/buzz/v1/activities/dclinton/@public?pp=1&max-results=1
>
> Why do we need object? We add more object metadata (visibility,
> attachment) that does logically belong in object for AS-aware
> processors. But we also want this stuff to work smoothly (degrade
> gracefully) with non-AS-aware processors. There doesn't seem to be a
> way to do that without moving these extensions -- which clearly belong
> with the object -- outside the object. Presumably the same would be
> true of any non-proprietary extensions to object as well.
>
> If we could just skip providing object/content, with an implied
> "inherit from entry/content", we'd be good to go.
>
If you define the meaning of those extension elements in terms of the
activity streams data model (in other words, define them as extension
components of the object construct and define their Atom serialization
as a mapping to those components from a container element) then there's
no reason why you can't include them as direct children of the
atom:entry element in the implied activity shorthand case.
Of course, in that case since the activity is implied as defined in the
spec the activity itself can't carry extensions like your
buzz:visibility element, so you could consider respecifying such
extensions to be on the object where that makes sense. If they don't
make sense as properties of object then the implied activity shorthand
is of course not appropriate.
John Panzer
This seems extremely complicated, especially when you consider that
these also need to be present for non-shorthand case, in which case
they would be under activity:object. So processors who are AS-aware
would need to know to look for these in two different places.
Seems to me much more straightforward to have AS-aware processors fall
back to atom:content if object/content is missing, as a general rule.
>
> Of course, in that case since the activity is implied as defined in the spec
> the activity itself can't carry extensions like your buzz:visibility
> element, so you could consider respecifying such extensions to be on the
> object where that makes sense. If they don't make sense as properties of
> object then the implied activity shorthand is of course not appropriate.
>
>
>
Martin Atkins
>
> This seems extremely complicated, especially when you consider that
> these also need to be present for non-shorthand case, in which case
> they would be under activity:object. So processors who are AS-aware
> would need to know to look for these in two different places.
>
> Seems to me much more straightforward to have AS-aware processors fall
> back to atom:content if object/content is missing, as a general rule.
>
AS-aware process already need to handle these two cases if they support
the implied activity shorthand.
The closest thing we have to a reference implementation, which is the
python parser library that backs the activity streams tester tool,
implements this by having a function which takes an XML element and a
parse mode and which returns a python manifestation of an activity
streams object construct.
You can see this here:
https://github.com/apparentlymart/activity-streams-python/blob/master/activitystreams/atom.py#L131
The "mode" enumeration represents the different minor variations on
object processing described in section 3.2 of the spec.
There is another function, which appears at line 70, that is responsible
for recognizing whether it has a full activity entry or an implied
activity shorthand entry and passing the right element into the object
processor. The object processor is, aside from the slight variations in
syntax for the core components as described in the spec, agnostic about
whether it was handed an atom:entry element, an activity:object element,
an atom:author element, or anything else.
I think this separation of concerns with activity vs. object parsing is
important for any good activity streams implementation, and the special
handling of the implied activity shorthand took only an extra five lines
of code or so in my implementation. If I added handling for the buzz
extension elements to the object processing function then they would
automatically be supported in both contexts.
With all of that said, my only concern with your proposal is whether it
creates sub-optimal behavior in any legitimate case. Your proposal
effectively requires all object elements to have an atom:content
element, whether explit or implied, which might be okay but is a new
requirement that not all existing implementations may meet at this
point, if they are representing object types for which atom:content has
no defined meaning.
John Panzer
Martin Atkins
At least my plan (as the person who rebooted the JSON spec to be
self-contained rather than referencing the Atom spec) was that the JSON
spec would actually be Activity Streams 2.0, with an extended data model
vs AtomActivity, which is effectively Activity Streams 1.0.
It's really only called json-activity for historical reasons.
This new spec actually had JSON, Atom and RSS serializations defined
initially, but given that interest seemed to be waning in Atom and RSS
and it was becoming an albatross for data model development -- each time
we wanted to add a new concept we'd spend an hour bikeshedding about how
it should be represented in Atom.
At least to my mind, the plan was always to see how AtomActivity fared
in the marketplace and if it actually started to gain adoption the
Activity Streams 2.0 spec would have an Atom serialization defined too.
At it turned out, AtomActivity didn't get published as soon as I'd hoped
and so we now actually have two compating specifications that are
nearing final at once, despite the fact that the latter spec was
actually conceived as a *successor* of the former, not a sibling. The
fact that the latter spec is a superset of the former was intentional.
Daniel Chapman
Full (JSON).
Then we aim the Atom spec at general consumption, e.g. sites can have
it as their public site feed, so it should be readable in a non AS
reader also.
The JSON spec can then be aimed at dedicated API processors, and can
include more detailed information.
I wasn't in any of the previous discussions, but I can see how it
would be possible to go in circles deciding how best to define
something in Atom that is as simple as giving it a name in JSON. Such
as whether to include summaries/counts or links in regards to replies.
With JSON we can more easily allow for both, and implementers can just
choose which one is appropriate for their needs.
If the JSON spec doesn't need to worry about mapping directly to the
Atom one, it frees it up a lot.
But calling the Atom one 1.0 feels to me like it cheapens it a little,
as it implies that it is out of date, which is certainly isn't. It is
still very useful.
Martin Atkins
>
> But calling the Atom one 1.0 feels to me like it cheapens it a little,
> as it implies that it is out of date, which is certainly isn't. It is
> still very useful.
>
If that is true, then we should add an Atom serialization (and possibly
also an RSS serialization) to the 2.0 (json-activity) spec.
In my opinion, there should only be one spec at a time defining the
activity streams data model. AtomActivity defines the the first version
of the activity streams data model, and json-activity defines a
successor data model that extends it.
The original goal was that this "AtomActivity" spec would draw a line in
the sand and pin down the stuff that is uncontroversial and has been
implemented by some apps for a while now, giving implementers the basic
functionality to implement against while we work on the more complicated
features for the next version. We failed to actually follow through on
that goal, since the AtomActivity spec still isn't finalized several
months later.
Given where we stand today, I would propose the following plan:
* Either finalize AtomActivity as-is in the next week or so, or just
throw it away in favor of the next step.
* Start thinking of json-activity as the version 2 spec rather than
the JSON spec.
* Decide whether we want to continue supporting Atom and RSS
serializations moving forward. If so, add sections defining them to the
version 2 spec in addition to the JSON serialization.
* Take the features that we are still working on, such as inline
replies and reactions, out into their own extension spec so we can
continue to work on them without delaying the finalization of the
version 2 spec.
* Finalize the version 2 spec as the current state of the art,
successor to and backwards-compatible replacement for AtomActivity.
Eric
it is then makes sense that ATOM 1.0 be released before JSON 2.0,
which could delay finalizing JSON 2.0 unnecessarily, especially since
the JSON work isn't dependent on the ATOM work.
Given the state of the JSON spec, I feel that it is ready for final
discussions, cleanup work, and a solid cut. It's crucial we give
implementors a stable release to build on top of. One example is
OpenSocial, which needs to point to a stable release to include
ActivityStreams.
While I'm not strongly opinionated on the versioning, I don't want to
see JSON 2.0 delayed in lieu of the ATOM work.
- Eric W.