New Draft Specs
Martin Atkins
Hi Folks,
I just updated the copies of the specs on my site to the latest revision
in my git repository. The URLs are still the same:
http://martin.atkins.me.uk/specs/activitystreams/atomactivity
http://martin.atkins.me.uk/specs/activitystreams/activityschema
This isn't really what I originally planned for Draft 2, but I thought
I'd release it because it's been a while since the last drafts.
Much of the work here is on the schema spec, expanding the vocabulary to
include additional verbs and object types. A few key ones are missing
(events, for example) either because there is a lack of clarity on how
they should be represented in Atom or because they depend on additions
to the schema spec that I've not yet made.
I still need to do some additional work to the syntax spec
(atomactivity) to support:
* activity:actor as a richer alternative to atom:author
* Some kind of solution for indirect objects. I'm currently thinking
of just adding activity:target (since the term "indirect object" doesn't
resonate for most folks) in addition to activity:object, though I have
some concerns about adding another dimension to our already
two-dimensional activities and worsening the existing combinatorial
problems with rendering activities into natural language sentences.
* Some other feedback I recieved that I've not yet incorporated.
NickLothian
discussion is happening or should I be going somewhere else?
Here's a few comments from my point of view.
1) Why are there two documents? The relationship between the two
documents is not expressed clearly anywhere, and I can't see why the
shouldn't be merged (eg, verbs are in one spec, and Object types in
another).
2) These specs seem to cover a lot of the same area as the OpenSocial
Atom based REST API for Activity. These specs intend to carry
additional machine-readable data as a payload, but it would be good to
make some kind of effort to be compatible with the OpenSocial API, and
seem them explicitly referenced.
For http://martin.atkins.me.uk/specs/activitystreams/atomactivity
3) Section 3 "Activity Concepts" probably should reference Section 6.1
"Activity Title, Summary and Detail", where it says "It is expected
that in many cases consumers of Activity Feeds will use them to turn
machine readable descriptions of Activities into human-readable
sentences such as "Joanne posted a Photo: 'My Cat'". ". When I read
that sentence (before completing the document) I got very concerned
that it had dropped the requirement for a human readable title and
summary.
4) Section 6 "Activity Entries" would make sense to come earlier in
the document - I think after section 4 and before section 5. At the
moment you really need to read section 6 to understand section 5 at
all (eg: " Any entry that does not meet the criteria for being an
Activity Entry as described in Section 6 is considered an Object Entry
by this specification")
5) Section 5.1 "The activity:object-type Extension Element"
- "Where multiple types are used, all types MUST be generalizaions or
specializations of one another." How are generalizations and
specializations defined?
- "Activity feed processors SHOULD use the most specific Object Type
that they understand within each entry." - how does the feed processor
know what Object Type is the most specific? I see that the other spec
defines some as more specific than others, so does this mean this
logic needs to be hard-coded in the processor?
- "If none of the Object Types are understood by the processor, the
processor MAY use other information to infer the Object Type, or
otherwise the processor MUST act as if no activity:object-type element
is present." - the "MUST" part here seems to be in conflict with the
previous "MAY"
- " no activity:object-type element is present, the Object has no
defined type. Processors SHOULD refer to such Objects only by their
titles." - In the previous sentence it said the processor MAY try to
infer an Object Type, and that it MUST act as if it has not type, and
here is says it SHOULD behave in a defined way. I don't think this is
consistent.
6) Section 5.3 "Implied Activity" - why is this before Section 6
"Activity Entries". Surely it makes more sense to specify the non-
implied version of the activity before the implied version?
7) 6.3. "Activity Link" - "An Activity Entry should include an
atom:link " - "should" be capitalized "SHOULD".
8) 6.4. "The activity:verb Extension Element"
- "Where multiple verbs are used, all verbs MUST be generalizations or
specializations of one another." - how is this defined?
- "Activity feed processors SHOULD use the most specific Verb that
they understand within each entry." - how the processor know which is
the most specific?
- "If none of the Activity's Verbs are understood by the processor,
the processor MAY use other information to infer the Verb, or the
processor MAY use the content of the atom:title, atom:summary and/or
atom:content to obtain a sentence describing the Activity." - I much
prefer this logic to the logic in section 5.3
For http://martin.atkins.me.uk/specs/activitystreams/activityschema
9) Section 4 Base Object Types
This is a real mix of good stuff, and things which need to be cut.
For example, the image and video object seem quite well specified
(building on the media:rss spec), but something like "TV Episode" is
pretty much meaningless. (Does it mean it had to be on broadcast tv?
What is the difference between this and an episodic YouTube video). If
that is included, then shouldn't we also have specialized types for
newspapers, books, book chapters, etc etc...
How do people see this being used, especially the specialization where
the subclass has no additional attributes?
10) Section 4.15:
See section 11 of http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol.
Why should this be specified differently?
Regards
Nick Lothian
On Feb 28, 10:47 am, Martin Atkins <m...@degeneration.co.uk> wrote:
> Hi Folks,
>
> I just updated the copies of the specs on my site to the latest revision
> in my git repository. The URLs are still the same:
>
honor gunday
I am mobile and I could only view the documents as much as g1 allows me to. It seems to me, as I understand correctly the different categories of actions are being standardized in verbality. I would like to raise an issue about internationalization. Folks at facebook who have done an excellent job at internationalizing the platform can speak to this better I think but if the base action verbs and objects are being indexed and becoming the standard and if they are really going to be a standard. It should be easy to internationalize from a grammatic perspective.
For example suffixative languages such as Finnish, Hungarian, Estonian, Turkish, Korean, Japanese, Central Asian Languages might have order problems with object-subject relationship during translation.
Slavic languages typically have a problem with plurals because the word base changes when there is more than 1. But changes again when there is more than 5. For example.
Again. If it's a standard. Internationalization feedback would come in handy imho.
Hope it helps.
Honor Gunday
On Feb 28, 10:47 am, Martin Atkins <m...@degeneration.co.uk> wrote: > Hi Folks, > > I just update...
> http://martin.atkins.me.uk/specs/activitystreams/atomactivityhttp://martin.atkins.me.uk/specs/activitystreams/activityschema
> > This isn't really what I originally planned for Draft 2, but I thought > I'd release it because ...
Martin Atkins
NickLothian wrote:
> I haven't seen any feedback on these specs here. Is this where
> discussion is happening or should I be going somewhere else?
This is a fine place to post feedback. Thanks.
> Here's a few comments from my point of view.
>
> 1) Why are there two documents? The relationship between the two
> documents is not expressed clearly anywhere, and I can't see why the
> shouldn't be merged (eg, verbs are in one spec, and Object types in
> another).
I think of them as being the syntax spec and the schema spec. The syntax
spec defines what elements we've added to Atom and RSS, and the schema
spec defines how to use the extension elements along with other Atom
markup to describe specific activity and object types.
> 2) These specs seem to cover a lot of the same area as the OpenSocial
> Atom based REST API for Activity. These specs intend to carry
> additional machine-readable data as a payload, but it would be good to
> make some kind of effort to be compatible with the OpenSocial API, and
> seem them explicitly referenced.
>
It was my understanding that OpenSocial was looking at using Atom for
activities, but I was not aware that they had yet defined an Atom
extension for doing so. Am I mistaken?
If not, it would be good if the OpenSocial folks would participate here
so that OpenSocial can reference the general Activity Streams specs
rather than the other way around.
> For http://martin.atkins.me.uk/specs/activitystreams/atomactivity
>
> 3) Section 3 "Activity Concepts" probably should reference Section 6.1
> "Activity Title, Summary and Detail", where it says "It is expected
> that in many cases consumers of Activity Feeds will use them to turn
> machine readable descriptions of Activities into human-readable
> sentences such as "Joanne posted a Photo: 'My Cat'". ". When I read
> that sentence (before completing the document) I got very concerned
> that it had dropped the requirement for a human readable title and
> summary.
>
> 4) Section 6 "Activity Entries" would make sense to come earlier in
> the document - I think after section 4 and before section 5. At the
> moment you really need to read section 6 to understand section 5 at
> all (eg: " Any entry that does not meet the criteria for being an
> Activity Entry as described in Section 6 is considered an Object Entry
> by this specification")
>
This draft re-arranged some sections so that object entries were defined
first. This is because it's expected that most existing publishers today
will be publishing object entries rather than activity entries. Only
activity aggregator services (e.g. FriendFeed and Plaxo) tend to publish
actual activity entries (which describe an activity explicitly rather
than an object with an implied activity) today.
However, I agree that some more editorial work is required to make the
document make sense this way around. There is some text left over from
when activity entries came first.
> 5) Section 5.1 "The activity:object-type Extension Element"
>
> - "Where multiple types are used, all types MUST be generalizaions or
> specializations of one another." How are generalizations and
> specializations defined?
This is to be defined by schema specifications and is intentionally
undefined here. However, I guess it could explicitly say that it is to
be defined by schemata.
> - "Activity feed processors SHOULD use the most specific Object Type
> that they understand within each entry." - how does the feed processor
> know what Object Type is the most specific? I see that the other spec
> defines some as more specific than others, so does this mean this
> logic needs to be hard-coded in the processor?
Yes, it is assumed that a particular activity processor will have a
fixed set of verbs and object types that it understands and part of that
understanding is knowledge of the relationships between them.
> - "If none of the Object Types are understood by the processor, the
> processor MAY use other information to infer the Object Type, or
> otherwise the processor MUST act as if no activity:object-type element
> is present." - the "MUST" part here seems to be in conflict with the
> previous "MAY"
The MUST only applies if there is no "other information". However, I
agree that this is not clear and sould be worded more carefully.
> - " no activity:object-type element is present, the Object has no
> defined type. Processors SHOULD refer to such Objects only by their
> titles." - In the previous sentence it said the processor MAY try to
> infer an Object Type, and that it MUST act as if it has not type, and
> here is says it SHOULD behave in a defined way. I don't think this is
> consistent.
What this sentence is trying to say is "if there is no recognized type"
rather than "if there is no activity:object-type element". In other
words, it's talking about the set of object-type elements that remain
after removing those that are not recognised and adding those determined
by "other information". Again, I agree that this is not particularly clear.
> 6) Section 5.3 "Implied Activity" - why is this before Section 6
> "Activity Entries". Surely it makes more sense to specify the non-
> implied version of the activity before the implied version?
"Implied Activity" is part of the definition of "Object Entries", though
I suppose I agree that it's strange to define the implicit approach
before the explicit approach. I'm not really sure how to revise this
while keeping "Object Entries" before "Activity Entries", though.
> 7) 6.3. "Activity Link" - "An Activity Entry should include an
> atom:link " - "should" be capitalized "SHOULD".
Agreed.
> 8) 6.4. "The activity:verb Extension Element"
>
> - "Where multiple verbs are used, all verbs MUST be generalizations or
> specializations of one another." - how is this defined?
>
> - "Activity feed processors SHOULD use the most specific Verb that
> they understand within each entry." - how the processor know which is
> the most specific?
>
> - "If none of the Activity's Verbs are understood by the processor,
> the processor MAY use other information to infer the Verb, or the
> processor MAY use the content of the atom:title, atom:summary and/or
> atom:content to obtain a sentence describing the Activity." - I much
> prefer this logic to the logic in section 5.3
>
The same approach applies here as for object types.
The difference is that the fallback behavior for no recognised verb is
much more severe than for no recognised object type, since the
processor's only real option is to fall back on the text provided by the
publisher, which is likely to be inconsistent with the text that an
activity aggregator would normally generate, and may be in the wrong
language.
>
> For http://martin.atkins.me.uk/specs/activitystreams/activityschema
>
> 9) Section 4 Base Object Types
>
> This is a real mix of good stuff, and things which need to be cut.
>
> For example, the image and video object seem quite well specified
> (building on the media:rss spec), but something like "TV Episode" is
> pretty much meaningless. (Does it mean it had to be on broadcast tv?
> What is the difference between this and an episodic YouTube video). If
> that is included, then shouldn't we also have specialized types for
> newspapers, books, book chapters, etc etc...
>
> How do people see this being used, especially the specialization where
> the subclass has no additional attributes?
Many of these distinctions exist only so that aggregators can render a
more specific sentence.
For example, an activity aggregator may wish to say "Martin liked a TV
Show" rather than "Martin liked a Video".
They do not have strong semantics and are really just to allow a
publisher to tweak the rendering in activity aggregators without the
aggregators having to hard-code the fact that, for example, the videos
on Hulu are TV Shows or Movies.
A processor that is not rendering these things for humans can probably
ignore the distinction. However, rendering things to humans in a
FriendFeed-like aggregator is the main focus of this work right now.
>
> 10) Section 4.15:
>
> See section 11 of http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol.
> Why should this be specified differently?
>
The current plan is for people to be represented using the Portable
Contacts schema adapted to be at home in Atom. Since Portable Contacts
is itself based on OpenSocial's schema, the result will probably look a
lot like what's described in that document.
However, I believe that the issue of how to describe people in Atom is
orthogonal to activities, so I'm hoping that someone will author a
specification for describing people in Atom which the activity schema
spec can then refer to. What's in there right now is the bare minimum
required to render an activity like "Martin is now friends with Joe",
and invents nothing new beyond the standard Atom elements.
Thanks for taking the time to send this feedback. I'll take this all
into consideration for the next draft.
NickLothian
On Mar 5, 12:52 pm, Martin Atkins <m...@degeneration.co.uk> wrote:
> NickLothian wrote:
> > I haven't seen any feedback on these specs here. Is this where
> > discussion is happening or should I be going somewhere else?
>
> This is a fine place to post feedback. Thanks.
>
> > Here's a few comments from my point of view.
>
> > 1) Why are there two documents? The relationship between the two
> > documents is not expressed clearly anywhere, and I can't see why the
> > shouldn't be merged (eg, verbs are in one spec, and Object types in
> > another).
>
> I think of them as being the syntax spec and the schema spec. The syntax
> spec defines what elements we've added to Atom and RSS, and the schema
> spec defines how to use the extension elements along with other Atom
> markup to describe specific activity and object types.
>
> > 2) These specs seem to cover a lot of the same area as the OpenSocial
> > Atom based REST API for Activity. These specs intend to carry
> > additional machine-readable data as a payload, but it would be good to
> > make some kind of effort to be compatible with the OpenSocial API, and
> > seem them explicitly referenced.
>
> It was my understanding that OpenSocial was looking at using Atom for
> activities, but I was not aware that they had yet defined an Atom
> extension for doing so. Am I mistaken?
>
Section 2
> If not, it would be good if the OpenSocial folks would participate here
> so that OpenSocial can reference the general Activity Streams specs
> rather than the other way around.
>
>
they do have a specification which has been around for a while and is
fairly widely deployed.
[snip]
> > 5) Section 5.1 "The activity:object-type Extension Element"
>
> > - "Where multiple types are used, all types MUST be generalizaions or
> > specializations of one another." How are generalizations and
> > specializations defined?
>
> This is to be defined by schema specifications and is intentionally
> undefined here. However, I guess it could explicitly say that it is to
> be defined by schemata.
>
general to most specialized. This makes the consumer code slightly
easier, and doesn't put a big burden on the consumer (as presumably it
already has the knowledge of the specialized object types).
I think that then the generalization/specialization spectrum might be
better defined as "least preferred/most preferred" on the producer
side.
The case I'm thinking of is where there are two different
specializations of (say) Article defined externally. Consumers have
little way of knowing which of those represents the activity the best
if both are in the feed, but the Producer does have that knowledge
> > - "Activity feed processors SHOULD use the most specific Object Type
> > that they understand within each entry." - how does the feed processor
> > know what Object Type is the most specific? I see that the other spec
> > defines some as more specific than others, so does this mean this
> > logic needs to be hard-coded in the processor?
>
> Yes, it is assumed that a particular activity processor will have a
> fixed set of verbs and object types that it understands and part of that
> understanding is knowledge of the relationships between them.
>
[snip]
> > 6) Section 5.3 "Implied Activity" - why is this before Section 6
> > "Activity Entries". Surely it makes more sense to specify the non-
> > implied version of the activity before the implied version?
>
> "Implied Activity" is part of the definition of "Object Entries", though
> I suppose I agree that it's strange to define the implicit approach
> before the explicit approach. I'm not really sure how to revise this
> while keeping "Object Entries" before "Activity Entries", though.
>
Atom Entry processing" or something?
[snip]
>
> > Forhttp://martin.atkins.me.uk/specs/activitystreams/activityschema
> > 9) Section 4 Base Object Types
>
> > This is a real mix of good stuff, and things which need to be cut.
>
> > For example, the image and video object seem quite well specified
> > (building on the media:rss spec), but something like "TV Episode" is
> > pretty much meaningless. (Does it mean it had to be on broadcast tv?
> > What is the difference between this and an episodic YouTube video). If
> > that is included, then shouldn't we also have specialized types for
> > newspapers, books, book chapters, etc etc...
>
> > How do people see this being used, especially the specialization where
> > the subclass has no additional attributes?
>
> Many of these distinctions exist only so that aggregators can render a
> more specific sentence.
>
> For example, an activity aggregator may wish to say "Martin liked a TV
> Show" rather than "Martin liked a Video".
>
> They do not have strong semantics and are really just to allow a
> publisher to tweak the rendering in activity aggregators without the
> aggregators having to hard-code the fact that, for example, the videos
> on Hulu are TV Shows or Movies.
>
> A processor that is not rendering these things for humans can probably
> ignore the distinction. However, rendering things to humans in a
> FriendFeed-like aggregator is the main focus of this work right now.
>
and some are underspecified. I think it would be much better to cut
those out and concentrate getting the raw base types well speced. I
generally find that having something incorrectly speced is worse than
having it not speced at all, and the extension model of this spec
means that it should be pretty simple for someone to put out (for
example) a TV episode object spec. If an extension is wrong it's much
easier to replace it than the base spec.
>
>
> > 10) Section 4.15:
>
> > See section 11 ofhttp://www.opensocial.org/Technical-Resources/opensocial-spec-v081/re....
>
> The current plan is for people to be represented using the Portable
> Contacts schema adapted to be at home in Atom. Since Portable Contacts
> is itself based on OpenSocial's schema, the result will probably look a
> lot like what's described in that document.
>
> However, I believe that the issue of how to describe people in Atom is
> orthogonal to activities, so I'm hoping that someone will author a
> specification for describing people in Atom which the activity schema
> spec can then refer to. What's in there right now is the bare minimum
> required to render an activity like "Martin is now friends with Joe",
> and invents nothing new beyond the standard Atom elements.
>
> Thanks for taking the time to send this feedback. I'll take this all
> into consideration for the next draft.
Martin Atkins
>
>
> Is there somewhere where issues are tracked?
I have been tracking issues on the following tracker:
http://mart.lighthouseapp.com/projects/23195-activity-streams-specs/tickets
However, this particular application has proven less than ideal and so
I'm no longer really using it in anger with new issues. My current
workflow is simply to flag email messages in my email account, but I'm
open to suggestions for alternative hosted issue tracking software.
NickLothian
On Mar 5, 2:59 pm, Martin Atkins <m...@degeneration.co.uk> wrote:
> NickLothian wrote:
>
> > Is there somewhere where issues are tracked?
>
> However, this particular application has proven less than ideal and so
> I'm no longer really using it in anger with new issues. My current
> workflow is simply to flag email messages in my email account, but I'm
> open to suggestions for alternative hosted issue tracking software.
is sufficient, and it would be a better place to upload example files
etc than here.
Monica Keller
contain enough metadata with which to write a generic aggregator and
coalesce activities from multiple providers:
<entry xmlns="http://www.w3.org/2005/Atom"> <category term="status"/
> <id>http://example.org/activities/example.org:87ead8dead6beef/self/
af3778</id> <title><a href="foo">some activity</a></title>
<summary>Some details for some activity</summary>
<updated>2008-02-20T23:35:37.266Z</updated> <link rel="self"
type="application/atom+xml" href="http://api.example.org/activity/
feeds/.../af3778"/> <author><uri>urn:guid:example.org:
34KJDCSKJN2HHF0DW20394</uri></author> <content> <activity
xmlns="http://ns.opensocial.org/2008/opensocial">
<bodyId>383777272</bodyId> </activity> </content></entry>
I have been working with our MDP team which has an activity template
editor to get them to add verbs and objects types which are really
predefined templates so our developers can just say this app raises a
Post Bookmark activity and when they raise the activity they can just
pass the expected variables for the appropriate template.
What do you guys think ? I am sure the opensocial folks have opinions
but I cant find much on the opensocial google group
Thanks
On Mar 4, 8:32 pm, NickLothian <nick.loth...@gmail.com> wrote:
> On Mar 5, 12:52 pm, Martin Atkins <m...@degeneration.co.uk> wrote:
>
>
>
>
>
> > NickLothian wrote:
> > > I haven't seen any feedback on these specs here. Is this where
> > > discussion is happening or should I be going somewhere else?
>
> > This is a fine place to post feedback. Thanks.
>
> > > Here's a few comments from my point of view.
>
> > > 1) Why are there two documents? The relationship between the two
> > > documents is not expressed clearly anywhere, and I can't see why the
> > > shouldn't be merged (eg, verbs are in one spec, and Object types in
> > > another).
>
> > I think of them as being the syntax spec and the schema spec. The syntax
> > spec defines what elements we've added to Atom and RSS, and the schema
> > spec defines how to use the extension elements along with other Atom
> > markup to describe specific activity and object types.
>
> > > 2) These specs seem to cover a lot of the same area as the OpenSocial
> > > Atom based REST API for Activity. These specs intend to carry
> > > additional machine-readable data as a payload, but it would be good to
> > > make some kind of effort to be compatible with the OpenSocial API, and
> > > seem them explicitly referenced.
>
> > It was my understanding that OpenSocial was looking at using Atom for
> > activities, but I was not aware that they had yet defined an Atom
> > extension for doing so. Am I mistaken?
>
>
> - Show quoted text -- Hide quoted text -
>
> - Show quoted text -- Hide quoted text -
>
> - Show quoted text -