Abstract

This specification describes the Activity vocabulary. It is intended to be used in the context of the ActivityStreams 2.0 format and provides a foundational vocabulary for activity structures, and specific activity types.

Author's Note

This section is non-normative.

This draft is heavily influenced by the JSON Activity Streams 1.0 specification originally co-authored by Martin Atkins, Will Norris, Chris Messina, Monica Wilkinson, Rob Dolin and James Snell. The author is very thankful for their significant contributions and gladly stands on their shoulders. Some portions of the original text of Activity Streams 1.0 are used in this document.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

1. Introduction

The Activity Streams 2.0 Vocabulary defines a set of abstract types and properties that describe past, present and future Activities. The vocabulary is defined in two parts:

A Core set of properties describing the generalized structure of an Activity; and

An Extended set of properties that cover specific types of Activities and Artifacts common to many social Web application systems.

While not all Activity Streams 2.0 implementations are expected to implement support for the Extended properties, all implementations MUST at least be capable of serializing and deserializing the Extended properties in accordance with the
Activity Streams 2.0 Core Syntax.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "
SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

A Link is an indirect, qualified reference to a resource identified by a URL. The fundamental model for links is established by [
RFC5988]. Many of the properties defined by the Activity Vocabulary allow values that are either instances of
Object or Link. When a Link is used, it establishes a
qualified relation connecting the subject (the containing object) to the resource identified by the href. Properties of the Link are properties of the reference as opposed to properties of the resource.

An Activity is a subtype of Object that describes some form of action that may happen, is currently happening, or has already happened. The Activity type itself serves as an abstract base type for all types of activities. It is important to note that the Activity type itself does not carry any specific semantics about the kind of action being taken.

Support for specific extended vocabulary types is expected to vary, with implementations only selecting the extended types and properties that make sense within the specific context and requirements of those applications. However, to avoid possible interoperability issues, implementations MUST avoid using extension types or properties that unduly overlap with or duplicate the extended vocabulary defined here.

3.1 Activity Types

All Activity Types inherit the properties of the base Activity type. Some specific Activity Types are subtypes or specializations of more generalized Activity Types (for instance, the
Invite Activity Type is a more specific form of the
Offer Activity Type).

Indicates that the actor has added the
object to the target. If the
target property is not explicitly specified, the target would need to be determined implicitly by context. The
origin can be used to identify the context from which the object originated.

An IntransitiveActivity that indicates that the actor has arrived at the location. The origin can be used to identify the context from which the actor originated. The target typically has no defined meaning.

Indicates that the actor is "following" the
object. Following is defined in the sense typically used within Social systems in which the actor is interested in any activity performed by or on the object. The
target and origin typically have no defined meaning.

Indicates that the actor is undoing the
object. In most cases, the object will be an Activity describing some previously performed action (for instance, a person may have previously "liked" an article but, for whatever reason, might choose to undo that like at some later point in time).

Indicates that the actor is traveling to
target from origin. Travel is an IntransitiveObject whose actor specifies the direct object. If the target or
origin are not specified, either can be determined by context.

Indicates that the actor is blocking the
object. Blocking is a stronger form of
Ignore. The typical use is to support social systems that allow one user to block activities or content of other users. The target and origin typically have no defined meaning.

Represents a question being asked. Question objects are an extension of IntransitiveActivity. That is, the Question object is an Activity, but the direct object is the question itself and therefore it would not contain an
object property.

Either of the anyOf and
oneOf properties MAY be used to express possible answers, but a Question object MUST NOT have both properties.

3.3 Object and Link Types

All Object Types inherit the properties of the base Object type. Link Types inherit the properties of the base Link type. Some specific Object Types are subtypes or specializations of more generalized Object Types (for instance, the Like Type is a more specific form of the Activity type).

The "Domain" indicates the type of Object the property term applies to. The "Range" indicates the type of value the property term can have. Certain properties are marked as a "Subproperty Of" another term, meaning that the term is a specialization of the referenced term. For instance,
actor is a subproperty of
attributedTo. Properties marked as being "Functional" can have only one value. Items not marked as "Functional" can have multiple values.

Identifies the context within which the object exists or an activity was performed.

The notion of "context" used is intentionally vague. The intended function is to serve as a means of grouping objects and activities that share a common originating context or purpose. An example could be all activities relating to a common project or event.

Describes an indirect object of the activity from which the activity is directed. The precise meaning of the origin is the object of the English preposition "from". For instance, in the activity "John moved an item to List B from List A", the origin of the activity is "List A".

One or more "tags" that have been associated with an objects. A tag can be any kind of Object. The key difference between
attachment and tag is that the former implies association by inclusion, while the latter implies associated by reference.

Describes the indirect object, or target, of the activity. The precise meaning of the target is largely dependent on the type of action being described but will often be the object of the English preposition "to". For instance, in the activity "John added a movie to his wishlist", the target of the activity is John's wishlist. An activity can have more than one target.

The content or textual representation of the Object encoded as a JSON string. By default, the value of content is HTML. The mediaType property can be used in the object to indicate a different content type.

When the object describes a time-bound resource, such as an audio or video, a meeting, etc, the duration property indicates the object's approximate duration. The value MUST be expressed as an xsd:duration as defined by [
xmlschema11-2], section 3.3.6 (e.g. a period of 5 seconds is represented as "PT5S").

The date and time describing the actual or expected ending time of the object. When used with an Activity object, for instance, the endTime property specifies the moment the activity concluded or is expected to conclude.

The date and time describing the actual or expected starting time of the object. When used with an Activity object, for instance, the startTime property specifies the moment the activity began or is scheduled to begin.

A non-negative integer specifying the total number of objects contained by the logical view of the collection. This number might not reflect the actual number of items serialized within the Collection object instance.

{
"@context": "https://www.w3.org/ns/activitystreams",
"name": "Cranberry Sauce Idea",
"type": "Note",
"content": "Mush it up so it does not have the same shape as the can.",
"updated": "2014-12-12T12:12:12Z"
}

5. Implementation Notes

5.1 Audience Targeting

Conceptually, every Object has both a Primary and Secondary audience. The Primary audience consists of those entities directly involved or owning the object. The Secondary audience consists of the collection of entities sharing an interest in the object but who might not be directly involved (e.g."followers").

For instance, suppose a social network of three individuals: Bob, Joe and Jane. Bob and Joe are each friends with Jane but are not friends with one another. Bob has chosen to "follow" activities for which Jane is directly involved. Jane shares a file with Joe.

In this example, Jane and Joe are each directly involved in the file sharing activity and together make up the Primary Audience for that event. Bob, having an interest in activities involving Jane, is the Secondary Audience. Knowing this, a system that produces or consumes the activity can intelligently notify each person of the event.

While there are means (based on the action type, actor, object and target of the activity) to infer the primary audience for many types of activities, heuristics do not work in every case and do not provide a means of identifying the secondary audience. The
to, cc, bto and bcc properties MAY be used within an Object to explicitly identify the Primary and Secondary audiences.

The prototypical use case for an Object containing these properties is the publication and redistribution of objects through an intermediary. That is, an event source generates the object and publishes it to the intermediary which determines a subset of items to display to specific individual users or groups. Such a determination can be made, in part, by identifying the Primary and Secondary Audiences for each object.

When the event source generates the object and specifies values for the to and cc fields, the intermediary SHOULD redistribute that object with the values of those fields intact, allowing any processor to see who the object has been targeted to. This is precisely the same model used by the to and cc fields in email systems.

There are situations, however, in which disclosing the identity of specific members of the audience may be inappropriate. For instance, a user may not wish to let other users know that they are interested in various topics, individuals or types of events. To support this option, an implementation generating an object MAY use the
bto and bcc properties to list entities to whom the object should be privately targeted. When an intermediary receives an object containing these properties, it
MUST remove those values prior to redistributing the object. The intent is that systems MUST consider entities listed within the
bto and bcc properties as part of the Primary and Secondary audience but MUST NOT disclose that fact to any other party.

Audience targeting information included within an Object only describes the intent of the object creator. With clear exception given to the appropriate handling of bto and
bcc, this specification leaves it up to implementations to determine how the audience targeting information is used.

5.1.1 Audience and Context

This section is non-normative.

Activities are rarely isolated events. Often, multiple individual activities will be performed around a similar context or audience. For instance, a collaborators working on a shared project might perform multiple related activities in the process of achieving some goal. Such activities can be logically grouped together using the context property, and scoped to a particular audience using the audience property.

For instance, the following shows two related activities that share a common context and audience:

5.2 Representing Relationships Between Entities

The Relationship object is used to represent relationships between individuals. It can be used, for instance, to describe that one person is a friend of another, or that one person is a member of a particular organization. The intent of modeling Relationship in this way is to allow descriptions of activities that operate on the relationships in general, and to allow representation of Collections of relationships.

For instance, many social systems have a notion of a "friends list". These are the collection of individuals that are directly connected within a person's social graph. Suppose we have a user, Sally, with direct relationships to users Joe and Jane. Sally follows Joe's updates while Sally and Jane have a mutual relationship.

The relationship property specifies the kind of relationship that exists between the two individuals identified by the
subject and
object properties. Used together, these three properties form what is commonly known as a "
reified statement" where subject identifies the subject, relationship identifies the predicate, and
object identifies the object.

While use of reified statements can be problematic and confusing in certain situations, their use within the Activity Streams vocabulary to describe relationships provides a straightforward mechanism of describing changes to an individual's social graph. For instance, to indicate that Sally has created a new relationship to user Matt, an implementer can use the
Relationship object together with the
Create activity:

Additionally, modeling the relationship in this way allows implementers to articulate additional properties of the relationship itself. For instance, the date and time at which the relationship began or ended.

Implementations may reuse existing vocabularies that have been developed for the purpose of describing relationships, or create their own guided by requirements of their particular implementation. Existing vocabularies include the "
Friend of a Friend" and "
Relationship" vocabularies.

5.2.1 Modeling "friend requests"

This section is non-normative.

One common use case for many social platforms is the establishment of symmetrical "friend" relationships, in which one user initially extends a request to another user to establish a new connection. Once the connection is made, both users automatically begin receiving notifications about activities performed by the other, and the established relationship becomes visible in either user's "friends list".

The initial "friend request" can be modeled by composing the
Offer and Relationship object types as in the following example:

As illustrated in this example, accepting the "friend request" results in four additional activities including: John following Sally, Sally following John, John adding the relationship with Sally to his collection of Connections, and Sally adding the relationship with John to her collection of Connections.

In this example,

The optional result property is used within the Accept activity to identify the additional activities that occurred as a result of the accept.

The optional context property is used to relate the various activities back to a common reference point, which in this example is the relationship being established. The context allows an implementation to efficiently group related activities together for display or analytic purposes.

5.3 Representing Places

This section is non-normative.

The Place object is used to represent both physical and logical locations. While numerous existing vocabularies exist for describing locations in a variety of ways, inconsistencies and incompatibilities between those vocabularies make it difficult to achieve appropriate interoperability between implementations. The Place object is included within the Activity vocabulary to provide a minimal, interoperable starting point for describing locations consistently across Activity Streams 2.0 implementations.

The Place object is intentionally flexible. It can, for instance, be used to identify a location simply by name:

The Place object can also describe an area around a given point using the radius property, the
altitude of the location, and a degree of
accuracy.

While publishers are not required to use these specific properties and MAY make use of other mechanisms for describing locations, consuming implementations that support the
Place object MUST support the use of these properties.

5.4 Representing Questions

This section is non-normative.

The Question object can be used to express various types of inquiries.

For instance, simple open-ended questions similar to those posted to crowd-sourced question and answer websites:

It is important to note that these types of activities are semantically distinct from one another and have no direct relationship on the other. That is, for example, if an actor "likes" a note at one point in time then later "dislikes" it, the "dislike" activity does not "undo" or negate out the prior "like".

The appropriate interpretation for the following is that Sally first liked, then later disliked John's note:

The Undo activity type is defined to provide the specific ability to undo or cancel out a prior activity. The appropriate interpretation for the following, then, is that Sally liked John's note at one point but has explicitly redacted that like later on.

The end result of the former example is that Sally has indicated that she changed her opinion about John's note and now dislikes it, while in the latter example she currently neither likes or dislikes it.

5.6 Mentions, Tags and Other Common Social Microsyntaxes

This section is non-normative.

Many social software systems use special text-based microsyntaxes that allow users to define special addressing for notifications, linking, or categorization within objects. For example, including text such as "@username" within an object's content will often route the object to a special "mentions" or "inbox" stream for a particular user. Likewise, including text such as "
#topic" within the object's content will often mark the object as being related to the topic "topic". Such mechanisms are commonly referred to as "mentions" and "hashtags", respectively.

While such microsyntaxes MAY be used within the values of the
content,
name, and summary properties on an Activity Streams Object, implementations SHOULD NOT be required to parse the values of those properties in order to determine the appropriate routing of notifications, categorization or linking between objects. Instead, publishers SHOULD make appropriate use of the vocabulary terms provided specifically for these purposes.

For example, suppose that an author wishes to send a note of thanks to another user named "@sally" with a hashtag of "#givingthanks". A typical way this message would appear within the content of a note is shown below:

Figure 1A simple note with a mention an a hashtag:

"Thankyou @sally for all your hard work! #givingthanks"

A typical social software implementation would typically render such a content such that "@sally" is replaced with a hyperlink to "@sally"'s social profile page and "#givingthanks" is replaced with a hyperlink to a listing of other notes that have been "tagged" with the same topic. Most implementations would also send a special notification to sally letting her know that a note mentioning her has been created.

The to property indicates that the user "@sally" is to be considered part of the primary
audience of the note and should therefore receive notification. The
tag property associates the Note with a reference to "
http://example.org/tags/givingthanks". Note that the
content still includes the "@sally" and "
#givingthanks" microsyntaxes but that consuming implementations are not required to parse those in order to make the appropriate associations.

In the case a publisher wishes to indicate a mention without an associated notification, the publisher can use the Mention object type as a value of the tag property.

5.7 Origin and Target

The origin and target properties of an Activity respectively identify the entities from which and
to which the action is directed. For instance, in the English statement, "Sally moved the file from Folder A to Folder B", the
origin is "Folder A" and the target is "Folder B". This activity is illustrated in the example below:

The origin property is applicable to any type of activity for which the English preposition "from" can be considered applicable in the sense of identifying the origin, source or provenance of the activity's object.

The target property is applicable to any type of activity for which the English preposition "to" can be considered applicable in the sense of identifying the indirect object or destination of the activity's object.

5.8 Activity Type Motivating Use Cases

This section is non-normative.

The Activity types defined in this vocabulary have been primarily selected to address the commonly implemented social use cases described below.

5.8.1 Content Management

The Content Management use case primarily deals with activities that involve the creation, modification or deletion of content. This includes, for instance, activities such as "John created a new note", "Sally updated an article", and "Joe deleted the photo".

5.8.2 Collection Management

The Collection Management use case primarily deals with activities involving the management of content within collections. Examples of collections include things like folders, albums, friend lists, etc. This includes, for instance, activities such as "Sally added a file to Folder A", "John moved the file from Folder A to Folder B", etc.

5.8.3 Reactions

The Reactions use case primarily deals with reactions to content. This can include activities such as liking or disliking content, ignoring updates, flagging content as being inappropriate, accepting or rejecting objects, etc.

5.8.4 Event RSVP

5.8.5 Group Management

The Group Management use case primarily deals with management of groups. It can include, for instance, activities such as "John added Sally to Group A", "Sally joined Group A", "Joe left Group A", etc.

5.8.7 Geo-Social Events

The Geo-Social Events use case primarily deals with activities involving geo-tagging type activities. For instance, it can include activities such as "Joe arrived at work", "Sally left work", and "John is travel from home to work".

5.8.9 Questions

5.8.10 Relationship Management

The Relationship Management use case primarily deals with representing activities involving the management of interpersonal and social relationships (e.g. friend requests, management of social network, etc). See 5.2Representing Relationships Between Entities for more information.

5.8.11 Negating Activity

5.8.12 Offers

The Offers use case deals with activities involving offering one object to another. It can include, for instance, activities such as "Company A is offering a discount on purchase of Product Z to Sally", "Sally is offering to add a File to Folder A", etc.

A. Non-normative Ontology Definition

This section is non-normative.

A non-normative turtle definition of the Activity Streams 2.0 vocabulary is provided here and/or at the namespace as a convenience for implementers wishing to use RDF mechanisms for processing Activity Streams 2.0. Note, however, that this document provides the normative definition of the Activity Streams 2.0 vocabulary.

B. Changelog

This section is non-normative.

The following notable changes have been made to this document since the previous candidate recommendation of 2016-12-15.

Removed the four normative relationship values for lack of implementation. Changed examples to use terms from the
Relationship vocabulary.