Activity Streams (http://activitystrea.ms) J. Snell, Ed.
Internet-Draft IBM
Intended status: Standards Track July 12, 2013
Expires: January 13, 2014
JSON Activity Streams 2.0
draft-snell-activitystreams-01
Abstract
This specification details a model for representing potential and
completed activities using the JSON format.
Author's Note
This draft is heavily influenced by the original JSON Activity
Streams 1.0 specification that was 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.
The Activity Streams 1.0 and 2.0 specifications are works produced by
the Activity Streams Working Group (http://activitystrea.ms/)
operating independently of the IETF. Discussion and feedback about
this specification is invited and should be directed to the Activity
Streams Mailing List (see https://groups.google.com/forum/#!forum/
activity-streams).
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 13, 2014.
Snell Expires January 13, 2014 [Page 1]
Internet-Draft ActivityStreams July 2013
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Relationship to JSON Activity Streams 1.0 . . . . . . . . 3
1.2. Relationship to JSON-LD 1.0 . . . . . . . . . . . . . . . 3
1.3. Syntax Conventions . . . . . . . . . . . . . . . . . . . 4
2. Example Activities . . . . . . . . . . . . . . . . . . . . . 4
3. Object Model . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Object . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Natural Language Values . . . . . . . . . . . . . . . . . 7
3.3. Link Values . . . . . . . . . . . . . . . . . . . . . . . 8
3.4. Activity . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4.1. Considerations on the use of "priority" . . . . . . . 11
3.4.2. Audience Targeting Properties . . . . . . . . . . . . 12
3.5. Additional Object Properties . . . . . . . . . . . . . . 14
3.6. Collection . . . . . . . . . . . . . . . . . . . . . . . 17
3.6.1. Using Collections as Summary Values . . . . . . . . . 19
4. The Activity Stream JSON Document . . . . . . . . . . . . . . 20
5. Deprecated Activity Streams 1.0 Syntax . . . . . . . . . . . 20
6. Comparison of Identifier Values . . . . . . . . . . . . . . . 21
7. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 22
8. Security Considerations . . . . . . . . . . . . . . . . . . . 22
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
9.1. application/activity+xml Media Type . . . . . . . . . . . 23
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
10.1. Normative References . . . . . . . . . . . . . . . . . . 24
10.2. Informational References . . . . . . . . . . . . . . . . 24
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 24
Appendix B. Processing as JSON-LD . . . . . . . . . . . . . . . 25
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction
Snell Expires January 13, 2014 [Page 2]
Internet-Draft ActivityStreams July 2013
In the most basic sense, an "activity" is a semantic description of
either a potential or completed action. In the former case,
activities express what can be done with any particular object, while
in the latter case, they express 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].
1.1. Relationship to JSON Activity Streams 1.0
The JSON Activity Streams 1.0 [activitystreams-1.0] 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 work
being performed in other standards development 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.
1.2. Relationship to JSON-LD 1.0
The JSON-based Serialization for Linked Data (JSON-LD)
[W3C.WD-json-ld-20130411] describes a rich syntax for the
serialization of semantically-rich metadata using the JSON format.
While the updated Activity Streams representation provided by this
document is not defined as a "JSON-LD Vocabulary", the syntax is
designed to be closely compatible with JSON-LD.
There are a few differences between JSON-LD and the serialization
syntax described here, specifically:
o JSON-LD uses field names with a leading "@" character, such as
"@id", "@type" and "@language". In this specification, the
leading "@" is omitted.
Snell Expires January 13, 2014 [Page 3]
Internet-Draft ActivityStreams July 2013
o While JSON-LD allows using relative IRI references in the values
of ID properties, this specification limits identifiers to
absolute IRIs.
o While it is possible to derive a JSON-LD "context" description for
the Activity Streams 2.0 JSON syntax one is not normatively
provided by this specification.
1.3. Syntax Conventions
This specification defines a JSON-based [RFC4627] serialization
syntax.
When serialized, absent properties are represented either by setting
the property value to null or 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.
This specification uses IRIs [RFC3987]. Every URI [RFC3986] is also
an IRI, so a URI may be used wherever below 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).
2. Example Activities
Following is a simple example of an activity:
{
"verb": "post",
"published": "2011-02-10T15:04:55Z",
"actor": {
"type": "person",
"id": "urn:example:person:martin",
"displayName": "Martin Smith",
"url": "http://example.org/martin",
"image": {
"id": "http://example.org/martin/image",
Snell Expires January 13, 2014 [Page 4]
Internet-Draft ActivityStreams July 2013
"width": 250,
"height": 250
}
},
"object" : {
"type": "article",
"id": "urn:example:blog:abc123/xyz"
"url": "http://example.org/blog/2011/02/entry"
},
"target" : {
"type": "blog",
"id": "urn:example:blog:abc123",
"displayName": "Martin's Blog",
"url": "http://example.org/blog/"
}
}
A more extensive, single-entry "Activity Stream" follows. In
addition to containing a number of required and optional core
properties, the example contains the additional, undefined extension
properties "foo" and "foo2" for illustrative purposes only.
{
"items" : [
{
"verb": "post",
"language": "en",
"published": "2011-02-10T15:04:55Z",
"foo": "some extension property",
"generator": "http://example.org/activities-app",
"provider": "http://example.org/activity-stream",
"title": {
"en": "Martin posted a new video to his album.",
"ga": "Martin phost le fisean nua a albam."
},
"actor": {
"type": "person",
"id": "urn:example:person:martin",
"displayName": "Martin Smith",
"url": "http://example.org/martin",
"foo2": "some other extension property",
"image": {
"id": "http://example.org/martin/image",
"width": 250,
"height": 250
}
},
Snell Expires January 13, 2014 [Page 5]
Internet-Draft ActivityStreams July 2013
"object" : {
"type": "photo",
"id": "urn:example:album:abc123/my_fluffy_cat",
"url": "http://example.org/album/my_fluffy_cat.jpg",
"image": {
"id": "http://example.org/album/my_fluffy_cat_thumb.jpg",
"width": 250,
"height": 250
}
},
"target": {
"url": "http://example.org/album/",
"type": "photo-album",
"id": "urn:example.org:album:abc123",
"title": {
"en": "Martin's Photo Album",
"ga": "Grianghraif Mairtin"
},
"image": {
"id": "http://example.org/album/thumbnail.jpg",
"width": 250,
"height": 250
}
}
}
]
}
3. Object Model
3.1. Object
The following "core properties" apply to all JSON objects serialized
within an Activity Stream document.
+--------------+-------------+--------------------------------------+
| Property | Value | Description |
+--------------+-------------+--------------------------------------+
| id | IRI | Provides a permanent, universally |
| | | unique identifier for the object in |
| | | the form of an absolute IRI |
| | | [RFC3987]. Objects SHOULD contain a |
| | | single "id" property. If an object |
| | | does not contain an "id" property, |
| | | consumers MAY use the value of the |
| | | "url" property as a less-reliable, |
| | | non-unique identifier. |
Snell Expires January 13, 2014 [Page 6]
Internet-Draft ActivityStreams July 2013
| type | IRI | Identifies the type of object. An |
| | | object MAY contain a "type" property |
| | | whose value matches either the |
| | | "isegment-nz-nc" or the "IRI" |
| | | production in [RFC3987]. The use of |
| | | a relative reference other than a |
| | | simple name is not allowed. If no |
| | | "type" property is specified, the |
| | | object has no specific type. |
| language | [RFC5646] | Establishes the default language |
| | Language | assumed for human-readable, natural- |
| | Tag | language metadata values included in |
| | | the object. An object MAY contain a |
| | | "language" property whose value MUST |
| | | be a [RFC5646] Language-Tag. |
| displayName | String | A simple human-readable, plain-text |
| | | name for the object. HTML markup |
| | | MUST NOT be included. An object MAY |
| | | contain a "displayName" property. If |
| | | the object does not specify a "type" |
| | | property, the object SHOULD specify |
| | | a "displayName". |
| url | Link | A Link (Section 3.3) value |
| | | describing a resource that provides |
| | | a visual representation of the |
| | | object. An object MAY contain a |
| | | "url" property. |
+--------------+-------------+--------------------------------------+
3.2. Natural Language Values
Natural Language values represent human-readable character sequences
in one or more languages. They are expressed as either: (1) a single
JSON string or (2) a JSON dictionary mapping [RFC5646] Language-Tags
to localized, equivalent translations of the same string value.
For instance, the "title" property in all objects is a Natural
Language value.
A single String value using the default language:
{
"language": "en",
"title": "This is the title"
}
Snell Expires January 13, 2014 [Page 7]
Internet-Draft ActivityStreams July 2013
Multiple, language-specific values:
{
"title": {
"en": "This is the name",
"fr": "C'est le titre",
"sp": "Este es el titulo"
}
}
Each key in the JSON dictionary MUST be an [RFC5646] Language Tag.
The associated values MUST be Strings.
3.3. Link Values
Link values represent references to other objects and resources.
They are expressed as either: (1) a String containing an absolute or
relative IRI, (2) an Object (Section 3.1), or (3) a JSON Array
containing a mixture of IRIs or Objects (Section 3.1). Link values
are closely related to the conceptual model of Links as established
in [RFC5988], but have a serialization that is compatible with the
JSON-serialization for Linked Data.
For instance, as defined in previously, all objects (Section 3.1) 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 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. Based on
the JSON-LD approach, there are essentially three ways of describing
these references.
To reference a single image without any additional metadata, the link
value can be expressed as a simple JSON string containing an absolute
or relative IRI:
{
"type": "application",
"id": "http://example.org/application/123",
"displayName": "My Application",
"image": "http://example.org/application/123.png"
}
Alternatively, if additional metadata is required, the link can be
expressed as an object that uses the id or url property:
Snell Expires January 13, 2014 [Page 8]
Internet-Draft ActivityStreams July 2013
{
"type": "application",
"id": "http://example.org/application/123",
"displayName": "My Application",
"image": {
"id": "http://example.org/application/123.png",
"mediaType": "image/png",
"height": 320,
"width": 320
}
}
If more than one link value is to be expressed, A JSON Array with a
mix of string and object elements can be used:
{
"type": "application",
"id": "http://example.org/application/123",
"displayName": "My Application",
"image": [
"http://example.org/application/abc.gif",
{
"id": "http://example.org/application/123.png",
"mediaType": "image/png",
"height": 320,
"width": 320
}
]
}
Individual items contained in such an array value are independent of
the others and no significance is given to the order of items in the
array.
RFC 5988 defines that all Links have a "link relation" that describes
the contextual purpose of the link. Within an Activity Streams
document, in the absence of a specific "rel" property within the link
itself, the name of the property whose value is a link serves as the
"link relation". Any legal link relation value, as defined by RFC
5988, can be used as a property with a link value in any Activity
Streams object, except where the link relation might conflict with
any other property defined by this specification.
When an object (Section 3.1) is used to represent a Link value, the
following additional properties MAY be used:
Snell Expires January 13, 2014 [Page 9]
Internet-Draft ActivityStreams July 2013
+-------------+--------------+--------------------------------------+
| Property | Value | Description |
+-------------+--------------+--------------------------------------+
| rel | RFC 5988 | The RFC 5988 Link Relation |
| | Link | associated with this link value. If |
| | Relation | absent, the name of the property is |
| | | assumed to specify the link |
| | | relation. |
| mediaType | MIME Media | The MIME media type of the resource |
| | Type | being referenced. |
+-------------+--------------+--------------------------------------+
3.4. Activity
Activity objects are specializations of the base Object (Section 3.1)
type that provide metadata about potential or completed actions.
Within an Activity object, the "verb" property is used to identify
the type of activity. All existing verb definitions used in JSON
Activity Streams 1.0 implementations can continue to be used and
retain their existing semantics. If the "verb" is not specified, the
"type" property MAY be used as an alternative means of determining
the activity type.
Activity objects extend the core object (Section 3.1) definition with
the following additional, optional properties:
+-----------+------------+------------------------------------------+
| Property | Value | Description |
+-----------+------------+------------------------------------------+
| verb | IRI | Identifies the type of activity. An |
| | | activity SHOULD contain a "verb" |
| | | property whose value matches either the |
| | | "isegment-nz-nc" or the "IRI" production |
| | | in [RFC3987]. The use of a relative |
| | | reference other than a simple name is |
| | | not allowed. If the "verb" property is |
| | | not specified, the activity MUST contain |
| | | a "type" property. |
| actor | Link | Describes one or more entities that |
| | (Section | either peformed or are expected to |
| | 3.3) value | perform the activity. |
| with | Link | Describes one or more entities involved |
| | (Section | with the performance of the activity who |
| | 3.3) value | are not the primary performer as |
| | | specified by "actor". |
| object | Link | Describes the primary object of the |
Snell Expires January 13, 2014 [Page 10]
Internet-Draft ActivityStreams July 2013
| | (Section | activity. For instance, in the activity, |
| | 3.3) value | "John saved a movie to his wishlist", |
| | | the object of the activity is "movie". |
| | | An activity SHOULD contain an "object" |
| | | property. If the "object" property is |
| | | not contained, the primary object of the |
| | | activity MAY be implied by context. |
| target | Link | Describes the target of the activity. |
| | (Section | The precise meaning of the activity's |
| | 3.3) value | target is dependent on the activities |
| | | "verb", but will often be the object the |
| | | English preposition "to". For instance, |
| | | in the activity, "John saved a movie to |
| | | his wishlist", the target of the |
| | | activity is "wishlist". The activity |
| | | target MUST NOT be used to identity an |
| | | indirect object that is not a target of |
| | | the activity. |
| result | Link | Describes the result of the activity. |
| | (Section | For instance, if a particular action |
| | 3.3) value | results in the creation of a new |
| | | resource, the "result" property can be |
| | | used to describe that new resource. |
| context | Link | The "context" property allows the |
| | (Section | Activity to further include information |
| | 3.3) value | about why a particular action occurred |
| | | by providing details about the context |
| | | within which a particular action was |
| | | performed. The value of the context |
| | | property is Link (Section 3.3) value. |
| priority | Decimal | An indicator of the relative priority or |
| | Number | importance that the creator of an |
| | between | Activity object considers the object to |
| | 0.00 and | have. Represented as a numeric decimal |
| | 1.00 | between 0.00 and 1.00, with two decimal |
| | | places of precision. If the property is |
| | | omitted, or expicitly set to null, the |
| | | assumption is that no explicit priority |
| | | or importance can be assumed. All other |
| | | values falling between 0.00 and 1.00 |
| | | indicate increasing priority. |
+-----------+------------+------------------------------------------+
3.4.1. Considerations on the use of "priority"
Snell Expires January 13, 2014 [Page 11]
Internet-Draft ActivityStreams July 2013
The presence of the "priority" property does not impose any specific
processing or display requirements on the part of any entity
consuming the activity.
Expressing the value as a range of numeric decimal values is intended
to provide the greatest level of flexibility in the expression and
consumption of prioritization detail. It is expected that
implementors consuming activity objects containing "priority" will
utilize and expose the additional information in a number of
different ways depending on the unique requirements of each
application use case.
Many existing systems do not represent priority values as numeric
ranges. Such systems might use fixed, labeled brackets such as
"low", "normal" and "high" or "urgent". Similar mechanisms can be
established, by convention, when using the "priority" property. In
typical use, it is RECOMMENDED that implementations wishing to work
with such defined categories treat "priority" property values in the
range 0.00 to 0.25 as "low" priority; values greater than 0.25 to
0.75 as "normal" priority; and values greater than 0.75 to 1.00 as
"high" priority. Specific implementations are free to establish
alternative conventions for the grouping of priority values with the
caveat that such conventions likely will not be understood by all
implementations.
3.4.2. Audience Targeting Properties
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
Snell Expires January 13, 2014 [Page 12]
Internet-Draft ActivityStreams July 2013
means of identifying the secondary audience. The "to", "cc", "bto"
and "bcc" properties MAY be used within an Activity to explicitly
identify the Primary and Secondary audiences.
+--------------+--------------------+-------------------------------+
| Property | Value | Description |
+--------------+--------------------+-------------------------------+
| to | Link (Section 3.3) | Specifies the public primary |
| | value | audience. |
| cc | Link (Section 3.3) | Specifies the public |
| | value | secondary audience. |
| bto | Link (Section 3.3) | Specifies the private primary |
| | value | audience. |
| bcc | Link (Section 3.3) | Specifies the private |
| | value | secondary audience. |
+--------------+--------------------+-------------------------------+
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
the to and 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 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 event source generating an activity MAY use the "bto" and
"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 "bto" and "bcc" properties as
part of the Primary and Second 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 "bto" and "bcc", this
Snell Expires January 13, 2014 [Page 13]
Internet-Draft ActivityStreams July 2013
specification leaves it up to implementations to determine how the
audience targeting information is used.
3.5. Additional Object Properties
The following "additional properties" MAY be used with any JSON
Object serialized within an Activity Stream document.
+--------------+-------------+--------------------------------------+
| Property | Value | Description |
+--------------+-------------+--------------------------------------+
| alias | IRI | Provides a contextually meaningful |
| | | alternative label for the object in |
| | | addition to the "id". For instance, |
| | | within some systems, groups can be |
| | | identified both by a unique global |
| | | ID and a more "human-friendly" label |
| | | such as "@friends" or "@network". |
| | | The value of the "alias" property |
| | | MUST match either the "isegment-nz- |
| | | nc" or the "IRI" production in |
| | | [RFC3987]. The use of a relative |
| | | reference other than a simple name |
| | | is not allowed. |
| attachments | Link | A Link (Section 3.3) value |
| | (Section | referencing one or more objects |
| | 3.3) value | associated with the containing |
| | | object. These are similiar in |
| | | concept to files attached to an |
| | | email message. |
| author | Link | A Link (Section 3.3) value |
| | (Section | referencing one or more entity that |
| | 3.3) value | created or authored the object. |
| content | Natural | A Natural-language description of |
| | Language | the object encoded as a single JSON |
| | value | String containing HTML markup. |
| | (Section | Visual elements such as thumbnail |
| | 3.2) | images MAY be included. |
| duplicates | Link | A Link (Section 3.3)value |
| | (Section | referencing one or more objects that |
| | 3.3) value | are semantically equivalent to this |
| | | object or duplicate this objects |
| | | content. An object SHOULD contain a |
| | | "duplicates" property when there are |
| | | known objects, possibly in a |
| | | different system, that are |
| | | semantically equivalent or duplicate |
| | | the content. |
Snell Expires January 13, 2014 [Page 14]
Internet-Draft ActivityStreams July 2013
| icon | Link | A Link (Section 3.3) value |
| | (Section | referencing one or more visual, |
| | 3.3) value | graphic representations of the |
| | | object, intended for human |
| | | consumption. The visual element |
| | | SHOULD have an aspect ratio of one |
| | | (horizontal) to one (vertical) and |
| | | SHOULD be suitable for presentation |
| | | at a small size. |
| image | Link | A Link (Section 3.3) value |
| | (Section | referencing one or more visual, |
| | 3.3) value | graphic represenations of the |
| | | object. Unlike the "icon" property, |
| | | there are no aspect ratio or display |
| | | restrictions. |
| location | Link | A Link (Section 3.3) value |
| | (Section | describing one or more physical or |
| | 3.3) value | virtual locations associated with |
| | | which the object. |
| published | [RFC3339] | The date and time at which the |
| | date-time | object was published. |
| generator | Link | A Link (Section 3.3) value |
| | (Section | referencing the application that |
| | 3.3) value | generated the object. |
| provider | Link | A Link (Section 3.3) value |
| | (Section | referencing the application that |
| | 3.3) value | published the object. Note that this |
| | | is not necessarily the same entity |
| | | that generated the object. |
| source | Link | A Link (Section 3.3) value |
| | (Section | referencing the original source of |
| | 3.3) value | this object. The source property is |
| | | closely related to the generator and |
| | | provider properties but serves the |
| | | distinct purpose of identifying |
| | | where the object was originally |
| | | published as opposed to identifying |
| | | the applications that generated or |
| | | published it. |
| summary | Natural | A Natural-language summarization of |
| | Language | the object encoded as a single JSON |
| | value | String containing HTML markup. |
| | (Section | Visual elements such as thumbnail |
| | 3.2) | images can be included. |
| updated | [RFC3339] | The date and time at which a |
| | date-time | previously published object has been |
| | | modified. |
| startTime | [RFC3339] | A date-time describing the actual or |
Snell Expires January 13, 2014 [Page 15]
Internet-Draft ActivityStreams July 2013
| | date-time | expected starting time of the |
| | | object. When used within an Activity |
| | | object, for instance, the |
| | | "startTime" specifies the moment the |
| | | activity began or is scheduled to |
| | | begin. |
| endTime | [RFC3339] | A date-time describing the actual or |
| | date-time | expected ending time of the object. |
| | | When used within an Activity object, |
| | | for instance, the "endTime" |
| | | specifies the moment the activity |
| | | concluded or is scheduled to |
| | | conclude. |
| rating | Decimal | A quality rating expressed as a |
| | Number | number between 1.0 and 5.0 |
| | between 1.0 | (inclusive) with one decimal place |
| | and 5.0 | of precision. |
| tags | Link | A Link (Section 3.3) value |
| | (Section | referencing one or more resources |
| | 3.3) value | that are loosely associated with the |
| | | containing object. The "tags" and |
| | | "attachments" properties differ from |
| | | one another in that the "tags" |
| | | property asserts "association by |
| | | reference" while "attachments" |
| | | asserts "association by enclosure". |
| title | Natural | A Natural-language title of the |
| | Language | object encoded as a single JSON |
| | (Section | String containing HTML markup. |
| | 3.2) value | |
| duration | Integer or | When the object describes a time- |
| | [RFC3339] | based resource, such as audio or |
| | duration | video, the "duration" property |
| | | indicates the approximate duration |
| | | of time expressed as an either an |
| | | RFC 3339 "duration" (e.g. a |
| | | duration of 5 seconds is represented |
| | | as "PT5S") or as a non-negative |
| | | integer specifying the duration in |
| | | seconds. |
| height | Integer | When the object describes a visual |
| | | resource, such as an image, video or |
| | | embeddable HTML page, the "height" |
| | | property indicates the recommended |
| | | display height in pixels. |
| width | Integer | When the object describes a visual |
| | | resource, such as an image, video or |
| | | embeddable HTML page, the "width" |
Snell Expires January 13, 2014 [Page 16]
Internet-Draft ActivityStreams July 2013
| | | property indicates the recommended |
| | | display width in pixels. |
| inReplyTo | Link | A Link (Section 3.3) value |
| | (Section | identifying one or more other |
| | 3.3) value | objects to which the containing |
| | | object can be considered a response. |
+--------------+-------------+--------------------------------------+
3.6. Collection
Collection objects are a specialization of the base Object
(Section 3.1) that contain a listing of other objects (Section 3.1)
The Collection object is used primarily as the root of an Activity
Streams document as described in Section 4, but can 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 Link (Section 3.3) values 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".
The value of the Collection object's "type" property MUST be
"collection" unless the fact that the object is a collection can be
determined by context.
Collection objects extend the core object (Section 3.1) definition
with the following additional properties:
+--------------+--------------+-------------------------------------+
| Property | Value | Description |
+--------------+--------------+-------------------------------------+
| totalItems | Integer | 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. |
| items | Array of | An array containing a listing of |
| | Objects | Objects (Section 3.1) of any type. |
| | (Section | |
| | 3.1) | |
| itemsAfter | [RFC3339] | A RFC 3339 date-time that indicates |
Snell Expires January 13, 2014 [Page 17]
Internet-Draft ActivityStreams July 2013
| | date-time | that the collection contains only |
| | | items published or updated strictly |
| | | after the date and time specified. |
| itemsBefore | [RFC3339] | A RFC 3339 date-time that indicates |
| | date-time | that the collection contains only |
| | | items published or updated strictly |
| | | before the date and time specified. |
| itemsPerPage | Integer | A non-negative integer specifying |
| | | the maximum number of items that |
| | | will be included in the value of |
| | | the items array. |
| startIndex | Integer | A non-negative integer value |
| | | identifying the relative position |
| | | within the logical view of |
| | | collection of the first object |
| | | contained in the items property. |
| | | For instance, if there are 20 items |
| | | that are considered to be members |
| | | of a collection, but only the last |
| | | 10 of those items are included in |
| | | the items property, the value of |
| | | startIndex would be 10. |
| first | Link | A Link (Section 3.3) value |
| | (Section | referencing the furthest preceeding |
| | 3.3) value | page of a multi-page collection. |
| last | Link | A Link (Section 3.3) value |
| | (Section | referencing the furthest following |
| | 3.3) value | page of a multi-page collection. |
| prev | Link | A Link (Section 3.3) value |
| | (Section | referencing the immediately |
| | 3.3) value | preceding page of the multi-page |
| | | collection. Note that the property |
| | | name previous can be used as an |
| | | equivalent alternative; however |
| | | implementations SHOULD use prev and |
| | | MUST NOT use both prev AND previous |
| | | within the same collection. |
| next | Link | A Link (Section 3.3) value |
| | (Section | referencing the immediately |
| | 3.3) value | following page of the multi-page |
| | | collection. |
| current | Link | A Link (Section 3.3) value |
| | (Section | referencing the page containing the |
| | 3.3) value | items that have been updated or |
| | | published most recently. |
| self | Link | A Link (Section 3.3) value |
| | (Section | referencing this page. |
| | 3.3) value | |
Snell Expires January 13, 2014 [Page 18]
Internet-Draft ActivityStreams July 2013
+--------------+--------------+-------------------------------------+
3.6.1. Using Collections as Summary Values
It is a common practice to use Collection objects to provide summary
information on the number of specific types of events that have
occurred with respect to any given object. For instance, a "note"
object may have been "shared" or "liked" a number of times by
different individuals. In such cases, the Collection object is used
as a property value with the "totalItems" field used to indicate the
total number of occurrences, the "items" property used to provide
details for a subset of the most recent occurrences, and the "id"
property used to reference a separate Activity Streams document
providing additional information.
This specification defines the following properties that MAY be used
within any object (Section 3.1) as "summary values":
+------------+-----------------+------------------------------------+
| Property | Value | Description |
+------------+-----------------+------------------------------------+
| replies | Collection | Provides information about the set |
| | (Section 3.6) | of objects that can be considered |
| | | to be replies to the containing |
| | | object. |
+------------+-----------------+------------------------------------+
In the following example, the "replies" property is used to indicate
that a note has 10 responses, and provides information on the most
recently received response:
Snell Expires January 13, 2014 [Page 19]
Internet-Draft ActivityStreams July 2013
{
"type": "note",
"id": "urn:example:note:1",
"displayName": "Note",
"title": "A Note about things",
"content": "blah blah blah",
"replies": {
"url": "http://example.org/note/1/comments.json",
"mediaType": "application/activity+json",
"totalItems": 10,
"items": [
{
"type": "note",
"id": "urn:example:note:1:A",
"content": "That's profound, man."
}
]
}
}
4. The Activity Stream JSON Document
The above defined JSON serialization can be used to represent
activities, objects and media links in any context. This section
defines one particular use of the above formats to publish a JSON
document representing a stream of activities.
Publishers using this format MUST produce a valid JSON document whose
root value is a Collection (Section 3.6).
The MIME media type of this document MUST be "application/
activity+json".
5. Deprecated Activity Streams 1.0 Syntax
The JSON syntax defined by this specification differs somewhat from
that defined in the original JSON Activity Streams 1.0
[activitystreams-1.0] 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.
Specifically:
Snell Expires January 13, 2014 [Page 20]
Internet-Draft ActivityStreams July 2013
1. Implementations MUST use the "application/stream+json" MIME media
type when producing a JSON serialization of an Activity Object
conforming to the 1.0 syntax, and "application/activity+json"
when producing a serialization conforming to the 2.0 syntax.
2. Implementations that process serializations of an Activity Object
identified using either the "application/stream+json" or more
generic "application/json" MIME media type MUST follow the syntax
and processing rules set by [activitystreams-1.0]. The 2.0
syntax and processing rules apply only when handling
serializations using the "application/activity+json" media type.
3. This document renames the 1.0 "objectType" property to "type" to
better align syntactically with JSON-LD. For backwards
compatibility, implementations MUST treat "objectType" as an
alias of "type".
4. This document redefines the "title", "content" and "summary"
properties as Natural Language Values (Section 3.2), 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.
5. This document redefines a large number of common properties
defined originally as Objects in 1.0 as Link values
(Section 3.3). This means the property values can be expressed
as either an IRI String, an Object, or an Array of IRI Strings
and Objects. 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.
6. This specification replaces the "upstreamDuplicates" and
"downstreamDuplicates" properties defined in the 1.0 syntax with
a singular "duplicates" property with a Link value (Section 3.3).
The "upstreamDuplicates" and "downstreamDuplicates" property
values in 1.0 are defined as Arrays of strings. Implementations
MUST consider the union of these two values as an alias for the
"duplicates" property.
By following these requirements, all JSON Activity Streams 1.0
serializations can be processed successfully by 2.0 implementations.
6. Comparison of Identifier Values
The values of multiple Object (Section 3.1) and Link (Section 3.3)
value's "id" properties can be compared to determine if the objects
Snell Expires January 13, 2014 [Page 21]
Internet-Draft ActivityStreams July 2013
represent duplicate content. Processors MUST compare these values on
a character-by-character, case-sensitive basis. Comparison
operations MUST be based solely on the IRI character strings and MUST
NOT rely on dereferencing the IRIs or URIs mapped from them.
As a consequence, two IRIs that resolve to the same resource but are
not character-for-character identical will be considered different
for the purposes of identifier comparison. In such cases, the
"duplicates" property can be used to expressly relate such objects to
one another.
7. Extensibility
Processors that encounter unfamiliar properties within any Activity
Streams object MUST NOT stop processing or signal an error and MUST
continue processing the items as if those properties were not
present.
8. 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 un-trusted 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 [RFC4627].
Snell Expires January 13, 2014 [Page 22]
Internet-Draft ActivityStreams July 2013
Activity Streams implementations handle URIs. See Section 7 of
[RFC3986].
Activity Streams implementations handle IRIs. See Section 8 of
[RFC3987].
9. IANA Considerations
9.1. application/activity+xml Media Type
This specification registers the application/activity+json MIME Media
Type:
Type name: application
Subtype name: activity+json
Required parameters: None
Optional parameters: "charset" : Specifies the character set
encoding. If not specified, a default of "UTF-8" is assumed.
Encoding considerations: Resources that use the "application/
activity+json" media type are required to conform to the
"application/json" Media Type and are therefore subject to the
same encoding considerations specified in Section 6 [RFC4627].
Security considerations: As defined in this specification
Published specification: This specification.
Applications that use this media type: JSON Activity Streams are
implemented by a wide range of existing applications.
Additional information:
Magic number(s): N/A
File extension(s): N/A
Macintosh file type code(s): TEXT
Person & email address to contact for further information: James M
Snell <jasnell@gmail.com>
Intended usage: COMMON
Restrictions on usage: None.
Snell Expires January 13, 2014 [Page 23]
Internet-Draft ActivityStreams July 2013
Author: James M Snell <jasnell@gmail.com>
Change controller: IESG
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[W3C.WD-json-ld-20130411]
Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0",
World Wide Web Consortium LastCall WD-json-ld-20130411,
April 2013,
<http://www.w3.org/TR/2013/WD-json-ld-20130411>.
[activitystreams-1.0]
Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson,
M., and R. Dolin, "JSON Activity Streams 1.0", May 2011.
10.2. Informational References
[RFC6963] Saint-Andre, P., "A Uniform Resource Name (URN) Namespace
for Examples", BCP 183, RFC 6963, May 2013.
Appendix A. Acknowledgements
The author wishes to thank the Activity Streams community and
implementers for their support, encouragement, and enthusiasm
Snell Expires January 13, 2014 [Page 24]
Internet-Draft ActivityStreams July 2013
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 G. Cappalaere, 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 Celik, Tatu Saloranta, Tim Moore, Timothy Young,
Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley,
and Zach Shepherd.
Appendix B. Processing as JSON-LD
While the Activity Streams 2.0 syntax is designed to be compatible
with JSON-LD, in order to successfully process an Activity Streams
document as JSON-LD, a "@context" description needs to be provided.
The following example illustrates an Activity Streams document that
can be processed as JSON-LD containing Schema.org defined metadata
elements.
Snell Expires January 13, 2014 [Page 25]
Internet-Draft ActivityStreams July 2013
{
"@context": {
"@vocab": "http://activitystrea.ms/spec/2.0/",
"verb": "http://schema.org/Action/@type",
"actor": "http://schema.org/Action/performedBy",
"object": "http://schema.org/BuyAction/bought",
"purchase": "http://schema.org/BuyAction",
"person": "http://schema.org/Person",
"book": "http://schema.org/Book"
},
"verb" : "purchase",
"id" : "urn:example:purchase:123/abc",
"title": "John purchased 'A Tale of Two Cities'",
"startTime" : "2013-04-02T12:31Z",
"endTime" : "2013-04-02T12:31Z",
"actor": {
"type": "person",
"displayName": "John Doe"
},
"object": {
"type": "book",
"title": "A Tale of Two Cities"
}
}
Author's Address
James M Snell (editor)
IBM
Email: jasnell@gmail.com
Snell Expires January 13, 2014 [Page 26]