1. Introduction
The Activity Streams 2.0 Core Syntax defines the JSON syntax for Activity Streams. This document defines the vocabulary properties.
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].
1.1 Conventions
Unless otherwise specified, all properties defined as
xsd:dateTime values MUST conform to the rules defined in Activity Streams 2.0 Core,
Section 2.3.
The examples included in this document use the normative JSON serialization defined by this specification.
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:
Example 144
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Activities in Project XYZ",
"type": "Collection",
"items": [
{
"summary": "Sally created a note",
"type": "Create",
"id": "http://activities.example.com/1",
"actor": "http://sally.example.org",
"object": {
"summary": "A note",
"type": "Note",
"id": "http://notes.example.com/1",
"content": "A note"
},
"context": {
"type": "http://example.org/Project",
"name": "Project XYZ"
},
"audience": {
"type": "Group",
"name": "Project XYZ Working Group"
},
"to": "http://john.example.org"
},
{
"summary": "John liked Sally's note",
"type": "Like",
"id": "http://activities.example.com/1",
"actor": "http://john.example.org",
"object": "http://notes.example.com/1",
"context": {
"type": "http://example.org/Project",
"name": "Project XYZ"
},
"audience": {
"type": "Group",
"name": "Project XYZ Working Group"
},
"to": "http://sally.example.org"
}
]
}
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.
Using the Relationship object, we can model these relationships as:
Example 145
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally's friends list",
"type": "Collection",
"items": [
{
"summary": "Sally is influenced by Joe",
"type": "Relationship",
"subject": {
"type": "Person",
"name": "Sally"
},
"relationship": "http://purl.org/vocab/relationship/influencedBy",
"object": {
"type": "Person",
"name": "Joe"
}
},
{
"summary": "Sally is a friend of Jane",
"type": "Relationship",
"subject": {
"type": "Person",
"name": "Sally"
},
"relationship": "http://purl.org/vocab/relationship/friendOf",
"object": {
"type": "Person",
"name": "Jane"
}
}
]
}
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:
Example 146
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally became a friend of Matt",
"type": "Create",
"actor": "http://sally.example.org",
"object": {
"type": "Relationship",
"subject": "http://sally.example.org",
"relationship": "http://purl.org/vocab/relationship/friendOf",
"object": "http://matt.example.org",
"startTime": "2015-04-21T12:34:56"
}
}
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.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:
Example 159
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally moved the sales figures from Folder A to Folder B",
"type": "Move",
"actor": "http://sally.example.org",
"object": {
"type": "Document",
"name": "sales figures"
},
"origin": {
"type": "Collection",
"name": "Folder A"
},
"target": {
"type": "Collection",
"name": "Folder B"
}
}
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.