Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification details a model for representing potential and completed activities using the JSON format.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document was published by the Social Web Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to email@example.com (subscribe, archives). All comments are welcome.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 August 2014 W3C Process Document.
In the most basic sense, an "activity" is a semantic description of a potential or completed action. In the former case, the activity expresses what can or might be done with a particular object, while in the latter case, it expresses what has already been done.
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, machine-processable and extensible manner. This may 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].
This section is non-normative.
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.
While the syntax defined by this specification diverges somewhat from that defined by JSON Activity Streams 1.0, the verbs, objectTypes, extensions and fundamental model defined by that original specification remain intact, and every valid Activity Streams 1.0 document is a valid Activity Streams 2.0 document.
Please refer to Section 6 for more detail about the differences between the 1.0 and 2.0 syntax and for a listing of specific backwards compatibility requirements.
This specification incorporates several existing extensions to the 1.0 syntax directly into the 2.0 model. These include portions of the Activity Streams 1.0 Base Schema, Audience Targeting, Responses, and Priority extensions.
This specification describes a JSON-based [RFC7159] serialization syntax for the Activity Vocabulary that follows the conventions defined by the [JSON-LD] specification. While serialization forms other than JSON-LD are possible, 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.
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.
Unless otherwise specified, all properties with date and time values MUST conform to the "date-time" production in [RFC3339], with an uppercase "T" character used to separate date and time, and an uppercase "Z" character in the absence of a numeric time zone offset. All such timestamps SHOULD be represented relative to Coordinated Universal Time (UTC).
Activity Streams 2.0 documents MUST be serialized using the UTF-8 character encoding.
This section is non-normative.
Following are three examples of activities with varying degrees of detail. Each of the examples uses an implied JSON-LD @context equal to that provided here.
The Activity Vocabulary defines the abstract model for Activity Streams 2.0. The vocabulary document defines seven distinct abstract classes: Object, Link, Collection, Activity, NaturalLanguageValue, Verb, and ObjectType. Each of these classes is described and illustrated below.
class is the primary base class for the Activity Streams vocabulary. An
implementations would typically create it's own set of subclasses that
derive from the
http://activitystrea.ms/2.0/Object class as
opposed to using
In addition to having a global identifier in the form of an absolute IRI
and an "object type" (expressed in JSON-LD using the
all instances of the
Object class share a common set of properties
as defined by the Activity Vocabulary.
While all properties are optional, all
Object instances SHOULD
at least contain a displayName.
Several properties defined by the Vocabulary are defined as being a Natural Language Value. These are a representations of human-readable character sequences using one or more languages. Within the JSON-LD serialization, they are expressed as either (1) a single JSON string or (2) a JSON object mapping [RFC5646] Language-Tags to localized, equivalent translations of the same string value. In [JSON-LD], such constructs are referred to as "Language Maps".
For instance, the
property is a Natural Language value.
Every key in the JSON object MUST be an [RFC5646] Language-Tag. The associated values MUST be Strings.
This section is non-normative.
Implementers ought to note that, in [JSON-LD], establishment of a default
language requires the use of the
@language keyword inside the
@context. For instance:
@language keyword in this manner establishes the
default language context for all string literal property values contained
by the object, including those that may not be intended as natural language
values. This current definition for
@language makes it difficult
for implementations that choose to ignore JSON-LD semantics when processing
Activity Streams documents or that wish to limit the language context only to
properties that are truly intended as natural language values. The
property introduced by the Activity Streams Vocabulary is provided to address
these shortcomings by allowing a default language to be established independently
of the JSON-LD
However, use of
means that JSON-LD based implementations will need to take an additional
processing step to ensure that properties such as
content are handled properly.
Link represents a dereferenceable pointer to another resource.
Within the JSON-LD serialization, they are expressed as either: (1) a String
containing an absolute or relative IRI, (2) a JSON object, or (3) an Array
containing a mixture of IRIs or JSON objects. Links are closely related to
the conceptual model of Links as established in [RFC5988].
The target URI of the Link is the global identifier expressed in the JSON-LD
serialization using the
@id keyword. In addition, all
instances share the following common set of properties as defined by the
For example, all Objects can contain an
property whose value describes a graphical
representation of the containing object. This property will
typically be used to provide the URL to a JPEG, GIF or PNG type
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. Using Links,
there are essentially three ways of describing such references.
Formally, the former example establishes a unqualified
relationship to the image resource while the latter creates a
qualified relationship that allows additional properties
to be specified for the link. Such properties (e.g.
rel, etc) describe the Link
relationship itself as opposed to describing the referenced resource. For
many practical applications, this distinction will likely be fairly
insignificant but it is still worth keeping in mind.
Individual items contained in such an array are independent of the others and no significance is given to the ordering of those items.
RFC 5988 defines that all Links have a "link relation" that describes
the contextual purpose of the link. Within a Link,
provides the link relation value. If no
rel property is
specified, the Link is not considered to have a specified link relation.
In the following example, two separate links are provided. The link
relation of the first is unspecified, while the link relation of the
second is "
preview". Either link, however, can be used as
alternative visual representations of the object.
It ought to be noted that the [HTML5] specification provides it's 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 valid in terms of both the [RFC5988] and [HTML5] definitions.
Also note that it is possible to use Link and Object together to indicate
that a particular JSON object can be interpretted as both. For instance, in the
following example, the value of the
image property is marked as being
both a Link and a hypothetical
urn:example:image object that,
for the sake of this example, derives from
Object. This allows additional
properties describing the Object -- such as
to be specified.
Activity objects are specializations of the base Object type that provide information about ongoing or completed actions.
In additional to common properties supported by all Object
Activity objects support the following additional
properties defined by the Vocabulary:
verb property is used to identify the type of activity.
verb is not specified, the
MAY be used as an alternative means of determining the activity type.
This section is non-normative.
Since Activity Streams 1.0, the
verb property has
been defined to permit identifiers either in the form of absolute IRI's
isegment-nz-nc tokens. For instance,
post" is a valid Activity Streams verb.
However, existing JSON-LD processing algorithms have difficulty
isegment-nz-nc token values properly
without additional processing. It is RECOMMENDED that JSON-LD
implementations handle simple
as "blank nodes". For instance, the value "
map to the blank node identified as
Every Activity has both a Primary and Secondary audience. The Primary audience consists of those entities either directly involved in the performance of the activity or who "own" the objects involved. The Secondary audience consists of the collection of entities sharing an interest in the activity but who are not 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 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 verb, actor, object and target of
the activity, to infer the primary audience for many types of
activities, those do not work in every case and do not provide a
means of identifying the secondary audience. The
properties MAY be used within an Activity to explicitly identify the
Primary and Secondary audiences.
The prototypical use case for an Activity containing these properties is the publication and redistribution of Activities through an intermediary. That is, an event source generates the activity and publishes it to the intermediary which determines a subset of events 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 activity.
When the event source generates the activity and specifies values for
cc fields, the
intermediary SHOULD redistribute that event
with the values of those fields intact, allowing any processor to see
who the activity has been targeted to. This is precisely the same
model used by the
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 event source generating an activity MAY use the
bcc properties to list
entities to whom the activity should be privately targeted. When an
intermediary receives an activity containing these properties, it
MUST remove those values prior to redistributing the activity. The
intent is that systems MUST consider entities listed within the
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 Activity only
describes the intent of the activity creator. With clear exception
given to the appropriate handling of
bcc, this specification leaves it up to implementations
to determine how the audience targeting information is used.
Collection objects are a specialization of the base Object that contain a listing of other Objects. The Collection object is used primarily as the root of an Activity Streams Document, but can also be used as the value of object properties.
Collections have both a logical model and a physical serialization. While the logical view of a collection might contain a large number of objects, any single serialized representation might include only a subset of those objects, with specific "paging" Links used to reference additional serialized representations that include additional subsets. Such representations are known as "multi-page collections", with each serialized subset representing a single "page".
All Collection objects have an
property whose value is a JSON array of Objects of any type. The
property MUST be supported by all implementations.
In addition to the common properties shared by all Object instances,
Collection objects set of properties defined by the
Vocabulary. These include:
Verb is a subclass of Object used to
specifically describe metadata associated with an Activity
ObjectType is a subclass of Object used
to describe metadata associated with an Object
Ed.Note: This section is currently provisional and may be moved to a separate document.
Object instances can have an
used to describe the kinds of potential activities that can be taken with
regards to the object. The value is expressed as a JSON object conforming
class defined by the Actions Vocabulary.
Please refer to the Actions Vocabulary for more detail on the Potential Actions model.
An Activity Streams Document
is a JSON-LD document whose root value is a Collection and
whose MIME media type is "
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 SHOULD consider it to be deprecated. This means that while implementations MAY 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.
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.
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.
objectTypeproperties defined by Activity Streams 1.0 as aliases for the JSON-LD keywords
summaryproperties as Natural Language Values, which means their values can be expressed as either a String or a JSON-LD Language Map. 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.
downstreamDuplicatesproperties 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
downstreamDuplicatesproperties MAY continue to be used, implementations SHOULD avoid them.
By following these requirements, all JSON Activity Streams 1.0 serializations can be processed successfully by 2.0 implementations.
Processors that encounter unfamiliar property names or values MUST NOT stop processing or signal an error and MUST continue processing the items as if those properties were not present.
In JSON-LD, a "Compact IRI" is a type of shorthand notation that allows absolute IRI values to be split into an absolute base IRI and a relative token. For instance, in the following example:
The property name
foaf:givenName is a Compact IRI that expands to
http://xmlns.com/foaf/0.1/givenName" when processed by a JSON-LD
While there are differences of opinion on how extensively Compact IRIs ought to be used within JSON-LD document instances, JSON-LD implementations are required to support them.
In order to simplify implementation and encourage interoperable reuse, the following predefined prefixes are defined for Activity Streams 2.0 as an "Initial Context":
For instance, the property name
foaf:givenName would expand to
http://xmlns.com/foaf/0.1/givenName", while the property
prov:actingOnBehalfOf would expand to
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].
This specification registers the
application/activity+json MIME Media
Resources that use the "
|Security considerations:||As defined in this specification.|
|Contact:||James M Snell <firstname.lastname@example.org>|
The author wishes to thank the Activity Streams community and implementers for their support, encouragement, and enthusiasm 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.
relproperties are defined on Link and not Object.
@typeJSON-LD keywords to express the global identifier and object type:
languageproperty has the same effect as using the
@languageinside the JSON-LD
languageproperty and injects it as an appropriate JSON-LD
@languagekeyword into specific properties that are defined as Natural Language Values to ensure that such properties are properly handled by the standardized JSON-LD algorithms:
urn:example:verbs:upload" verb identifier:
urn:example:types:note" object type:
urn:example:types:note" as the objectType, and potential actions "
urn:example:actions:ShareAction" and "