.
[responses]
Snell, J., "Responses for Activity Streams", March 2012,
.
Appendix A. Acknowledgements
The author wishes to thank the Activity Streams community and
implementers for their support, encouragement, and enthusiasm
including but not limited to: Abdul Qabiz, Adina Levin, Adrian Chan,
Adriana Javier, Alan Hoffman, Alex Kessinger, Alexander Ovchinnikov,
Alexander Zhuravlev, Alexandre Loureiro Solleiro, Amy Walgenbach,
Andres Vidal, Angel Robert Marquez, Ari Steinberg, Arjan
Scherpenisse, Arne Roomann-Kurrik, Beau Lebens, Ben Hedrington, Ben
Metcalfe, Ben Werdmuller, Benjamin Goering, Bill de hOra, Bo Xing,
Bob Aman, Bob Wyman, Brett Slatkin, Brian Walsh, Brynn Evans, Charlie
Cauthen, Chris Chabot, Chris Messina, Chris Toomey, Christian
Crumlish, Dan Brickley, Dan Scott, Daniel Chapman, Danny Ayers, Dare
Obasanjo, Darren Bounds, David Cramer, David Nelson, David Recordon,
DeWitt Clinton, Douglas Pearce, Ed Summers, Elias Bizannes, Elisabeth
Norris, Eric Marcoullier, Eric Woods, Evan Prodromou, Gee-Hsien
Chuang, Greg Biggers, Gregory Foster, Henry Saputra, Hillary Madsen,
Howard Liptzin, Hung Tran, Ian Kennedy, Ian Mulvany, Ivan Pulleyn,
Jacob Kim, James Falkner, James Pike, James Walker, Jason Kahn, Jason
Kantz, Jeff Kunins, Jeff Martin, Jian Lin, Johannes Ernst, John
Panzer, Jon Lebkowsky, Jon Paul Davies, Jonathan Coffman, Jonathan
Dugan, Joseph Boyle, Joseph Holsten, Joseph Smarr, Josh Brewer, Jud
Valeski, Julien Chaumond, Julien Genestoux, Jyri Engestroem, Kaliya
Snell Expires May 08, 2014 [Page 30]
Internet-Draft ActivityStreams November 2013
Hamlin, Kevin Marks, Laurent Eschenauer, Laurie Voss, Leah Culver,
Libby Miller, Manu Mukerji, Mark Weitzel, Marko Degenkolb, Marshall
Kirkpatrick, Martin Atkins, Martin Svensson, Marty Alchin, Mary
Hoder, Matt Leventi, Matt Wilkinson, Matthias Mueller-Prove, Max
Engel, Max Wegmueller, Melvin Carvalho, Michael Buckbee, Michael
Chan, Michael Richardson, Michael Sullivan, Mike Macgirvin, Mislav
Marohnić, Mo Jangda, Monica Wilkinson, Nate Benes, NeilFred
Picciotto, Nick Howard, Nick Lothian, Nissan Dookeran, Nitya
Narasimhan, Pablo Martin, Padraic Brady, Pat G. Cappalaere, Patrick
Aljord, Peter Ferne, Peter Reiser, Peter Saint-Andre, Phil Wolff,
Philip (flip) Kromer, Richard Cunningham, Richard Zhao, Rick
Severson, Robert Hall, Robert Langbert, Robert Dolin, Robin Cover,
Ryan Boyd, Sam Sethi, Scott Raymond, Scott Seely, Simon Grant, Simon
Wistow, Stephen Garcia, Stephen Sisk, Stephen Paul Weber, Steve Ivy,
Steve Midgley, Steven Livingstone-Perez, Sylvain Carle, Sylvain
Hellegouarch, Tantek Celik, Tatu Saloranta, Tim Moore, Timothy Young,
Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley,
and Zach Shepherd.
Appendix B. Processing as JSON-LD
While the Activity Streams 2.0 syntax is designed to be compatible
with JSON-LD, in order to successfully process an Activity Streams
document as JSON-LD, a "@context" description needs to be provided.
The following example illustrates an Activity Streams document that
can be processed as JSON-LD containing Schema.org defined metadata
elements.
{
"@context": {
"@vocab": "http://activitystrea.ms/spec/2.0/",
"verb": "@type",
"objectType": "@type",
"id": "@id",
"actor": "http://schema.org/Action/performedBy",
"object": "http://schema.org/BuyAction/bought",
"purchase": "http://schema.org/BuyAction",
"person": "http://schema.org/Person",
"book": "http://schema.org/Book"
},
"verb" : "purchase",
"id" : "urn:example:purchase:123/abc",
"displayName": "John purchased 'A Tale of Two Cities'",
"startTime" : "2013-04-02T12:31Z",
"endTime" : "2013-04-02T12:31Z",
"actor": {
"objectType": "person",
"displayName": "John Doe"
Snell Expires May 08, 2014 [Page 31]
Internet-Draft ActivityStreams November 2013
},
"object": {
"objectType": "book",
"displayName": "A Tale of Two Cities"
}
}
Appendix C. Motivational Use Cases
This specification defines a number of syntax changes relative to the
JSON Activity Streams 1.0 specification. The sections that follow
describe some of the general motivations for these changes with
illustrative examples.
C.1. Internationalization (i18n)
The JSON Activity Streams 1.0 syntax has no inherent notion of a
"language context". That is, the core syntax has no internal
mechanism a publisher can use to identify the language used when
constructing the Activity Streams document. Nor are there any
existing mechanisms at the JSON syntax level that an Activity Streams
implementation can inherit. This specification introduces the
"language" property and Natural Language Value concepts to fill this
gap.
Imagine a scenario with a service that receives Activity objects from
users and republishes those to a distributed audience of interested
parties. This service spans international boundaries and the users
speak a multitude of different languages. Within this system, a
native English speaker might subscribe to notifications about
activities posted by a native French speaker.
For instance, let's suppose that our native French speaker posts the
following activity to this system:
Snell Expires May 08, 2014 [Page 32]
Internet-Draft ActivityStreams November 2013
POST /activity/feed HTTP/1.1
Content-Type: application/activity+xml
{
"verb": "post",
"language": "fr",
"object": {
"objectType": "article",
"displayName": "Un exemple basique",
...
}
}
The system receives this activity post and prepares to notify our
native English speaking user. Knowing that this user prefers English
and does not speak a word of French, the system can inspect the
Activity and detect automatically that a translation ought to be
provided. Rather than replacing the original French text, however,
the service can simply add in the English translation along side it.
{
"verb": "post",
"language": "fr",
"actor": {
"id": "urn:example:person:abc",
"displayName": "Jean Valjean"
},
"object": {
"type": "article",
"displayName": {
"fr": "Un exemple basique",
"en": "A basic example"
}
...
}
}
It is also possible for a Natural Language Value to express
alternative same-language representations of a string that utilize
different writing systems or regions. For instance, it is common for
Japanese translations to provide equivalent ideographic (kanji) and
phonetic (katakana or hiragana) alternatives:
{
"title": {
"ja-Hani": "...",
Snell Expires May 08, 2014 [Page 33]
Internet-Draft ActivityStreams November 2013
"ja-Kana": "..."
}
}
C.2. Extensibility (e11y)
Arguably, the two most important extensibility points in the Activity
Streams format are the object type and verb properties.
Implementations are free to come up with their own types and verbs at
any point. While such extensibility is extremely powerful, it comes
with a cost. Namely, implementations that encounter previously
unknown verbs and object types may not have enough to knowledge about
those to do anything significant with them.
For instance, the most common use case for Activity Streams today is
the generation of a human-readable "activity feed" that translates
Activity objects into sentences just as "John uploaded a new photo"
or "Jane checked in at a hotel", etc. Given an extension verb such
as "http://example.org/whatever", an implementation might not have
sufficient information about that verb to generate a readable
sentence describing the activity that occurred.
With Activity Streams 1.0, a number of different approaches have been
tried to address this problem, but all of the solutions essentially
deal with the need to provide additional metadata about extension
verbs and object types so that an implementation can dynamically
learn and adapt. The notion of "type values" is added by this
specification to specifically deal with this issue.
For example, suppose I have an implementation that generates Activity
objects that use a new extension verb "urn:example:verbs:upload".
Knowing that consumers of these objects might not have encountered
this verb before, I want to make it possible for those
implementations to automatically discover metadata about the new
verb. To do so, I can use a type value to provide some basic
information.
{
"verb": {
"id": "urn:example:verbs:upload",
"url": "http://example.org/verbs.json",
"mediaType": "application/ld+json",
"displayName": {
"en": "upload",
"fr": "televersement"
},
"alias": "post"
Snell Expires May 08, 2014 [Page 34]
Internet-Draft ActivityStreams November 2013
},
"actor": {
"type": "person",
"displayName": "John"
},
"object": {
"type": "photo",
"displayName": "cats.jpg"
}
}
An implementation receiving this has several choices. It could
choose to ignore everything other than the verb's identifier,
treating it generically as one would have to today using the 1.0
syntax; or, it could inspect the metadata provided and notice that
the extension verb can be treated generally as an alias of "post" or
displayed in English as "upload" and in French as "televersement";
or, it can choose to attempt discovering more information about the
verb by dereferencing the provided URL.
The point is, these options are built into the core syntax, making
extension verbs and object types significantly more usable,
particularly when combined with the new language context features.
C.2.1. Publishing Extension objectType and verb Libraries
By treating extension objectTypes and verbs as objects in their own
right, it becomes trivially possible to use the Activity Streams
format as a means of publishing metadata about extension verbs.
For example:
{
"displayName": "My object types and verbs",
"items": [
{
"objectType": "verb",
"id": "urn:example:verbs:create",
"alias": "post",
"displayName": "Create"
},
{
"objectType": "objectType",
"id": "urn:example:types:article",
"displayName": "Article"
}
]
Snell Expires May 08, 2014 [Page 35]
Internet-Draft ActivityStreams November 2013
}
Implementations could use such documents to dynamically learn about
new verbs and objectTypes.
C.3. First Class Links
Linking in the 1.0 syntax is largely undefined and inconsistent.
There is a general notion of Media Link objects that are used for
some things like images and videos, along with a "url" property that
in some cases is used to always point to HTML represenations while in
other cases might point to JSON documents or image files, and there
is no reusable concept of a generic link provided for extensions to
leverage which has led to inconsistent implementation. The 2.0
syntax introduced here deals with these issues by introducing a
clear, consistent, reusable first class linking model.
For instance, using the 2.0 syntax, an "image" object type can be
represented simply as:
{
"objectType": "image",
"url": "http://example.org/cats.jpg",
"mediaType": "image/jpeg",
"displayName": "A picture of my cats",
"alternate": {
"url": "http://example.org/gallery?i=cats.jpg",
"mediaType": "text/html"
}
"preview": "http://example.org/thumbnails/cats.jpg"
}
Essentially, any 2.0 object that contains a "url" property can be
interpreted as a link. That "url" property points to a
representation of the object, while the "mediaType" property
identifies the content type of that linked resource. RFC 5988 Link
Relations can be used directly within the 2.0 syntax to provide
additional data -- in this case, an alternative HTML representation
of the image as well as a thumbnail preview.
Another case that the more flexible linking approach allows us to
address is providing multiple links for a single property. For
instance, it is not uncommon for there to be several alternative
versions of an image resource offered at various resolutions to
support multiple types of devices. With the 2.0 syntax, multiple
choices for a single link can be easily provided.
Snell Expires May 08, 2014 [Page 36]
Internet-Draft ActivityStreams November 2013
{
"objectType": "application",
"displayName": "My application",
"icon": [
{
"url": "http://example.org/sd/icon.png",
"width": 57,
"height": 57
},
{
"url": "http://example.org/hd/icon.png",
"width": 114,
"height": 114
}
],
"preview": [
"http://www.example.org/screenshots/1.jpg",
"http://www.example.org/screenshots/2.jpg",
"http://www.example.org/screenshots/3.jpg"
]
}
C.4. Use of External Vocabularies
Use of an "external vocabulary" within Activity Streams means using
object types, verbs and properties that are not defined by the core
Activity Streams specification. An example would be using concepts
defined within a microdata vocabulary such as that defined by
Schema.org (http://schema.org).
Implementations that wish to use a Activity Streams with such
external vocabularies face the challenge that, often times, identical
or overlapping concepts can be expressed in a multitude of ways
depending on which vocabulary is selected. This can make it
difficult to map abstract data models into a specific JSON
serialization.
Snell Expires May 08, 2014 [Page 37]
Internet-Draft ActivityStreams November 2013
For instance, suppose an application uses the Schema.org model to
represent an article, described here: http://schema.org/Article.
Within this model, there are several properties defined that directly
overlap properties defined by the core Activity Streams syntax. Such
properties include "name", "contentLocation", and "articleBody". In
order to encode the abstact model of a Schema.org/Article into the
JSON Activity Streams model, the application needs to determine
precisely how to map the abstract properties to the serialized
format. In Activity Streams 1.0, no guidance was given on how to
achieve such a mapping, within the 2.0 syntax, the JSON Serialization
for Linked Data (JSON-LD) provides a foundation.
Using JSON-LD I can maintain basic Activity Streams 2.0 syntax while
mapping the physical serialization to the abstract model inline.
{
"objectType": "article",
"displayName": "My article about things",
"content": "This is my article",
"@context": {
"objectType": "@type",
"article": "http://schema.org/Article",
"displayName": "http://schema.org/name",
"content": "http://schema.org/Article/articleBody"
}
}
For any non-JSON-LD aware implementation, this can be processed just
as if it were an ordinary Activity Streams object, without any
additional consideration given. For a JSON-Ld aware implementation,
however, the addition of the "@context" property allows the
serialized JSON to be unambiguously mapped to the Schema.org concept
of an "Article". The fact that we can support such a mapping allows
the Activity Streams format to extend to a broader range of scenarios
without requiring alternative, incompatible vocabulary specific
models of "actions" or "activities" to be developed.
C.5. Embedded Actions
Every Activity Streams object represents a discreet modular component
that can be distributed, shared, or acted upon in a variety of ways.
The 2.0 syntax allows these components to not only express
information about the content but also about the specific types of
actions that can be performed with the object.
For example, an email that is automatically generated by an expense
reporting system could embed a structured Activity Stream object that
Snell Expires May 08, 2014 [Page 38]
Internet-Draft ActivityStreams November 2013
contains a listing of the possible actions the recipient of the email
can take. An intelligent email agent can interpret this embedded
metadata and provide a tailored, in-context UI experience:
Your employee, John Doe, has submitted a new expense
report for "John's trip to San Francisco"....
Author's Address
James M Snell (editor)
IBM
Email: jasnell@gmail.com
Snell Expires May 08, 2014 [Page 39]