mariuszprzydatek.com

In this post i’d like to address the subject of Activity Streams spec., something I’ve been working with recently in one of the projects.

Let’s start with a definition of an activity stream (Wikipedia):

• “An activity stream is a list of recent activities performed by an individual, typically on a single website. For example, Facebook’s News Feed is an activity stream. Since the introduction of the News Feed on September 6, 2006, other major websites have introduced similar implementations for their own users. Since the proliferation of activity streams on websites, there have been calls to standardize the format so that websites could interact with a stream provided by another website. The Activity Streams project, for example, is an effort to develop an activity stream protocol to syndicate activities across social Web applications. Several major websites with activity stream implementations have already opened up their activity streams to developers to use, including Facebook and MySpace. Though activity stream arises from social networking, nowadays it has become an essential part of business software. Enterprise social software is used in different types of companies to organize their internal communication and acts as an important addition to traditional corporate intranet.”

Activity Streams is an open format specification for activity stream protocols, which are used to syndicate activities taken in social web applications and services.

JSON Activity Streams 1.0 is the name of the specification published on May 2011 by the working group consisting of: J. Snell (IBM), M. Atkins (SAY Media), W. Norris (Google), C. Messina (Citizen Agency, Google), M. Wilkinson (MySpace, Facebook, VMware), R. Dolin (Microsoft).

On the homepage of the specification activitystrea.ms you’ll find more details including a list of early adopters (BBC, Gnip, Google, Buzz, Gowalla, IBM, MySpace, Opera, Socialcast, Superfeedr,
TypePad, Windows Live, YIID, and many others).

Introduction:

• In its simplest form, an activity consists of an actor, a verb, an an object, and a target.
• It tells the story of a person performing an action on or with an object — “Geraldine posted a photo to her album” or “John shared a video”. In most cases these components will be explicit, but they may also be implied.
• Goal of the specification is to provide sufficient metadata about an activity such that a consumer of the data can present it to a user in a rich human-friendly format. (this may include constructing readable sentences about the activity that occurred, visual representations of the activity, or combining similar activities for display).
• The basic properties that comprise the description of an activity are defined in the appropriate sections of the specification.
• Within the specification, an object is a thing, real or imaginary, which participates in an activity. It may be the entity performing the activity, or the entity on which the activity was performed.
• An object consists of properties defined in appropriate sections of the specification. Certain object types may further refine the meaning of these properties, or they may define additional properties.
• Some types of objects may have an alternative visual representation in the form of an image, video or embedded HTML fragments. A Media Link represents a hyperlink to such resources.
• An Activity Stream is a collection one or more individual activities. The relationship between the activities within the collection is undefined by this specification.

Following is a simple, minimal example of a JSON serialized activity:

{
    "published": "2011-02-10T15:04:55Z",
    "actor": {
        "url": "http://example.org/martin",
        "objectType" : "person",
        "id": "tag:example.org,2011:martin",
        "image": {
            "url": "http://example.org/martin/image",
            "width": 250,
            "height": 250
        },
        "displayName": "Martin Smith"
    },
    "verb": "post",
    "object" : {
        "url": "http://example.org/blog/2011/02/entry",
        "id": "tag:example.org,2011:abc123/xyz"
    },
    "target" : {
        "url": "http://example.org/blog/",
        "objectType": "blog",
        "id": "tag:example.org,2011:abc123",
        "displayName": "Martin's Blog"
    }
}

To give you an idea on the “breadth” of the spec., and how many various activities got its individual verb, take a look at the following complete list of “verbs”:

• accept – Indicates that that the actor has accepted the object. For instance, a person accepting an award, or accepting an assignment.
• access – Indicates that the actor has accessed the object. For instance, a person accessing a room, or accessing a file.
• acknowledge – Indicates that the actor has acknowledged the object. This effectively signals that the actor is aware of the object’s existence.
• add – Indicates that the actor has added the object to the target. For instance, adding a photo to an album.
• agree – Indicates that the actor agrees with the object. For example, a person agreeing with an argument, or expressing agreement with a particular issue.
• append – Indicates that the actor has appended the object to the target. For instance, a person appending a new record to a database.
• approve – Indicates that the actor has approved the object. For instance, a manager might approve a travel request.
• archive – Indicates that the actor has archived the object.
• assign – Indicates that the actor has assigned the object to the target.
• at – Indicates that the actor is currently located at the object. For instance, a person being at a specific physical location.
• attach – Indicates that the actor has attached the object to the target.For instance, a person attaching a file to a wiki page or an email.
• attend – Indicates that the actor has attended the object. For instance, a person attending a meeting.
• author – Indicates that the actor has authored the object. Note that this is a more specific form of the verb “create”.
• authorize – Indicates that the actor has authorized the object. If a target is specified, it means that the authorization is specifically in regards to the target. For instance, a service can authorize a person to access a given application; in which case the actor is the service, the object is the person, and the target is the application. In contrast, a person can authorize a request; in which case the actor is the person and the object is the request and there might be no explicit target.
• borrow – Indicates that the actor has borrowed the object. If a target is specified, it identifies the entity from which the object was borrowed. For instance, if a person borrows a book from a library, the person is the actor, the book is the object and the library is the target.
• build – Indicates that the actor has built the object. For example, if a person builds a model or compiles code.
• cancel – Indicates that the actor has canceled the object. For instance, canceling a calendar event.
• close – Indicates that the actor has closed the object. For instance, the object could represent a ticket being tracked in an issue management system.
• complete – Indicates that the actor has completed the object.
• confirm – Indicates that the actor has confirmed or agrees with the object. For instance, a software developer might confirm an issue reported against a product.
• consume – Indicates that the actor has consumed the object. The specific meaning is dependent largely on the object’s type. For instance, an actor may “consume” an audio object, indicating that the actor has listened to it; or an actor may “consume” a book, indicating that the book has been read. As such, the “consume” verb is a more generic form of other more specific verbs such as “read” and “play”.
• checkin – Indicates that the actor has checked-in to the object. For instance, a person checking-in to a Place.
• create – Indicates that the actor has created the object.
• delete – Indicates that the actor has deleted the object. This implies, but does not require, the permanent destruction of the object.
• deliver – Indicates that the actor has delivered the object. For example, delivering a package.
• deny – Indicates that the actor has denied the object. For example, a manager may deny a travel request.
• disagree – Indicates that the actor disagrees with the object.
• dislike – Indicates that the actor dislikes the object. Note that the “dislike” verb is distinct from the “unlike” verb which assumes that the object had been previously “liked”.
• experience – Indicates that the actor has experienced the object in some manner. Note that, depending on the specific object types used for both the actor and object, the meaning of this verb can overlap that of the “consume” and “play” verbs. For instance, a person might “experience” a movie; or “play” the movie; or “consume” the movie. The “experience” verb can be considered a more generic form of other more specific verbs as “consume”, “play”, “watch”, “listen”, and “read”
• favorite – Indicates that the actor marked the object as an item of special interest.
• find – Indicates that the actor has found the object.
• flag-as-inappropriate – Indicates that the actor has flagged the object as being inappropriate for some reason. When using this verb, thecontext property can be used to provide additional detail about why the object has been flagged.
• follow – Indicates that the actor began following the activity of the object. In most cases, the objectType will be a “person”, but it can potentially be of any type that can sensibly generate activity. Processors MAY ignore (silently drop) successive identical “follow” activities.
• give – Indicates that the actor is giving an object to the target. Examples include one person giving abadge object to another person. Theobject identifies the object being given. Thetarget identifies the receiver.
• host – Indicates that the actor is hosting the object. As in hosting an event, or hosting a service.
• ignore – Indicates that the actor has ignored the object. For instance, this verb may be used when an actor has ignored a friend request, in which case the object may be the request-friend activity.
• insert – Indicates that the actor has inserted the object into the target.
• install – Indicates that the actor has installed the object, as in installing an application.
• interact – Indicates that the actor has interacted with the object. For instance, when one person interacts with another.
• invite – Indicates that the actor has invited the object, typically a person object, to join or participate in the object described by the target. The target could, for instance, be an event, group or a service.
• join – Indicates that the actor has become a member of the object. This specification only defines the meaning of this verb when theobject of the Activity has an objectTypeof group, though implementors need to be prepared to handle other types of objects.
• leave – Indicates that the actor has left the object. For instance, a Person leaving a Group or checking-out of a Place.
• like – Indicates that the actor marked the object as an item of special interest. The “like” verb is considered to be an alias of “favorite”. The two verb are semantically identical.
• listen – Indicates that the actor has listened to the object. This is typically only applicable for objects representing audio content, such as music, an audio-book, or a radio broadcast. The “listen” verb is a more specific form of the “consume”, “experience” and “play” verbs.
• lose – Indicates that the actor has lost the object. For instance, if a person loses a game.
• make-friend – Indicates the creation of a friendship that is reciprocated by the object. Since this verb implies an activity on the part of its object, processors MUST NOT accept activities with this verb unless they are able to verify through some external means that there is in fact a reciprocated connection. For example, a processor may have received a guarantee from a particular publisher that the publisher will only use this Verb in cases where a reciprocal relationship exists.
• open – Indicates that the actor has opened the object. For instance, the object could represent a ticket being tracked in an issue management system.
• play – Indicates that the actor spent some time enjoying the object. For example, if the object is a video this indicates that the subject watched all or part of the video. The “play” verb is a more specific form of the “consume” verb.
• present – Indicates that the actor has presented the object. For instance, when a person gives a presentation at a conference.
• purchase – Indicates that the actor has purchased the object. If a target is specified, in indicates the entity from which the object was purchased.
• qualify – Indicates that the actor has qualified for the object. If a target is specified, it indicates the context within which the qualification applies.
• read – Indicates that the actor read the object. This is typically only applicable for objects representing printed or written content, such as a book, a message or a comment. The “read” verb is a more specific form of the “consume”, “experience” and “play” verbs.
• receive – Indicates that the actor is receiving an object. Examples include a person receiving abadge object. Theobject identifies the object being received.
• reject – Indicates that the actor has rejected the object.
• remove – Indicates that the actor has removed the object from the target.
• remove-friend – Indicates that the actor has removed the object from the collection of friends.
• replace – Indicates that the actor has replaced the target with the object.
• request – Indicates that the actor has requested the object. If a target is specified, it indicates the entity from which the object is being requested.
• request-friend – Indicates the creation of a friendship that has not yet been reciprocated by the object.
• resolve – Indicates that the actor has resolved the object. For instance, the object could represent a ticket being tracked in an issue management system.
• return – Indicates that the actor has returned the object. If a target is specified, it indicates the entity to which the object was returned.
• retract – Indicates that the actor has retracted the object. For instance, if an actor wishes to retract a previously published activity, the object would be the previously published activity that is being retracted.
• rsvp-maybe – The “possible RSVP” verb indicates that the actor has made a possible RSVP for the object. This specification only defines the meaning of this verb when its object is an event, though implementors need to be prepared to handle other object types. The use of this verb is only appropriate when the RSVP was created by an explicit action by the actor. It is not appropriate to use this verb when a user has been added as an attendee by an event organiser or administrator.
• rsvp-no – The “negative RSVP” verb indicates that the actor has made a negative RSVP for the object. This specification only defines the meaning of this verb when its object is an event, though implementors need to be prepared to handle other object types. The use of this verb is only appropriate when the RSVP was created by an explicit action by the actor. It is not appropriate to use this verb when a user has been added as an attendee by an event organiser or administrator.
• rsvp-yes – The “positive RSVP” verb indicates that the actor has made a positive RSVP for an object. This specification only defines the meaning of this verb when its object is an event, though implementors need to be prepared to handle other object types. The use of this verb is only appropriate when the RSVP was created by an explicit action by the actor. It is not appropriate to use this verb when a user has been added as an attendee by an event organiser or administrator.
• satisfy – Indicates that the actor has satisfied the object. If a target is specified, it indicate the context within which the object was satisfied. For instance, if a person satisfies the requirements for a particular challenge, the person is the actor; the requirement is the object; and the challenge is the target.
• save – Indicates that the actor has called out the object as being of interest primarily to him- or herself. Though this action MAY be shared publicly, the implication is that the object has been saved primarily for the actor’s own benefit rather than to show it to others as would be indicated by the “share” verb.
• schedule – Indicates that the actor has scheduled the object. For instance, scheduling a meeting.
• search – Indicates that the actor is or has searched for the object. If a target is specified, it indicates the context within which the search is or has been conducted.
• sell – Indicates that the actor has sold the object. If a target is specified, it indicates the entity to which the object was sold.
• send – Indicates that the actor has sent the object. If a target is specified, it indicates the entity to which the object was sent.
• share – Indicates that the actor has called out the object to readers. In most cases, the actor did not create the object being shared, but is instead drawing attention to it.
• sponsor – Indicates that the actor has sponsored the object. If a target is specified, it indicates the context within which the sponsorship is offered. For instance, a company can sponsor an event; or an individual can sponsor a project; etc.
• start – Indicates that the actor has started the object. For instance, when a person starts a project.
• stop-following – Indicates that the actor has stopped following the object.
• submit – Indicates that the actor has submitted the object. If a target is specified, it indicates the entity to which the object was submitted.
• tag – Indicates that the actor has associated the object with the target. For example, if the actor specifies that a particular user appears in a photo. the object is the user and the target is the photo.
• terminate – Indicates that the actor has terminated the object.
• tie – Indicates that the actor has neither won or lost the object. This verb is generally only applicable when the object represents some form of competition, such as a game.
• unfavorite – Indicates that the actor has removed the object from the collection of favorited items.
• unlike – Indicates that the actor has removed the object from the collection of liked items.
• unsatisfy – Indicates that the actor has not satisfied the object. If a target is specified, it indicates the context within which the object was not satisfied. For instance, if a person fails to satisfy the requirements of some particular challenge, the person is the actor; the requirement is the object and the challenge is the target.
• unsave – Indicates that the actor has removed the object from the collection of saved items.
• unshare – Indicates that the actor is no longer sharing the object. If a target is specified, it indicates the entity with whom the object is no longer being shared.
• update – The “update” verb indicates that the actor has modified the object. Use of the “update” verb is generally reserved to indicate modifications to existing objects or data such as changing an existing user’s profile information.
• use – Indicates that the actor has used the object in some manner.
• watch – Indicates that the actor has watched the object. This verb is typically applicable only when the object represents dynamic, visible content such as a movie, a television show or a public performance. This verb is a more specific form of the verbs “experience”, “play” and “consume”.
• win – Indicates that the actor has won the object. This verb is typically applicable only when the object represents some form of competition, such as a game.

The complete schema can be found on the Github page of the project, here.

Take care!

Resources:

• Activity Stream (http://en.wikipedia.org/wiki/Activity_stream)
• Activity Streams format (http://en.wikipedia.org/wiki/Activity_Streams_(format))
• Activity Streams homepage (http://activitystrea.ms)
• JSON Activity Streams 1.0 (http://activitystrea.ms/specs/json/1.0)
• Github project with complete schema (https://github.com/activitystreams/activity-schema)