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 classes
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 along with generally
equivalent, non-normative Microdata, RDFa, Microformats, and Turtle
serializations. These non-JSON alternatives are included solely for
illustrative purposes.
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 Scope and Context
This section is non-normative.
Activities are rarely isolated events. Often, multiple individual
activities will be performed around a similar context or scope.
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 scope property.
For instance, the following shows two related activities that share
a common context and scope:
Example 678
{
"@context": "http://www.w3.org/ns/activitystreams",
"type": "Collection",
"items": [
{
"type": "Create",
"id": "http://activities.example.com/1",
"actor": "http://sally.example.org",
"object": {
"type": "Note",
"id": "http://notes.example.com/1",
"content": "A note"
},
"context": {
"type": "http://example.org/Project",
"name": "Project XYZ"
},
"scope": {
"type": "Group",
"name": "Project XYZ Working Group"
},
"to": "http://john.example.org"
},
{
"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"
},
"scope": {
"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 considers Joe
to be a close friend while Jane is just an acquaintance.
Using the Relationship object, we can model
these relationships as:
Example 679
{
"@context": "http://www.w3.org/ns/activitystreams",
"type": "Collection",
"items": [
{
"type": "Relationship",
"subject": {
"type": "Person",
"name": "Sally"
},
"relationship": "http://purl.org/vocab/relationship/closeFriendOf",
"object": {
"type": "Person",
"name": "Joe"
}
},
{
"type": "Relationship",
"subject": {
"type": "Person",
"name": "Sally"
},
"relationship": "http://purl.org/vocab/relationship/acquaintanceOf",
"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 680
{
"@context": "http://www.w3.org/ns/activitystreams",
"type": "Create",
"actor": "http://sally.example.org",
"object": {
"type": "Relationship",
"subject": "http://sally.example.org",
"relationship": "http://purl.org/vocab/relationship/closeFriendOf",
"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.
The Activity Streams vocabulary does not define normative values
for use with the
relationship property.
It is expected that implementations will make use of several
existing vocabularies that have been developed for the purpose
of describing relationships. Examples of such 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 693
{
"@context": "http://www.w3.org/ns/activitystreams",
"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.