This specification details a model for representing potential and
completed activities using the JSON format. It is intended to be used
with vocabularies that detail the structure of activities, and define
specific types of activities.
Author's Note
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.
Introduction
In the most basic sense, an "Activity" is a semantic description of
an action. It is the goal of this specification to provide a JSON-based
syntax that is sufficient to express metadata about activities in a rich,
human-friendly but machine-processable and extensible manner. This can
include constructing natural-language descriptions or visual
representations about the activity, associating actionable information
with various types of objects, communicating or recording activity logs,
or delegation of potential actions to other applications.
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]].
Relationship to Other Social Standards
Activity Streams 2.0 is suitable as a social data syntax. It forms
part of the [[SWP]] suite of related standards.
Relationship to JSON Activity Streams 1.0
The JSON Activity Streams 1.0 [[AS1]] specification was
published in May of 2011 and provided a baseline extensible syntax
for the expression of completed activities. This specification
builds upon that initial foundation by incorporating lessons learned
through extensive implementation, community feedback and related
ongoing work from a variety of other communities.
Some of the issues that specifically motivated the evolution of
Activity Streams 2.0 from Activity Streams 1.0 include:
Multi-lingual representation of activities
Unification of "verb" and "objectType" to "type"
Removal of activity types and object types that weren't core to social
use cases
Introduction of the Link type for richly-described links
Incorporation of audience targeting into the core spec
The generalized "Undo" activity type, so all activities can be undone
Consistent collection and paging representation
Formalizing the namespace of the base vocabulary of object types and
activity types
Extensibility framework for other types and properties
Compatibility with JSON-LD
The terms displayName, verb,
title and objectType should be treated as
reserved terms that SHOULD NOT be used within Activity Streams 2.0
documents. When encountered in an Activity Streams 2.0 document, they
SHOULD be processed in accordance to the guidelines listed in
Serialization
This specification describes a JSON-based [[!RFC7159]] serialization
syntax for the Activity
Vocabulary that conforms to a subset of [[!JSON-LD]] syntax
constraints but does not require JSON-LD processing. While other
serialization forms are possible, such alternatives are not discussed
by this document.
When serialized, absent properties are represented by either (a)
setting the property value to null, or (b) by omitting the property
declaration altogether at the option of the publisher. These
representations are semantically equivalent. If a property has an
array value, the absence of any items in that array MUST be
represented by omitting the property entirely or by setting the value
to null. The appropriate interpretation of an omitted or explicitly
null value is that no value has been assigned as opposed to the view
that the given value is empty or nil.
An Activity Streams
Document is a JSON document whose root value is an
Activity Streams Object of any type, including a
Collection, and whose MIME media type is
"application/activity+json".
Activity Streams 2.0 documents MUST be serialized using the UTF-8
character encoding.
JSON-LD
The serialized JSON form of an Activity Streams 2.0 document MUST
be consistent with what would be produced by the standard
JSON-LD 1.0 Processing Algorithms and API [[!JSON-LD-API]] Compaction
Algorithm using, at least, the normative JSON-LD @context definition
provided here.
Implementations MAY augment the provided @context with additional
@context definitions but MUST NOT override or change the normative
context. Implementations MAY also use additional properties and values
not defined in the JSON-LD @context with the understanding that any
such properties will likely be unsupported and ignored by consuming
implementations that use the standard JSON-LD algorithms. See the
Extensibility section for more information
on handling extensions within Activity Streams 2.0 documents.
JSON-LD uses the special @context property to define the
processing
context. The value of the @context property is defined
by the [[JSON-LD]] specification. Implementations producing Activity
Streams 2.0 documents SHOULD include a @context property
with a value that includes a reference to the normative
Activity Streams 2.0 JSON-LD
@context definition using the URL
"https://www.w3.org/ns/activitystreams". Implementations
MAY use the alternative URL
"http://www.w3.org/ns/activitystreams"
instead. This can be done using a string, object, or array.
Context with a string
Document providing a context as a string.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A note",
"type": "Note",
"content": "My dog has fleas."
}
Context with an object
Document providing context as an object using the @vocab keyword and a prefix for extension terms.
{
"@context": {
"@vocab": "https://www.w3.org/ns/activitystreams#",
"ext": "https://canine-extension.example/terms/",
"@language": "en"
},
"summary": "A note",
"type": "Note",
"content": "My dog has fleas.",
"ext:nose": 0,
"ext:smell": "terrible"
}
Context with an array
Document providing context as an array, and including an alias for an additional term.
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"css": "http://www.w3.org/ns/oa#styledBy"
}
],
"summary": "A note",
"type": "Note",
"content": "My dog has fleas.",
"css": "http://www.csszengarden.com/217/217.css?v=8may2013"
}
When a JSON-LD enabled Activity Streams 2.0 implementation encounters
a JSON document identified using the
"application/activity+json" MIME media type, and
that document does not contain a @context property
whose value includes a reference to the normative
Activity Streams 2.0 JSON-LD
@context definition, the implementation MUST assume that the
normative @context definition still applies.
IRIs and URLs
This specification uses IRIs [[!RFC3987]]. Every URI [[!RFC3986]] is
also an IRI, so a URI may be used wherever an IRI is named. There are
two special considerations: (1) when an IRI that is not also a URI is
given for dereferencing, it MUST be mapped to a URI using the steps in
Section 3.1 of [[!RFC3987]] and (2) when an IRI is serving as an "id"
value, it MUST NOT be so mapped.
Relative IRI (and URL) references SHOULD NOT be used within an
Activity Streams 2.0 document due to the fact that many JSON
parser implementations are not capable of reliably preserving the base
context necessary to properly resolve relative references.
Date and Times
All properties with date and time values MUST conform to the
"date-time" production in [[!RFC3339]] with the one exception
that seconds MAY be omitted. An uppercase "T"
character MUST be used to separate date and time, and an
uppercase "Z" character MUST be used in the absence of a numeric time
zone offset.
This is specified using the following [[ABNF]] syntax description.
The "time-hour", "time-minute", "time-second", "time-secfrac",
"time-offset" and "full-date" constructs are as defined in
[[RFC3339]].
It is important to note that the `time-offset` component does not
correlate to time-zones, and while times that include the
`time-offset` component work well for timestamps, they cannot be
reliably converted to and from local "wall times" without additional
information and processing.
Examples
Following are three examples of activities with varying degrees of detail.
Each example is shown using the normative JSON serialization defined
by this specification.
Minimal Activity
Expresses the statement 'http://www.test.example/martin' created
'http://example.org/foo.jpg'. No additional detail is given.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Martin created an image",
"type": "Create",
"actor": "http://www.test.example/martin",
"object": "http://example.org/foo.jpg"
}
Basic activity with some additional detail
Expresses the statement "Martin Smith added an article to the blog
'Martin's Blog' at 3:04 PM UTC on February 10, 2015." Some additional
details about the article, actor and target blog are given using
properties defined by the
Activity Streams 2.0
Vocabulary.
The Activity Vocabulary
normatively defines the core object types and properties for Activity
Streams 2.0.
The object types defined by the vocabulary are segmented into a set of
eight core types and an extended set of Activity and Object types common
to many social Web applications. The core types include:
Every JSON object in an Activity Streams 2.0 document is either an
Object or a Link. All other types
defined in the Activity Vocabulary, as well as all extension types, are
derived from these two base types.
A JSON object in the Activity Streams 2.0 document is a
Link if either: (a) the object contains a
type property whose value includes "Link" or
(b) any of the types included in the value of the type
property are defined as extensions of Link (see
Mention for
instance); otherwise the JSON object is considered an instance
or extension of Object.
Object
The Object
is the primary base type for the Activity Streams vocabulary.
The Activity Vocabulary
defines a range of Object types that are common to
many social Web applications. This specification stops short of
defining semantically specific properties for most of these objects.
External vocabularies can be used to express additional detail not
covered by the Activity Vocabulary.
Furthermore, while implementations are free to introduce new types of
Objects beyond those defined by the Activity Vocabulary, interoperability
issues can arise when applications rely too much on extension types that
are not recognized by other implementations. Care should be taken to not
unduly overlap with or duplicate the existing Object types.
When an implementation uses an extension type that overlaps with a core
vocabulary type, the implementation MUST also specify the core vocabulary
type. For instance, some vocabularies (e.g. The Good Relations
Vocabulary) define their own types for describing locations. An
implementation that wishes, for example, to use a
http://purl.org/goodrelations/v1#Location
as an object type MUST also identify the object as being a
Place
as illustrated in the following:
Certain properties defined by some External Vocabularies can overlap or
duplicate those defined by the Activity Vocabulary. Where such overlap
exists, for the sake of consistent interoperability, implementations
MUST favor the use of properties defined by the Activity Vocabulary.
Text representations of Object types
Activity Streams consumers often need a text representation of an
Activity Streams object, e.g. for display in a Web browser or console
interface.
The name
property SHOULD be derived from input by the creator or another user.
The summary
property SHOULD be used as a fallback text representation, possibly
automatically generated by the publisher. If there is no name property,
the summary property SHOULD NOT include markup, and SHOULD be short
enough to be used as a reasonable text representation of the object.
A note with a name defined by the author
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"id": "http://example.org/note/123",
"name": "Our Weather Is Fine",
"content": "I feel that the weather is appropriate to our season and location."
}
A note with an automatically-generated summary
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"id": "http://example.org/note/124",
"summary": "A note by Sally",
"content": "Everything is OK here."
}
The name and summary MAY be absent,
MAY lack explicit values in the end user's current language,
and MAY be longer than appropriate for use as a text representation of
the Object in the current language context. Consumer implementations
SHOULD have fallback strategies for text representation of Objects in
these cases.
Link
A Link describes a qualified, indirect reference to another
resource that is closely related to the conceptual model of Links as
established in [[!RFC5988]]. The properties of the Link object are not
the properties of the referenced resource, but are provided as hints
for rendering agents to understand how to make use of the resource. For
example, height and width might represent the
desired rendered size of a referenced image, rather than the actual
pixel dimensions of the referenced image.
For example, all Objects can contain an
image
property whose value describes a graphical representation of the
containing object. This property will typically be used to provide the
URL to an image (e.g. JPEG, GIF or PNG) resource that can be displayed
to the user. Any given object might have multiple such visual
representations -- multiple screenshots, for instance, or the same
image at different resolutions. In Activity Streams 2.0, there are
essentially three ways of describing such references.
To reference a single image without any additional
metadata, a direct association can be expressed as a JSON string
containing an absolute IRI.
Formally, the former example establishes an unqualified
direct relationship with the image resource while the
latter creates a qualified,
indirect relationship that allows additional properties about the
relationship to be specified.
If more than one value is to be expressed, A JSON Array with a
mix of strings and Links can be used:
Individual items contained in such an array are independent of one
another and no significance is given to the ordering.
RFC 5988 defines that all Links have a "link relation" that describes
the contextual purpose of the link. Within a Link,
the rel property
provides the link relation value. If no rel property is
specified, the link relation is considered to be unspecified. Any given
Link can have multiple link relation values. In the JSON
serialization, a single link relation is expressed as a single JSON
string. Multiple link relations are expressed as an array of JSON
strings.
The scope of the link relation is the object in which the Link
is an immediate child.
In the following example, two separate references are provided. The
link relation of the first is unspecified, while the link relation of
the second is "thumbnail".
It ought to be noted that the [[!HTML5]] specification provides its
own alternative definition of a "link relation" that differs slightly
from the [[RFC5988]] definition. In the HTML5 definition, any string
that does not contain the "space" U+0020, "tab" (U+0009), "LF" (U+000A),
"FF" (U+000C), "CR" (U+000D) or "," (U+002C) characters can be used as a
valid link relation. To promote interoperability, Activity Streams 2.0
implementations MUST only use link relations that are syntactically
valid in terms of both the [[RFC5988]] and [[HTML5]] definitions.
Implementations MAY use link relation values that are not registered.
Note that the Link and Object types are disjoint from
one another. That is, any given Object cannot also be a
Link.
Actor
Actor objects are specializations of the base Object
type that represent entities capable of carrying out an
Activity. The Activity
Vocabulary provides the normative definition of five specific
types of Actors:
Application |
Group |
Organization |
Person |
Service.
This specification intentionally defines Actors in only the most
generalized way, stopping short of defining semantically specific
properties for each. All Actor objects are specializations of
Object and inherit all of the core properties
common to all Objects. External vocabularies can be used to express
additional detail not covered by the Activity Vocabulary. VCard
[[vcard-rdf]] SHOULD be used to provide additional metadata for
Person,
Group,
and Organization instances.
An Activity with a Person actor extended with VCard properties:
While implementations are free to introduce new types of Actors beyond
those defined by the Activity Vocabulary, interoperability issues can
arise when applications rely too much on extension types that are not
recognized by other implementations. Care should be taken to not unduly
overlap with or duplicate the existing Actor types.
When an implementation uses an extension type that overlaps with a core
vocabulary type, the implementation MUST also specify the core
vocabulary type. For instance, some vocabularies (e.g. VCard) define
their own types for describing people. An implementation that wishes,
for example, to use a vcard:Individual as an Actor MUST
also identify that Actor as a Person
as illustrated in the previous example.
Activity
Activity objects are specializations of the base Object
type that provide information about actions that have either
already occurred, are in the process of occurring, or may occur
in the future.
The Activity Vocabulary
defines a small number of Activity types that are common
to many social Web applications. This specification stops short of
defining semantically specific properties for most of these activities.
External vocabularies can be used to express additional detail not
covered by the Activity Vocabulary.
While implementations are free to introduce new types of Activites
beyond those defined by the Activity Vocabulary, interoperability
issues can arise when applications rely too much on extension types
that are not recognized by other implementations. Care should be taken
to not unduly overlap with or duplicate the existing Activity types.
When an implementation uses an extension type that overlaps with a core
vocabulary type, the implementation MUST also specify the core
vocabulary type. For instance, some vocabularies (e.g. Schema.org)
define their own types for describing actions. An implementation that
wishes, for example, to use http://schema.org/LikeAction
as an Activity MUST also identify that Object as being a
Like
as illustrated in the following:
An Activity that is both a
Like
and a http://schema.org/LikeAction:
Implementations are free to use Activity objects in both passive and
imperative operations. In the passive sense, the Activity is used
to record that an activity has or is occurring. In the imperative
sense, the Activity can be used as a form of command, instructing
an application to modify state in some manner consistent with the
action being described. However, because this specification does not
define a normative processing model that constrains how applications
make use of the format, the distinction about whether an Activity
statement is to be interpreted as a passive notification or as
an imperative command can vary across implementations.
IntransitiveActivity
IntransitiveActivity objects are specializations of the Activity
type that represent intransitive actions. IntransitiveActivity objects
do not have an object property.
Collection
Collection objects are a specialization of the
base Object that serve as a container for other
Objects or Links.
The items within a Collection can be ordered or
unordered. The OrderedCollection type MAY be
used to identify a Collection whose items are always ordered. In the
JSON serialization, the unordered items of a Collection are
represented using the items property while ordered items
are represented using the orderedItems property.
A Collection can contain a large number of items. Often, it becomes
impractical for an implementation to serialize every item contained
by a Collection using the items (or
orderedItems) property alone. In such cases, the items
within a Collection can be divided into distinct subsets or "pages".
A page is identified using the CollectionPage
type.
The CollectionPage type extends from the base
Collection type and inherits all of it's
properties. The following additional properties can also be
specified:
partOf |
next |
prev |
The partOf property identifies the
Collection to which the items contained by the
CollectionPage belong.
The first, next, prev,
last, and current properties are used
to reference other CollectionPage instances
that contain additional subsets of items from the parent collection.
As with Collection objects, the items within a
CollectionPage might be ordered or unordered.
The OrderedCollectionPage type MAY be used
to identify a page whose items are strictly ordered.
The OrderedCollectionPage type extends from
both CollectionPage and
OrderedCollection. In addition to the properties
inherited from each of those, the OrderedCollectionPage
may contain an additional
startIndex property whose value indicates the relative index position
of the first item contained by the page within the
OrderedCollection to which the page belongs.
An illustration of the relationship between Collection,
OrderedCollection, CollectionPage, and
OrderedCollectionPage:
Whether ordered or not, the pages of a Collection are
typically arranged in a sequence (either a singly or doubly-linked
list). The first property is used to identify the first
page in this sequence, while the last property is used
to identify the final page in the sequence. The prev and
next properties identify the pages immediately before
and immediately following, respectively.
A visualization of the Collection paging model:
The current property identifies a page
containing the subset of items in the Collection that
have been created or updated most recently.
The values for the first, last,
next, prev, and current
properties can be either a single CollectionPage
or a Link referencing a separate resource
containing a CollectionPage.
The following is a simple unordered collection with paging:
Using paging with an OrderedCollection can be tricky
because there are no guarantees that implementations will process the
sequence of pages in any predictable order. Implementations that wish
to reconstruct the appropriate complete ordering of member items in
the logical collection should navigate to the first (or last)
page in the sequence then recursively follow the next
(or prev) link until all pages have been processed.
The pages of an OrderedCollection SHOULD be instances
of OrderedCollectionPage. If the pages of an
OrderedCollection are not instances
of OrderedCollectionPage, a consumer will have
no reliable means of reconstructing the appropriate ordering of items.
Natural Language Values
Several properties defined by the
Vocabulary are defined
as having natural language values. These are human-readable strings using one or more languages. Within the JSON serialization, they are
expressed as either (1) a single JSON string or (2) a JSON object
mapping well-formed [[!BCP47]] Language-Tags to localized, equivalent
translations of the same string value. In the serialized JSON, these
two forms are differentiated using a simple property naming convention,
for instance: "name" identifies the JSON string
form for the name
property while "nameMap" represents the object form.
A single name String value without language information:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Object",
"name": "This is the title"
}
Multiple, language-specific values:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Object",
"nameMap": {
"en": "This is the title",
"fr": "C'est le titre",
"es": "Este es el título"
}
}
Every key in the object form MUST be a well-formed [[!BCP47]]
Language-Tag. The associated values MUST be strings.
The Activity Vocabulary
defines three properties that use natural language values:
name,
summary, and
content.
Accordingly, in the JSON serialization, the terms
"name", "summary", and "content"
represent the JSON string forms; and the terms
"nameMap", "summaryMap", and
"contentMap" for represent the object forms.
The special language tag "und" can be used within the
object form to explicitly identify a value whose
language is unknown or undetermined.
Using the "und" language tag:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Object",
"nameMap": {
"und": "This is the title"
}
}
Default Language Context
When using [[JSON-LD]] mechanisms to produce or consume Activity
Streams 2.0 documents, the @language property MAY be used
within a @context to identify the default language. This
mechanism may not be understood by implementations that do not choose
to process Activity Streams 2.0 documents using JSON-LD.
Specifying the default "@language" within the JSON-LD
@context:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"@language": "en"
}],
"type": "Object",
"name": "This is the title"
}
Bidirectional Text
Natural language values within an Activity Streams 2.0 document MAY
contain bidirectional text. The default base direction of an Activity
Streams 2.0 document is Left-to-Right. The base direction of individual
natural language values MAY be modified as described below.
When specifying bidirectional text for a natural language value,
and the base direction of the text cannot be correctly identified by
the first strong directional character of that text, publishers SHOULD
explicitly identify the default direction either by prefixing the value
with an appropriate Unicode bidirectional control character, or by using
HTML directional markup where permitted.
Consumers of Activity Streams 2.0 documents that contain bidirectional
text SHOULD identify the base direction of any given natural language
value by either scanning the text for the first strong directional
character not contained within a markup tag; or by utilizing
directional markup where provided. Once the base direction has been
identified, consumers MUST determine the appropriate rendering and
display of natural language values, according to the Unicode
Bidirectional Algorithm [[!BIDI]]. This may necessitate wrapping
additional control characters or markup around the string prior to
display, in order to apply the base direction.
Property
Value
Direction
Method
name
"פעילות הבינאום, W3C"
Right-to-Left
First strong directional character
name
"The document was titled, '\u2067פעילות הבינאום, W3C\u2069'"
Left-to-Right
First strong directional character
name
"\u200FHTML היא שפת סימון"
Right-to-Left
Bidi Control Character
name
"\u200E'سلام' is hello in Persian."
Left-to-Right
Bidi Control Character
summary
<p dir=\"rtl\">HTML היא שפת סימון>/p>
Right-to-Left
HTML Markup
summary
<p>פעילות הבינאום, W3C</p>
Right-to-Left
First strong directional character (ignoring markup)
summary
<p title="سلام">Hello</p>
Left-to-Right
First strong directional character (ignoring markup)
Marking up language
Activity Streams 2.0 publishers SHOULD explicitly mark the language of
natural language properties if they are known, using either map properties
or a default language tag.
Not all examples in this specification explicitly mark the language of
natural language properties. This is intentional. The authors and the
working group wished to avoid having implementers cut-and-paste examples
from the document with explicit language markup as a template for new
documents, which would consequently have inaccurate language markup.
Extensibility
In Activity Streams 2.0, an "extension" is any property, activity,
actor or object type not defined by the
Activity Vocabulary.
Consuming implementations that encounter unfamiliar
extensions MUST NOT stop processing or signal an error and MUST
continue processing the items as if those properties were not
present. Note that support for extensions can vary across
implementations and no normative processing model for extensions is
defined. Accordingly, implementations that rely too heavily on
the use of extensions may experience reduced interoperability with
other implementations.
For extensions, [[JSON-LD]] is used as the primary mechanism for
defining and disambiguating extensions. Implementations that wish to
fully support extensions SHOULD use [[JSON-LD]] mechanisms.
It is important to note that the JSON-LD Processing Algorithms
[[JSON-LD-API]], as currently defined, will silently ignore any
property not defined in a JSON-LD @context. Implementations that
publish Activity Streams 2.0 documents containing extension
properties SHOULD provide a @context definition for all extensions.
It is also important to note that there are valid JSON constructs which
cannot be used within a JSON-LD document. For instance, JSON-LD forbids
"arrays of arrays" as used, for example, by the popular
GeoJSON specification. While
implementations are free to use such constructs as extensions within an
Activity Streams 2.0 document, consumers that use the standard JSON-LD
Processing Algorithms will be required to either ignore such extensions
or map those to alternative compatible constructs prior to applying the
JSON-LD algorithms. Simple GeoJSON Points, for instance, can be mapped
to Place
objects, while more complex geometries can be converted to
GeoSparql
"Well-Known Text" representations as illustrated in the non-normative
examples below:
The JSON-LD syntax supports the use of "Compact URIs". A "Compact URI" is an
alternative encoding of a URI that uses
a defined prefix to simplify serialization. For instance, the URI
http://example.org/term can be
represented as ex:term by assigning the ex:
prefix the value of http://example.org/
Within JSON-LD, Compact URI prefixes are defined within the JSON-LD
@context definition. For example:
In this example, both the property name term and the value
ex:Foo are Compact URIs. The property name term
expands to http://example.org/term and the value
ex:Foo expands to http://example.org/Foo
In JSON-LD, Compact URI expansion of values applies to
properties explicitly defined as "@type": "@id" in the
@context definition. Specifically, Compact URIs can be used
anywhere an IRI (or URI) value is expected.
Activity Streams 2.0 implementations that wish to fully support extensions
MUST support Compact URI expansion as defined by the JSON-LD specification.
Such expansion applies to all property names as well as all property values
explicitly defined as type @id in the JSON-LD @context.
Over reliance on the Compact URI form can lead to ambiguity and
interoperability issues between implementations. Therefore, Compact URI use
SHOULD be avoided in all cases other than property names and the value(s)
of the type property.
Re-serialization of Extensions
Implementations that use JSON-LD mechanisms to parse and then
reserialize Activity Streams 2.0 documents that contain extension
properties SHOULD take sufficient care to ensure that extension
properties used within the original document are preserved and
serialized appropriately.
For instance, consider the following simple Activity Stream object
containing hypothetical foo and bar extension
properties. The foo extension is defined within the
JSON-LD @context while the bar extension
property is not.
A simple extended Object
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{"foo": "http://example.org/foo"}
],
"type": "Note",
"content": "This is a simple note",
"foo": 123,
"bar": 321
}
An implementation that receives this Note object can choose to parse
the object as an ordinary JSON object or it can use the standard
JSON-LD Expansion algorithm.
If the implementation chooses to parse the object as ordinary JSON
and then reserializes the object (e.g. for storage or redistribution),
then it would simply preserve the values of the @context,
foo and bar properties as they are and
include those in the reserialized output.
However, if the implementation chooses to use the JSON-LD expansion
algorithm, the @context will be removed from the expanded
result and the bar property will be mapped to the
"blank node" _:bar. If this document is then reserialized
using the normative Activity Streams 2.0 context, the JSON-LD
compacted form would be:
The reserialized compacted form:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"content": "This is a simple note",
"http://example.org/foo": 123,
"bar": 321
}
While this is close to the original, the use of fully expanded URI
label for the foo property is not ideal. To ensure that
the reserialized object is serialized correctly, implementations that
perform JSON-LD expansion of received documents SHOULD preserve the
original @context used when performing the JSON-LD
expansion, then reuse that when reserializing the object into the
JSON-LD compacted form.
Vocabulary
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]].
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.
Core Types
The Activity Vocabulary Core Types provide the basis for the rest of
the vocabulary.
Describes an object of any kind. The Object type serves as the
base type for most of the other kinds of objects defined in the
Activity Vocabulary, including other Core types such as
Activity,
IntransitiveActivity,
Collection and
OrderedCollection.
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.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Activity",
"summary": "Sally did something to a note",
"actor": {
"type": "Person",
"name": "Sally"
},
"object": {
"type": "Note",
"name": "A Note"
}
}
Notes:
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.
Instances of IntransitiveActivity are a subtype of
Activity representing intransitive actions. The
object property is
therefore inappropriate for these activities.
Used to represent distinct subsets of items from a
Collection. Refer to the
Activity Streams 2.0 Core for a complete description of the
CollectionPage object.
Used to represent ordered subsets of items from an
OrderedCollection. Refer to the
Activity Streams 2.0 Core for a complete description of the
OrderedCollectionPage object.
The Activity Streams 2.0 Extended Types include Activity and Object
subtypes that are common to many social Web applications. They are
divided into three sets:
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.
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).
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally accepted an invitation to a party",
"type": "Accept",
"actor": {
"type": "Person",
"name": "Sally"
},
"object": {
"type": "Invite",
"actor": "http://john.example.org",
"object": {
"type": "Event",
"name": "Going-Away Party for Jim"
}
}
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally accepted Joe into the club",
"type": "Accept",
"actor": {
"type": "Person",
"name": "Sally"
},
"object": {
"type": "Person",
"name": "Joe"
},
"target": {
"type": "Group",
"name": "The Club"
}
}
Notes:
Indicates that the actor accepts the
object. The target property can be used
in certain circumstances to indicate the context into which the
object has been accepted.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally added a picture of her cat to her cat picture collection",
"type": "Add",
"actor": {
"type": "Person",
"name": "Sally"
},
"object": {
"type": "Image",
"name": "A picture of my cat",
"url": "http://example.org/img/cat.png"
},
"origin": {
"type": "Collection",
"name": "Camera Roll"
},
"target": {
"type": "Collection",
"name": "My Cat Pictures"
}
}
Notes:
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).
The target and origin typically
have no defined meaning.
Indicates that the actor has updated the
object. Note, however, that this vocabulary
does not define a mechanism for describing the actual
set of modifications made to object.
The target and
origin typically have no defined meaning.
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.
Indicates that the actor is "flagging" the
object. Flagging is defined in the sense common to
many social platforms as reporting content as being inappropriate
for any number of reasons.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Question",
"name": "What is the answer?",
"closed": "2016-05-10T00:00:00Z"
}
Notes:
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.
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).
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Article",
"name": "What a Crazy Day I Had",
"content": "<div>... you will never believe ...</div>",
"attributedTo": "http://sally.example.org"
}
Notes:
Represents any kind of multi-paragraph written work.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"name": "A Word of Warning",
"content": "Looks like it is going to rain today. Bring an umbrella!"
}
Notes:
Represents a short written work typically less than a single paragraph in length.
A Profile is a content object that describes another Object,
typically used to describe Actor Type
objects. The describes property is
used to reference the object being described by the profile.
A Tombstone represents a content object that has been deleted. It
can be used in Collections to signify that there used to be
an object at this position, but it has been deleted.
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.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally and Joe offered the Foo object",
"type": "Offer",
"actor": [
"http://joe.example.org",
{
"type": "Person",
"id": "http://sally.example.org",
"name": "Sally"
}
],
"object": "http://example.org/foo"
}
Notes:
Describes one or more entities that either performed or are
expected to perform the activity. Any single activity can have
multiple actors. The actor MAY be
specified using an indirect Link.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"name": "Have you seen my cat?",
"attachment": [
{
"type": "Image",
"content": "This is what he looks like.",
"url": "http://example.org/cat.jpeg"
}
]
}
Notes:
Identifies a resource attached or related to an object
that potentially requires special handling. The intent is to
provide a model that is at least semantically similar to
attachments in email.
Identifies one or more entities to which this object is attributed.
The attributed entities might not be Actors. For instance, an object
might be attributed to the completion of another activity.
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.
Indicates an entity that describes an icon for this object.
The image should have an aspect ratio of one (horizontal)
to one (vertical) and should be suitable for presentation at a
small size.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"content": "This is all there is.",
"inReplyTo": {
"summary": "Previous note",
"type": "Note",
"content": "What else is there?"
}
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"content": "This is all there is.",
"inReplyTo": "http://example.org/posts/1"
}
Notes:
Indicates one or more entities for which this object is considered
a response.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally listened to a piece of music on the Acme Music Service",
"type": "Listen",
"actor": {
"type": "Person",
"name": "Sally"
},
"object": "http://example.org/foo.mp3",
"instrument": {
"type": "Service",
"name": "Acme Music Service"
}
}
Notes:
Identifies one or more objects used (or to be used) in the
completion of an Activity.
Identifies an exclusive option for a Question. Use of
oneOf implies that the Question can have only a single
answer. To indicate that a Question can have multiple answers, use
anyOf.
Identifies an inclusive option for a Question. Use of
anyOf implies that the Question can have multiple
answers. To indicate that a Question can have only one answer, use
oneOf.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally moved a post from List A to List B",
"type": "Move",
"actor": "http://sally.example.org",
"object": "http://example.org/posts/1",
"target": {
"type": "Collection",
"name": "List B"
},
"origin": {
"type": "Collection",
"name": "List A"
}
}
Notes:
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".
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally liked a note",
"type": "Like",
"actor": "http://sally.example.org",
"object": [
"http://example.org/posts/1",
{
"type": "Note",
"summary": "A simple note",
"content": "That is a tree."
}
]
}
Notes:
When used within an Activity, describes the
direct object of the activity. For instance, in the activity
"John added a movie to his wishlist", the object of the activity
is the movie added.
When used within a Relationship describes
the entity to which the subject is
related.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally checked that her flight was on time",
"type": ["Activity", "http://www.verbs.example/Check"],
"actor": "http://sally.example.org",
"object": "http://example.org/flights/1",
"result": {
"type": "http://www.types.example/flightstatus",
"name": "On Time"
}
}
Notes:
Describes the result of the activity. For instance, if a particular
action results in the creation of a new resource, the result
property can be used to describe that new resource.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"id": "http://www.test.example/notes/1",
"content": "I am fine.",
"replies": {
"type": "Collection",
"totalItems": 1,
"items": [
{
"summary": "A response to the note",
"type": "Note",
"content": "I am glad to hear it.",
"inReplyTo": "http://www.test.example/notes/1"
}
]
}
}
Notes:
Identifies a Collection containing objects
considered to be responses to this object.
One or more "tags" that have been associated with an object.
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 association by reference.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally offered the post to John",
"type": "Offer",
"actor": "http://sally.example.org",
"object": "http://example.org/posts/1",
"target": "http://john.example.org"
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally offered the post to John",
"type": "Offer",
"actor": "http://sally.example.org",
"object": "http://example.org/posts/1",
"target": {
"type": "Person",
"name": "John"
}
}
Notes:
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.
Indicates the altitude of a place. The measurement units is
indicated using the units property. If
units is not specified, the default is assumed
to be "m" indicating meters.
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"content": "A <em>simple</em> note"
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"contentMap": {
"en": "A <em>simple</em> note",
"es": "Una nota <em>sencilla</em>",
"zh-Hans": "一段<em>简单的</em>笔记"
}
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "A simple note",
"type": "Note",
"mediaType": "text/markdown",
"content": "## A simple note\nA simple markdown `note`"
}
Notes:
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.
The content MAY be expressed using multiple language-tagged
values.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"name": "A simple note"
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"nameMap": {
"en": "A simple note",
"es": "Una nota sencilla",
"zh-Hans": "一段简单的笔记"
}
}
Notes:
A simple, human-readable, plain-text name for the object. HTML
markup MUST NOT be included. The name MAY be expressed
using multiple language-tagged values.
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").
When used on a Link, identifies the MIME media type of the
referenced resource.
When used on an Object, identifies the MIME media
type of the value of the content property.
If not specified, the content property is
assumed to contain text/html content.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Event",
"name": "Going-Away Party for Jim",
"startTime": "2014-12-31T23:00:00-08:00",
"endTime": "2015-01-01T06:00:00-08:00"
}
Notes:
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.
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Event",
"name": "Going-Away Party for Jim",
"startTime": "2014-12-31T23:00:00-08:00",
"endTime": "2015-01-01T06:00:00-08:00"
}
Notes:
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.
The radius from the given latitude and longitude for a Place.
The units is expressed by the units property.
If units is not specified, the default is
assumed to be "m" indicating "meters".
A link relation associated with a Link. The
value MUST conform to both the [[HTML5]] and [[RFC5988]]
"link relation" definitions.
In the [[HTML5]], any string not containing the "space" U+0020,
"tab" (U+0009), "LF" (U+000A), "FF" (U+000C), "CR" (U+000D) or ","
(U+002C) characters can be used as a valid link relation.
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.
Specifies the measurement units for the radius
and altitude properties on a
Place object. If not specified, the default is
assumed to be "m" for "meters".
{
"@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"
}
{
"@context": "https://www.w3.org/ns/activitystreams",
"summary": "Sally is an acquaintance of John's",
"type": "Relationship",
"subject": {
"type": "Person",
"name": "Sally"
},
"relationship": "http://purl.org/vocab/relationship/acquaintanceOf",
"object": {
"type": "Person",
"name": "John"
}
}
Notes:
On a Relationship object, the subject
property identifies one of the connected individuals. For
instance, for a Relationship object describing
"John is related to Sally", subject would refer to
John.
Activity Streams 2.0 documents can (and likely will) contain potentially
sensitive personal information such as identity, contact information,
physical location, physical characteristics, and so forth. Furthermore,
Activity data, in general, can be analyzed to generate profiles of the
behavior of individual or groups of Actors.
Implementations that produce or consume Activity Streams 2.0 documents
MUST take steps to openly and publicly document and communicate to all
potential users: (a) the kinds of potentially sensitive personal
information published, consumed or collected by the implementation, (b)
the reasons for publishing, consuming and collecting that information,
(c) the manner in which that information is being used, (d) the
identity of any other party with whom that information is being shared,
and (e) the reason the information is being shared with other parties.
Implementations that publish Activity Streams 2.0 documents SHOULD
assume a default position of limiting both the kind and amount of
sensitive personal information included in the document unless users have
"opted in" to sharing additional detail.
Implementations that consume Activity Streams 2.0 documents SHOULD NOT,
by default, store or share sensitive personal information included within
consumed documents unless users have "opted in" to allowing that
information to be stored or shared.
In this context, "opting in" does not necessarily require explicit
action on the part of the user. If, for instance, the use of certain
sensitive personal information is clearly implicit in the use of an
implementation (a location tracking service, for example), then any
use of that implementation can be considered an implicit acknowledgement
that the sensitive personal information will be used and shared so long
as the documentation guidelines listed above are followed.
Security Considerations
Publishers or Consumers implementing Activity Streams as a stream of
public data may also want to consider the potential for unsolicited
commercial or malicious content and should take preventative measures
to recognize such content and either identify it or not include it in
their implementations.
Publishers should take reasonable measures to ensure potentially
malicious user input such as cross-site scripting attacks are not
included in the Activity Streams data they publish.
Consumers that re-emit ingested content to end-users MUST take
reasonable measures if emitting ingested content to make sure
potentially malicious ingested input is not re-emitted.
Consumers that re-emit ingested content for crawling by search
engines should take reasonable measures to limit any use of their
site as a Search Engine Optimization loophole. This may include
converting untrusted hyperlinks to text or including a
rel="nofollow" attribute.
Consumers should be aware of the potential for spoofing attacks where
the attacker publishes activities or objects with falsified property
values with the intent of injecting malicious content, hiding or
corrupting legitimate content, or misleading users.
Activity Streams are JSON Documents and are subject to the same
security considerations described in [[!RFC7159]].
Activity Streams implementations handle URIs. See Section 7 of
[[!RFC3986]].
Activity Streams implementations handle IRIs. See Section 8 of
[[!RFC3987]].
IANA Considerations
The application/activity+json Media Type
This specification registers the application/activity+json MIME Media Type specifically for identifying documents
conforming to the Activity Streams 2.0 format.
Type name:
application
Subtype name:
activity+json
Required parameters:
None
Optional parameters:
profile: The profile parameter for the application/activity+json
media type allows one or more profile URIs to be specified. These
profile URIs have the identifier semantics defined in [[!RFC6906]].
The "profile" media type parameter MUST be quoted. It contains a
non-empty list of space-separated URIs (the profile URIs).
The "URI" in the above grammar refers to the "URI" as defined in
Section 3 of [[!RFC3986]].
Encoding considerations:
Resources that use the "application/activity+json"
Media Type are required to conform to all of the requirements
for the "application/json" Media Type and are
therefore subject to the same encoding considerations specified
in Section 11 of [[!RFC7159]].
Note that while the Activity Streams 2.0 format uses JSON-LD
conventions, there are a number of constraints and additional
requirements for Activity Streams 2.0 implementations that justify
the use of a specific media type.
Because Activity Streams 2.0 can be considered a restricted profile
of JSON-LD, Implementations SHOULD consider the
`application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
media type as being equivalent to `application/activity+json`.
Fragment identifiers used with application/activity+json are treated as in RDF syntaxes, as per [[[RDF11-CONCEPTS]]].
Conformance
All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
Documents
Conforming documents are those that comply with all the conformance
criteria for documents. For readability, some of these conformance
requirements are phrased as conformance requirements on publishers;
such requirements are implicitly requirements on documents: by
definition, all documents are assumed to have a publisher.
Conforming documents must not include deprecated or obsolete syntax
from Activity Streams 1.0. Conforming documents must include properties
and types from the Activity Vocabulary. Conforming documents that use
other vocabularies must also include equivalent Activity Vocabulary
properties and types as illustrated in Section C. Conforming documents
must not use features of JSON-LD or other serialization features
disallowed in this specification, as in Section 2. Conforming
documents that include types or properties beyond those defined in the
Activity Streams 2.0 Vocabulary must use the extensibility features
defined in section 5.
A non-exhaustive list of examples of documents includes:
A document representing an actor
A document representing an object
A document representing an activity
A document representing a collection of the activities done by an
actor
A document representing a collection of the activities done to an
object
A document representing a collection of the activities addressed
to an actor or object
Implementations
Conforming implementations are software that publish, store, analyze,
consume or otherwise process conforming documents. The two main kinds
of implementations are publishers and consumers.
Publishers
Conforming publishers are implementations that create and publish
conforming documents. Conforming publishers must make conforming
documents available according to the serialization requirements of
section 2. Conforming publishers must consider privacy as described
in section 6. Conforming publishers must consider security as
described in section 7.
A non-exhaustive list of example publishers includes:
A social network
A personal web site
A document publishing system
A bridge from a non-conforming social network
A document converter from similar document types such as RSS or
Atom
Consumers
Conforming consumers are implementations that read and analyze
conforming documents. Conforming consumers must tolerate deprecated or
obsolete properties or types from Activity Streams 1.0. Conforming
consumers must ignore properties or types that are not applicable to
their application domain.
Conforming consumers may re-publish conforming documents in other
other data formats. Conforming consumers may present conforming
documents to a user on screen, in print, in audio format, or using
other presentation mechanisms. Conforming consumers must faithfully
translate the information represented in conforming documents into
these other formats or media. Conforming consumers that re-publish
conforming documents must consider privacy as described in section 6
and security as described in section 7.
A non-exhaustive list of example consumers includes:
A social network
A search engine
A feed reader
A document validator
A feed aggregator
A statistical analyzer
Acknowledgements
The Activity Streams 2.0 specification is a product of the W3C
Social Web Working Group. The editors thank all of the Working
Group members who contributed to the conversations, issues and
testing that helped shape the current specification.
The editor's also wish to thank all of those who contributed to
Activity Streams prior to the specification being picked up as a
contribution to the W3C Social Web Working Group. Activity Streams 1.0
was a community driven effort and the specification would not be where it
is today without the earlier contributions from the community, 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
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 Cappelaere, 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 Çelik, Tatu Saloranta, Tim Moore, Timothy Young,
Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley,
Laurent-Walter Goix, Matthew Marum, Andy Smith, and Zach Shepherd.
Deprecated Activity Streams 1.0 Syntax
Note: While this appendix sections is non-normative, it uses normative
terms such as MUST. Where used, the meaning is to indicate what would
be required to properly implement the Activity Streams 1.0 backwards
compatibility model described in this appendix if an implementer chose
to do so.
While the syntax defined by this specification diverges from
that defined by JSON Activity Streams 1.0, the fundamental model
defined by that original specification remains intact. Specific
processing rules are defined by
this specification that allow existing Activity Streams 1.0
documents to be mapped to and processed as an Activity Streams 2.0
document.
The JSON syntax defined by this specification differs somewhat from
that defined in the original JSON Activity Streams 1.0
[[AS1]] specification in ways that are not backwards
compatible. Implementations can choose to continue supporting the
JSON Activity Streams 1.0 syntax but ought consider it to be
deprecated. This means that while implementations can continue to
consume the 1.0 syntax, they should not output the 1.0 syntax unless
specifically interacting with older non-2.0 compliant
implementations.
Specifically:
Implementations can use the "application/stream+json" MIME
media type when producing a JSON serialization using the Activity
Streams 1.0 syntax, and "application/activity+json"
when producing a serialization conforming to the 2.0 syntax.
Implementations that process serializations identified using either
the "application/stream+json" or the more
generic "application/json" MIME media type MUST follow
the syntax and processing rules set by [[AS1]]. The 2.0
syntax and processing rules apply only when handling
serializations using the "application/activity+json" media
type.
When processing Activity Streams 1.0 documents using a JSON-LD
processing model, implementations can use the special AS 1.0 to AS 2.0
expansion @context definition provided
here to produce
the JSON-LD expanded representation. Refer to the
JSON-LD
Processing Algorithms and API for details.
When processing Activity Streams 1.0 documents and converting those to
2.0, implementations ought to treat id as an alias for the
JSON-LD @id key word; and the objectType and
verb properties as aliases for the JSON-LD
@type keyword.
Activity Streams 1.0 uses the displayName property which
has been renamed to name in Activity Streams 2.0.
Implementations ought to treat displayName as an alias
for name.
Activity Streams 1.0 uses the title property which has
been dropped from Activity Streams 2.0. Implementations processing
Activity Streams 1.0 documents as Activity Streams 2.0 ought to treat
instances of the title property as an extension.
This document redefines the
content and
summary
properties as natural language values which means their values can be expressed
as either a string or an object mapping language tags to string values.
In the 1.0 syntax, these are expressed solely as String values. Because
the 1.0 values are a valid subset allowed by this specification,
implementations are not required to take any specific action to continue
supporting those values.
This document redefines a large number of common properties
defined originally as Objects in 1.0 as either
Objects or Links. The JSON-LD
serialization allows such property values to be expressed as either an
IRI String, an JSON object, or an Array of IRI Strings and JSON objects.
Because the 1.0 values are a valid subset allowed by this specification,
existing implementations are not required to take any specific action to
continue supporting those values.
This specification deprecates the upstreamDuplicates and
downstreamDuplicates properties defined by Activity Streams
1.0 and does not provide a replacement. This is due largely to lack of any
reasonable implementation evidence. While the
upstreamDuplicates and downstreamDuplicates
properties MAY continue to be used, implementations SHOULD avoid them.
In Activity Streams 1.0, the "post" verb was defined to
describe the action of both creating an object and "posting" or uploading
it to a service. This specification replaces the "post" verb
with separate
Create and
Add
Activity types. When processing Activity Streams 1.0 documents and
converting those into 2.0, implementations SHOULD treat instances of the
"post" verb as equivalent to
Createif there is no target property specified; and
equivalent to
Addif there is a target property specified.
By following these guidelines, all JSON Activity Streams 1.0
serializations can be processed successfully by 2.0 implementations.
Example using Multiple Vocabularies
It is possible use multiple vocabularies to cover particular
characteristics of the activities like data provenance and annotations,
which can compliment the Activity Vocabulary. For example: Eric writes a
short note to be shared with his followers. After posting the note, he
notices a spelling error. He edits the note and re-posts it. Later, Eric
decides that the information in the note is incorrect. He deletes the
note.
A series of activities; creating, editing, and deleting a note.
The following notable changes have been made to this document since the
previous candidate recommendation of 2016-12-15.
Removed process sections, especially those noting exit criteria and
at-risk features.
Updated Collection Paging to clarify additional
CollectionPage properties.
Used better wording for summary as text representation.
Updated context examples to include more realistic complex contexts.
Implementation Notes
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.
Audience and Context
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:
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:
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:
{
"@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:56Z"
}
}
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.
Modeling "friend requests"
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:
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "http://example.org/connection-requests/123",
"summary": "Sally requested to be a friend of John",
"type": "Offer",
"actor": "acct:sally@example.org",
"object": {
"summary": "Sally and John's friendship",
"id": "http://example.org/connections/123",
"type": "Relationship",
"subject": "acct:sally@example.org",
"relationship": "http://purl.org/vocab/relationship/friendOf",
"object": "acct:john@example.org"
},
"target": "acct:john@example.org"
}
Assuming the "friend request" is accepted, the remaining steps
in this common application scenario can be represented as a
set of distinct activities:
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.
Representing Places
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.
Representing Questions
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:
{
"@context": "https://www.w3.org/ns/activitystreams",
"name": "A question about robots",
"id": "http://help.example.org/question/1",
"type": "Question",
"content": "I'd like to build a robot to feed my cat. Should I use Arduino or Raspberry Pi?"
}
Multiple-choice questions or "polls" are also supported using either the
oneOf or anyOf properties:
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "http://polls.example.org/question/1",
"name": "A question about robots",
"type": "Question",
"content": "I'd like to build a robot to feed my cat. Which platform is best?",
"oneOf": [
{"name": "arduino"},
{"name": "raspberry pi"}
]
}
Responses to questions are expressed as
Objects containing an
inReplyto property referencing the Question.
Because Question objects are also instances of
Activity, the result property
can be used to express the results or outcome of the Question (as
appropriate):
{
"@context": "https://www.w3.org/ns/activitystreams",
"name": "A question about robots",
"id": "http://polls.example.org/question/1",
"type": "Question",
"content": "I'd like to build a robot to feed my cat. Which platform is best?",
"oneOf": [
{"name": "arduino"},
{"name": "raspberry pi"}
],
"replies": {
"type": "Collection",
"totalItems": 3,
"items": [
{
"attributedTo": "http://sally.example.org",
"inReplyTo": "http://polls.example.org/question/1",
"name": "arduino"
},
{
"attributedTo": "http://joe.example.org",
"inReplyTo": "http://polls.example.org/question/1",
"name": "arduino"
},
{
"attributedTo": "http://john.example.org",
"inReplyTo": "http://polls.example.org/question/1",
"name": "raspberry pi"
}
]
},
"result": {
"type": "Note",
"content": "Users are favoriting "arduino" by a 33% margin."
}
}
Inverse Activities and "Undo"
Several of the core Activity types are
defined as natural inversions of one another. These include:
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.
Mentions, Tags and Other Common Social Microsyntaxes
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 can be used within the values of the content,
name, and summary
properties on an Activity Streams Object,implementations are not expected to parse the values of those properties in order to determine the appropriate routing of notifications, categorization, or linking between objects. Instead, publishers are expected to make appropriate use of the vocabulary terms provided specifically for these purposes to communicate information to consumers.
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:
A simple note with a mention an a hashtag:
"Thank you @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 following illustrates an equivalent Activity Streams
Note object:
{
"@context": "https://www.w3.org/ns/activitystreams",
"name": "A thank-you note",
"type": "Note",
"content": "Thank you <a href='http://sally.example.org'>@sally</agt for all your hard work! <a href='http://example.org/tags/givingthanks'>#givingthanks</a>",
"to": {
"name": "Sally",
"type": "Person",
"id": "http://sally.example.org"
},
"tag": {
"id": "http://example.org/tags/givingthanks",
"name": "#givingthanks"
}
}
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.
{
"@context": "https://www.w3.org/ns/activitystreams",
"name": "A thank-you note",
"type": "Note",
"content": "Thank you @sally for all your hard work! #givingthanks",
"tag": [
{
"type": "Mention",
"href": "http://example.org/people/sally",
"name": "@sally"
},
{
"id": "http://example.org/tags/givingthanks",
"name": "#givingthanks"
}
]
}
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:
{
"@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.
Activity Type Motivating Use Cases
The Activity types defined in this
vocabulary have been primarily selected to address the commonly implemented social use cases described below.
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".
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.
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.
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.
The Content Experience use case primarily deals with describing
activities involving listening to, reading, or viewing content.
For instance, "Sally read the article", "Joe listened to the song".
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".
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 for more information.
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 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.
Changelog
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.
Removed process sections, especially those noting exit criteria and
at-risk features.
