Activity Streams (http://activitystrea.ms)                 J. Snell, Ed.
Internet-Draft                                                       IBM
Intended status: Standards Track                          April 19, 2014
Expires: October 20, 2014


                       JSON Activity Streams 2.0
                     draft-snell-activitystreams-06

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 September 19, 2014.





Snell                  Expires September 19, 2014               [Page 1]


Internet-Draft               ActivityStreams                  Aoril 2014


Copyright Notice

   Copyright (c) 2014 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  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Relationship to JSON Activity Streams 1.0 . . . . . . . .   3
     1.2.  Relationship to JSON-LD 1.0 . . . . . . . . . . . . . . .   4
     1.3.  Syntax Conventions  . . . . . . . . . . . . . . . . . . .   5
   2.  Example Activities  . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Example 1: Minimal Activity . . . . . . . . . . . . . . .   6
     2.2.  Example 2: Basic activity with some additional detail . .   6
     2.3.  Example 3: An extended activity . . . . . . . . . . . . .   7
   3.  Object Model  . . . . . . . . . . . . . . . . . . . . . . . .   8
     3.1.  Object  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     3.2.  Natural Language Values . . . . . . . . . . . . . . . . .   9
     3.3.  Type Values . . . . . . . . . . . . . . . . . . . . . . .  10
     3.4.  Link Values . . . . . . . . . . . . . . . . . . . . . . .  12
     3.5.  Activity  . . . . . . . . . . . . . . . . . . . . . . . .  14
       3.5.1.  Considerations on the use of "priority" . . . . . . .  16
       3.5.2.  Audience Targeting Properties . . . . . . . . . . . .  17
     3.6.  Additional Object Properties  . . . . . . . . . . . . . .  18
       3.6.1.  Action Values . . . . . . . . . . . . . . . . . . . .  21
     3.7.  Collection  . . . . . . . . . . . . . . . . . . . . . . .  22
       3.7.1.  Using Collections as Summary Values . . . . . . . . .  24
   4.  The Activity Stream JSON Document . . . . . . . . . . . . . .  25
   5.  Reserved Object Types and Verbs . . . . . . . . . . . . . . .  26
     5.1.  Object Types  . . . . . . . . . . . . . . . . . . . . . .  26
     5.2.  Verbs . . . . . . . . . . . . . . . . . . . . . . . . . .  26
   6.  Deprecated Activity Streams 1.0 Syntax  . . . . . . . . . . .  26
   7.  Comparison of Identifier Values . . . . . . . . . . . . . . .  27
   8.  Extensibility . . . . . . . . . . . . . . . . . . . . . . . .  28
     8.1.  Extension verbs and objectTypes . . . . . . . . . . . . .  28
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  29
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  30
     10.1.  application/activity+xml Media Type  . . . . . . . . . .  30



Snell                  Expires September 19, 2014               [Page 2]


Internet-Draft               ActivityStreams                  Aoril 2014


   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  31
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  31
     11.2.  Informational References . . . . . . . . . . . . . . . .  32
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  32
   Appendix B.  Processing as JSON-LD  . . . . . . . . . . . . . . .  33
   Appendix C.  Activity Statement Linguistic Forms  . . . . . . . .  34
     C.1.  Intransitive Activity . . . . . . . . . . . . . . . . . .  34
     C.2.  Transitive Activity . . . . . . . . . . . . . . . . . . .  35
     C.3.  Ditransitive Activity . . . . . . . . . . . . . . . . . .  35
     C.4.  Expressing tense and aspect . . . . . . . . . . . . . . .  36
     C.5.  Activity Duration . . . . . . . . . . . . . . . . . . . .  38
   Appendix D.  Motivational Use Cases . . . . . . . . . . . . . . .  39
     D.1.  Internationalization (i18n) . . . . . . . . . . . . . . .  39
     D.2.  Extensibility (e11y)  . . . . . . . . . . . . . . . . . .  40
       D.2.1.  Publishing Extension objectType and verb Libraries  .  42
     D.3.  First Class Links . . . . . . . . . . . . . . . . . . . .  42
     D.4.  Use of External Vocabularies  . . . . . . . . . . . . . .  44
     D.5.  Embedded Actions  . . . . . . . . . . . . . . . . . . . .  45
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  45

1.  Introduction

   In the most basic sense, an "activity" is a semantic description of
   potential or completed actions.  In the former case, the activity
   expresses what can 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].

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.



Snell                  Expires September 19, 2014               [Page 3]


Internet-Draft               ActivityStreams                  Aoril 2014


   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.

   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 [base-schema], Audience
   Targeting [audience], Responses [responses], and Priority [priority]
   extensions.

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 certain field names with a leading "@" character,
      such as "@id" and "@language".  In this specification, the leading
      "@" is omitted.

   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.

   When processing an Activity Streams document as JSON-LD, the
   following rules apply:

   o  The "objectType" property MUST be treated as an alias of JSON-LD
      "@type".

   o  The "id" property MUST be treated as an alias of JSON-LD "@id".





Snell                  Expires September 19, 2014               [Page 4]


Internet-Draft               ActivityStreams                  Aoril 2014


   o  The "language" property MUST be treated as an alias of JSON-LD
      "@language".

   o  A JSON array used to convey Link (Section 3.4) values MUST be
      treated as an unordered JSON-LD @set (@container = @set).

   o  The JSON array value for the "items" property defined in
      Section 3.7 MUST be treated as an ordered JSON-LD @list
      (@container = @list).

   o  The "displayName", "title", "content" and "summary" properties
      defined in Section 3.1 and Section 3.6 MUST be treated as JSON-LD
      Language Maps (@container = @language).

1.3.  Syntax Conventions

   This specification defines a JSON-based [RFC4627] serialization
   syntax.

   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.

   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).

2.  Example Activities

   Following are three examples of activities with varying degrees of
   detail.






Snell                  Expires September 19, 2014               [Page 5]


Internet-Draft               ActivityStreams                  Aoril 2014


2.1.  Example 1: Minimal Activity

   Expresses the statement "'urn:example:person:martin' posted 'http://
   example.org/foo.jpg'".  No additional detail is given.

     {
       "verb": "post",
       "actor": "urn:example:person:martin",
       "object": "http://example.org/foo.jpg"
     }

2.2.  Example 2: Basic activity with some additional detail

   Expresses the statement "Martin Smith posted an article to the blog
   'Martin's Blog' at 3:04 PM GMT on February 2, 2011."  Some additional
   details about the article, actor and target blog are given.

     {
       "verb": "post",
       "published": "2011-02-10T15:04:55Z",
       "language": "en",
       "actor": {
         "objectType": "person",
         "id": "urn:example:person:martin",
         "displayName": "Martin Smith",
         "url": "http://example.org/martin",
         "image": {
           "url": "http://example.org/martin/image.jpg",
           "mediaType": "image/jpeg",
           "width": 250,
           "height": 250
         }
       },
       "object" : {
         "objectType": "article",
         "id": "urn:example:blog:abc123/xyz"
         "url": "http://example.org/blog/2011/02/entry",
         "displayName": "Why I love Activity Streams"
       },
       "target" : {
         "objectType": "blog",
         "id": "urn:example:blog:abc123",
         "displayName": "Martin's Blog",
         "url": "http://example.org/blog/"
       }
     }





Snell                  Expires September 19, 2014               [Page 6]


Internet-Draft               ActivityStreams                  Aoril 2014


2.3.  Example 3: An extended activity

   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.

    {
      "totalItems": 1,
      "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",
          "displayName": {
            "en": "Martin posted a new video to his album.",
            "ga": "Martin phost le fisean nua a albam."
          },
          "actor": {
            "objectType": "person",
            "id": "urn:example:person:martin",
            "displayName": "Martin Smith",
            "url": "http://example.org/martin",
            "foo2": "some other extension property",
            "image": {
              "url": "http://example.org/martin/image",
              "mediaType": "image/jpeg",
              "width": 250,
              "height": 250
            }
          },
          "object" : {
            "objectType": {
              "id": "http://example.org/Photo",
              "displayName": "Photo"
            },
            "id": "urn:example:album:abc123/my_fluffy_cat",
            "url": "http://example.org/album/my_fluffy_cat.jpg",
            "image": {
              "url": "http://example.org/album/my_fluffy_cat_thumb.jpg",
              "mediaType": "image/jpeg",
              "width": 250,
              "height": 250
            }
          },



Snell                  Expires September 19, 2014               [Page 7]


Internet-Draft               ActivityStreams                  Aoril 2014


          "target": {
            "objectType": {
              "id": "http://example.org/PhotoAlbum",
              "displayName": "Photo-Album"
            },
            "id": "urn:example.org:album:abc123",
            "url": "http://example.org/album/",
            "displayName": {
              "en": "Martin's Photo Album",
              "ga": "Grianghraif Mairtin"
            },
            "image": {
              "url": "http://example.org/album/thumbnail.jpg",
              "mediaType": "image/jpeg",
              "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.























Snell                  Expires September 19, 2014               [Page 8]


Internet-Draft               ActivityStreams                  Aoril 2014


   +-------------+---------------+-------------------------------------+
   | 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.                         |
   | objectType  | Type value    | Identifies the type of object. An   |
   |             | (Section 3.3) | object MAY contain a "objectType"   |
   |             |               | property whose value is a Type      |
   |             |               | value (Section 3.3).  If no         |
   |             |               | "objectType" property is specified, |
   |             |               | the object has no specific type.    |
   | language    | [RFC5646]     | Establishes the default language    |
   |             | Language Tag  | assumed for human-readable,         |
   |             |               | natural-language metadata values    |
   |             |               | included in the object. An object   |
   |             |               | MAY contain a "language" property   |
   |             |               | whose value MUST be a [RFC5646]     |
   |             |               | Language-Tag.                       |
   | displayName | Natural       | A simple human-readable, plain-text |
   |             | Language      | name for the object. HTML markup    |
   |             | value         | MUST NOT be included. An object MAY |
   |             | (Section 3.2) | contain a "displayName" property.   |
   |             |               | If the object does not specify a    |
   |             |               | "objectType" property, the object   |
   |             |               | SHOULD specify a "displayName".     |
   | url         | Link (Section | A Link (Section 3.4) value          |
   |             | 3.4) value    | describing a resource that provides |
   |             |               | a 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.





Snell                  Expires September 19, 2014               [Page 9]


Internet-Draft               ActivityStreams                  Aoril 2014


   For instance, the "displayName" property in all objects is a Natural
   Language value.

   A single String value using the default language:

     {
       "language": "en",
       "displayName": "This is the title"
     }

   Multiple, language-specific values:

     {
       "displayName": {
         "en": "This is the title",
         "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.  Type Values

   Type values represent references to or descriptions of an abstract
   type.  They are expressed as either: (1) a String conforming to
   either the "isegment-nz-nc" or "IRI" productions in [RFC3987] or (2)
   an Object (Section 3.1).  When represented as a String, the use of
   relative references other than a simple name is not allowed.  When
   represented as an Object, the "id" property MUST be specified.

   Within the Activity Streams 2.0, Type values are used only by the
   "objectType" and "verb" properties.

   Object type as a simple name (isegment-nz-nc):

     {
       "objectType": "person",
       "displayName": "John"
     }

   Object type as an absolute IRI:

     {
       "objectType": "http://example.org/Person",
       "displayName": "John"
     }



Snell                  Expires September 19, 2014              [Page 10]


Internet-Draft               ActivityStreams                  Aoril 2014


   Object type as an object:

     {
       "objectType": {
         "id": "http://example.org/Person",
         "displayName": "Person"
       },
       "displayName": "John"
     }

   Because the second and third examples above each specify "http://
   example.org/Person", the two examples are considered to specify the
   same type.

   Verb as a simple name (isegment-nz-nc):

     {
       "verb": "post",
       "actor": "acct:john.doe@example.org",
       "object": "http://example.org/123"
     }

   Verb as an absolute IRI:

     {
       "verb": "http://example.com/Upload",
       "actor": "acct:john.doe@example.org",
       "object": "http://example.org/123"
     }

   Verb as an object:

     {
       "verb": {
         "id": "http://example.com/Upload",
         "displayName": "Upload"
       },
       "actor": "acct:john.doe@example.org",
       "object": "http://example.org/123"
     }

   Allowing verbs and object types to be represented as objects rather
   than simple names or IRIs is intended to simplify the use of
   extensions that an implementation might not have encountered
   previously.  The object properties provide additional information and
   metadata about the new verb or object type.





Snell                  Expires September 19, 2014              [Page 11]


Internet-Draft               ActivityStreams                  Aoril 2014


   It is important to note that because the "id" property is strictly
   limited to absolute IRI values, the object representation cannot be
   used to describe types with simple names.

3.4.  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].

   For example, as defined 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.  Using Link
   values, there are essentially three ways of describing such
   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:

     {
       "objectType": "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 containing the url property.

     {
       "objectType": "application",
       "id": "http://example.org/application/123",
       "displayName": "My Application",
       "image": {
         "url": "http://example.org/application/123.png",
         "mediaType": "image/png",
         "height": 320,
         "width": 320
       }
     }



Snell                  Expires September 19, 2014              [Page 12]


Internet-Draft               ActivityStreams                  Aoril 2014


   If more than one link value is to be expressed, A JSON Array with a
   mix of string and object elements can be used:

     {
       "objectType": "application",
       "id": "http://example.org/application/123",
       "displayName": "My Application",
       "image": [
         "http://example.org/application/abc.gif",
         {
           "url": "http://example.org/application/123.png",
           "mediaType": "image/png",
           "height": 320,
           "width": 320
         }
       ]
     }

   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 an object (Section 3.1),
   in the absence of a specific "rel" property within the link object
   itself, the name of the property whose value is a link serves as the
   "link relation".  Any valid 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.

   In the following example, two separate links are provided.  The link
   relation of the first is "image", while the link relation of the
   second is "preview".  Both links, however, can be used as alternative
   visual representations of the "application" object.

     {
       "objectType": "application",
       "image": [
         "http://example.org/foo.jpg",
         {
           "url": "http://example.org/screens/1.jpg",
           "rel": "preview",
           "mediaType": "image/jpeg"
         }
       ]
     }





Snell                  Expires September 19, 2014              [Page 13]


Internet-Draft               ActivityStreams                  Aoril 2014


   When an object (Section 3.1) is used to represent a Link value, the
   following additional properties MAY be used:

   +-----------+---------------+---------------------------------------+
   | Property  | Value         | Description                           |
   +-----------+---------------+---------------------------------------+
   | rel       | RFC 5988 Link | The RFC 5988 Link Relation associated |
   |           | Relation      | with this link value.  If 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.5.  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
   "objectType" 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        | Type value    | Identifies the type of activity. An |
   |             | (Section 3.3) | activity SHOULD contain a "verb"    |
   |             |               | property whose value is a Type      |
   |             |               | value (Section 3.3).  If the "verb" |
   |             |               | property is not specified, the      |
   |             |               | activity MUST contain a             |
   |             |               | "objectType" property.              |
   | actor       | Link (Section | Describes one or more entities that |
   |             | 3.4) value    | either peformed or are expected to  |
   |             |               | perform the activity.               |
   | object      | Link (Section | Describes the direct object of the  |
   |             | 3.4) value    | activity. For instance, in the      |
   |             |               | activity, "John saved a movie to    |
   |             |               | his wishlist", the object of the    |
   |             |               | activity is "movie". An activity    |
   |             |               | SHOULD contain an "object"          |



Snell                  Expires September 19, 2014              [Page 14]


Internet-Draft               ActivityStreams                  Aoril 2014


   |             |               | property. If the "object" property  |
   |             |               | is not contained, the primary       |
   |             |               | object of the activity MAY be       |
   |             |               | implied by context.                 |
   | target      | Link (Section | Describes the indirect object of    |
   |             | 3.4) value    | the activity. The precise meaning   |
   |             |               | of the activity's 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 identify an     |
   |             |               | indirect object that is not a       |
   |             |               | target of the activity.             |
   | result      | Link (Section | Describes the result of the         |
   |             | 3.4) value    | 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.         |
   | instrument  | Link (Section | An optional Link Value that         |
   |             | 3.4) value    | describes one or more objects used  |
   |             |               | to perform the action. For          |
   |             |               | instance, in the activity, "Sally   |
   |             |               | played music with a piano", the     |
   |             |               | instrument of the activity is the   |
   |             |               | "piano".                            |
   | participant | Link (Section | An optional Link Value that         |
   |             | 3.4) value    | describes one or more additional    |
   |             |               | actors that have or will indirectly |
   |             |               | participate in the activity.  For   |
   |             |               | instance, in the Activity, "Sally   |
   |             |               | went to the movies with Joe", Sally |
   |             |               | is the primary "actor" while Joe is |
   |             |               | a "participant".                    |
   | priority    | Decimal       | An indicator of the relative        |
   |             | Number        | priority or importance that the     |
   |             | between 0.00  | creator of an activity considers    |
   |             | and 1.00      | the it to have. Represented as a    |
   |             |               | numeric decimal between 0.00 and    |
   |             |               | 1.00, with two decimal places of    |
   |             |               | precision. If the property is       |
   |             |               | omitted or set to null, the         |
   |             |               | assumption is that a default        |
   |             |               | priority can be assumed. The value  |



Snell                  Expires September 19, 2014              [Page 15]


Internet-Draft               ActivityStreams                  Aoril 2014


   |             |               | 0.00 represents the lowest possible |
   |             |               | priority while 1.00 represents the  |
   |             |               | highest.                            |
   | status      | One of        | An optional, explicit indicator of  |
   |             | "active",     | the current status of the Activity. |
   |             | "canceled",   | "active" indicates that the         |
   |             | "completed",  | activity is ongoing; "canceled"     |
   |             | "pending",    | indicates that the activity has     |
   |             | "tentative",  | been aborted; "completed" indicates |
   |             | or "voided"   | that the activity concluded;        |
   |             |               | "pending" indicates that the        |
   |             |               | activity is expected to begin;      |
   |             |               | "tentative" indicates that the      |
   |             |               | activity has been proposed; and     |
   |             |               | "voided" indicates that the         |
   |             |               | activity statement has been         |
   |             |               | retracted or should be considered   |
   |             |               | invalid.                            |
   +-------------+---------------+-------------------------------------+

3.5.1.  Considerations on the use of "priority"

   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.





Snell                  Expires September 19, 2014              [Page 16]


Internet-Draft               ActivityStreams                  Aoril 2014


3.5.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
   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.4) | Specifies the public primary     |
   |           | value              | audience.                        |
   | cc        | Link (Section 3.4) | Specifies the public secondary   |
   |           | value              | audience.                        |
   | bto       | Link (Section 3.4) | Specifies the private primary    |
   |           | value              | audience.                        |
   | bcc       | Link (Section 3.4) | Specifies the private secondary  |
   |           | value              | 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.




Snell                  Expires September 19, 2014              [Page 17]


Internet-Draft               ActivityStreams                  Aoril 2014


   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
   specification leaves it up to implementations to determine how the
   audience targeting information is used.

3.6.  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 (Section   | A Link (Section 3.4) value        |



Snell                  Expires September 19, 2014              [Page 18]


Internet-Draft               ActivityStreams                  Aoril 2014


   |             | 3.4) value      | referencing one or more objects   |
   |             |                 | associated with the containing    |
   |             |                 | object. These are similiar in     |
   |             |                 | concept to files attached to an   |
   |             |                 | email message.                    |
   | author      | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing one or more entity    |
   |             |                 | that created or authored the      |
   |             |                 | object.                           |
   | content     | Natural         | A Natural-language description of |
   |             | Language value  | the object encoded as a single    |
   |             | (Section 3.2)   | JSON String containing HTML       |
   |             |                 | markup. Visual elements such as   |
   |             |                 | thumbnail images MAY be included. |
   | duplicates  | Link (Section   | A Link (Section 3.4)value         |
   |             | 3.4) value      | referencing one or more objects   |
   |             |                 | that 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.         |
   | icon        | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing one or more visual,   |
   |             |                 | 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 (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing one or more visual,   |
   |             |                 | graphic represenations of the     |
   |             |                 | object. Unlike the "icon"         |
   |             |                 | property, there are no aspect     |
   |             |                 | ratio or display restrictions.    |
   | location    | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | describing one or more physical   |
   |             |                 | or virtual locations associated   |
   |             |                 | with which the object.            |
   | published   | [RFC3339] date- | The date and time at which the    |
   |             | time            | object was published.             |
   | generator   | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing the application that  |
   |             |                 | generated the object.             |



Snell                  Expires September 19, 2014              [Page 19]


Internet-Draft               ActivityStreams                  Aoril 2014


   | provider    | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing the application that  |
   |             |                 | published the object. Note that   |
   |             |                 | this is not necessarily the same  |
   |             |                 | entity that generated the object. |
   | summary     | Natural         | A Natural-language summarization  |
   |             | Language value  | of the object encoded as a single |
   |             | (Section 3.2)   | JSON String containing a fragment |
   |             |                 | of HTML markup. Visual elements   |
   |             |                 | such as thumbnail images can be   |
   |             |                 | included.                         |
   | updated     | [RFC3339] date- | The date and time at which a      |
   |             | time            | previously published object has   |
   |             |                 | been modified.                    |
   | startTime   | [RFC3339] date- | A date-time describing the actual |
   |             | time            | or 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] date- | A date-time describing the actual |
   |             | time            | or 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 Number  | A quality rating expressed as a   |
   |             | between 1.0 and | number between 1.0 and 5.0        |
   |             | 5.0             | (inclusive) with one decimal      |
   |             |                 | place of precision.               |
   | tags        | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | referencing one or more resources |
   |             |                 | 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 for the  |
   |             | Language        | object expressed as a fragment of |
   |             | (Section 3.2)   | HTML markup. The "title" and      |
   |             | value           | "displayName" properties are      |
   |             |                 | closely related and overlap in    |



Snell                  Expires September 19, 2014              [Page 20]


Internet-Draft               ActivityStreams                  Aoril 2014


   |             |                 | function with the key difference  |
   |             |                 | being that "title" is permitted   |
   |             |                 | to contain HTML markup, while     |
   |             |                 | "displayName" is not.             |
   | 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" property        |
   |             |                 | indicates the recommended display |
   |             |                 | width in pixels.                  |
   | inReplyTo   | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | identifying one or more other     |
   |             |                 | objects to which the containing   |
   |             |                 | object can be considered a        |
   |             |                 | response.                         |
   | actions     | Action (Section | An optional Action (Section       |
   |             | 3.6.1) value    | 3.6.1) value that describes       |
   |             |                 | potential activities that can be  |
   |             |                 | performed with the object.        |
   | scope       | Link (Section   | A Link (Section 3.4) value        |
   |             | 3.4) value      | identifying one or more resources |
   |             |                 | that define the total population  |
   |             |                 | of entities for which the object  |
   |             |                 | is considered to be relevant.     |
   +-------------+-----------------+-----------------------------------+

3.6.1.  Action Values

   The "actions" property on an Activity Streams object is used to
   describe the kinds of activities that can be taken with regards to
   the object.  The value is expressed as a JSON dictionary mapping




Snell                  Expires September 19, 2014              [Page 21]


Internet-Draft               ActivityStreams                  Aoril 2014


   verbs to Link (Section 3.4) values referencing resources or objects
   that can be used to carry out those verbs.

   For instance, a hypothetical object with "video" as the objectType
   might have "watch", "share" and "embed" as potential actions:

       {
         "objectType": "video",
         "id": "http://example.org/cats.mpg",
         "actions": {
           "watch": "movie://example.org/cats.mpg",
           "share": {
             "objectType": "service",
             "displayName": "My Sharing Service",
             "url": "http://example.net/share"
           },
           "embed": [
             "http://example.org/gadgets/video.xml?v=cats.mpg",
             {
               "objectType": "inline-html",
               "content": "<video ... />"
             }
           ]
         }
       }

   Each key in the Action value MUST be a valid verb identifier
   conforming to either the "isegment-nz-nc" or "IRI" productions in
   [RFC3987] and be suitable for use as a value for Activity
   (Section 3.5) object's "verb" property.  The value of each key MUST
   be a valid Link (Section 3.4) value.

3.7.  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.4) 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".



Snell                  Expires September 19, 2014              [Page 22]


Internet-Draft               ActivityStreams                  Aoril 2014


   The value of the Collection object's "objectType" 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          |
   |              | date-time     | indicates that the collection      |
   |              |               | contains only items published or   |
   |              |               | updated strictly after the date    |
   |              |               | and time specified.                |
   | itemsBefore  | [RFC3339]     | A RFC 3339 date-time that          |
   |              | date-time     | indicates 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 (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing the furthest           |



Snell                  Expires September 19, 2014              [Page 23]


Internet-Draft               ActivityStreams                  Aoril 2014


   |              |               | preceeding page of a multi-page    |
   |              |               | collection.                        |
   | last         | Link (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing the furthest following |
   |              |               | page of a multi-page collection.   |
   | prev         | Link (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing the immediately        |
   |              |               | 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 (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing the immediately        |
   |              |               | following page of the multi-page   |
   |              |               | collection.                        |
   | current      | Link (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing the page containing    |
   |              |               | the items that have been updated   |
   |              |               | or published most recently.        |
   | self         | Link (Section | A Link (Section 3.4) value         |
   |              | 3.4) value    | referencing this page.             |
   +--------------+---------------+------------------------------------+

3.7.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":









Snell                  Expires September 19, 2014              [Page 24]


Internet-Draft               ActivityStreams                  Aoril 2014


   +-----------+---------------+---------------------------------------+
   | Property  | Value         | Description                           |
   +-----------+---------------+---------------------------------------+
   | replies   | Collection    | Provides information about the set of |
   |           | (Section 3.7) | 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:

   {
     "objectType": "note",
     "id": "urn:example:note:1",
     "displayName": "A note about things",
     "content": "blah blah blah",
     "replies": {
       "url": "http://example.org/note/1/comments.json",
       "mediaType": "application/activity+json",
       "totalItems": 10,
       "items": [
         {
           "objectType": "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 an ordered listing of Activity objects.

   Publishers using this format MUST produce a valid JSON document whose
   root value is a Collection (Section 3.7).

   The MIME media type of this document MUST be "application/
   activity+json".








Snell                  Expires September 19, 2014              [Page 25]


Internet-Draft               ActivityStreams                  Aoril 2014


5.  Reserved Object Types and Verbs

   The following objectType and verb values are reserved for specific
   uses by this specification:

5.1.  Object Types

   +------------+------------------------------------------------------+
   | Type       | Description                                          |
   +------------+------------------------------------------------------+
   | activity   | Objects specifying "objectType":"activity" conform   |
   |            | to the Activity construct defined in Section 3.5.    |
   | verb       | Objects specifying "objectType":"verb" provide       |
   |            | metadata about an extension verb as defined in       |
   |            | Section 3.3.  The "id" attribute of such objects     |
   |            | MUST be provided.                                    |
   | objectType | Objects specifying "objectType":"objectType" provide |
   |            | metadata about an extension objectType as defined in |
   |            | Section 3.3.  The "id" attribute of such objects     |
   |            | MUST be provided.                                    |
   | collection | Objects specifying "objectType":"collection" conform |
   |            | to the Collection construct defined in Section 3.7.  |
   +------------+------------------------------------------------------+

5.2.  Verbs

   +------+------------------------------------------------------------+
   | Type | Description                                                |
   +------+------------------------------------------------------------+
   | post | The "post" verb describes the act of authoring an object   |
   |      | and then publishing it online. The actor can be any        |
   |      | entity; the object can be of any object type; and the      |
   |      | target, if specified, can be of any object type. A target, |
   |      | however, is not required.                                  |
   +------+------------------------------------------------------------+

6.  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.




Snell                  Expires September 19, 2014              [Page 26]


Internet-Draft               ActivityStreams                  Aoril 2014


   Specifically:

   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 the 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 redefines the "displayName", "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.

   4.  This document redefines a large number of common properties
       defined originally as Objects in 1.0 as Link values
       (Section 3.4).  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.

   5.  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.4).
       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.

7.  Comparison of Identifier Values

   The values of "id" properties can be compared to determine if the
   identifiers represent duplicate content.  The values MUST be compared
   on a character-by-character, case-sensitive basis.  Comparisons MUST




Snell                  Expires September 19, 2014              [Page 27]


Internet-Draft               ActivityStreams                  Aoril 2014


   be based solely on the character strings themselves 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.

8.  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.1.  Extension verbs and objectTypes

   Verb and objectType identifiers are expressed in one of two ways:
   either as a simple token value matching the "isegment-nz-nc"
   production in [RFC3987] or as an absolute IRI.  When expressed as an
   IRI, it is RECOMMENDED that the final component (either the last path
   segment or fragment identifier) conforms to the "isegment-nz-nc"
   production as well.  For instance, "http://example.org/verbs/like" or
   "http://example.org/verbs#like".

   When selecting a verb identifier that is a direct equivalent to a
   natural language verb or action, it is RECOMMENDED that the final
   isegment-nz-nc token is expressed as the "infinitive" or "base" form
   of the natural language verb, without indication of linguistic tense,
   mood or aspect.  For example, the verb identifier "http://example.org
   /verbs/share" is preferable to alternative forms like "http://
   example.org/verbs/shared" or "http://example.org/verbs/sharing".

   Verb identifiers may also be idiomatic in nature.  For example, an
   activity such as "Joe flagged the post as inappropriate", could be
   expressed using an idiomatic verb "flag-as-inappropriate":

     {
       "actor": "acct:joe@example.org",
       "verb": "flag-as-inappropriate",
       "object": "http://example.org/posts/1"
     }

   In such cases, the verb identifier may not necessarily correlate a
   single discrete linguistic verb infinitive, but SHOULD still be
   expressed in the infinitive form (e.g. "flag-as-inappropriate" as
   opposed to "flagged-as-inappropriate").



Snell                  Expires September 19, 2014              [Page 28]


Internet-Draft               ActivityStreams                  Aoril 2014


   When selecting an objectType identifier that is a direct equivalent
   to a natural language common noun, it is RECOMMENDED that the final
   isegment-nz-nc token is expressed in terms of a singular instance of
   the object.  For example, the objectType identifier "http://
   example.org/objects#bird" is preferable to "http://example.org/
   objects#birds".

   The objectType identifier MUST NOT be used to specific individual
   instances of a class of object -- for instance, it would never be
   appropriate to have "objectType": "acct:joe@example.org", even though
   the value "acct:joe@xample.org" is a valid absolute IRI.

   Note, finally, that verb and objectType identifiers are not dependent
   on language context.  That is, while the natural language verbs
   "speak" (English) and "hablar" (Spanish) are equivalent natural
   language translations, they are not considered to be equivalent verb
   identifiers as defined in Section 7.  Implementations are free to
   treat such variations as equivalent but doing so is considered beyond
   the scope of this specification.

9.  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.





Snell                  Expires September 19, 2014              [Page 29]


Internet-Draft               ActivityStreams                  Aoril 2014


   Activity Streams are JSON Documents and are subject to the same
   security considerations described in [RFC4627].

   Activity Streams implementations handle URIs.  See Section 7 of
   [RFC3986].

   Activity Streams implementations handle IRIs.  See Section 8 of
   [RFC3987].

10.  IANA Considerations

10.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>




Snell                  Expires September 19, 2014              [Page 30]


Internet-Draft               ActivityStreams                  Aoril 2014


      Intended usage: COMMON

      Restrictions on usage: None.

      Author: James M Snell <jasnell@gmail.com>

      Change controller: IESG

11.  References

11.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,
              <http://activitystrea.ms/specs/json/1.0/>.








Snell                  Expires September 19, 2014              [Page 31]


Internet-Draft               ActivityStreams                  Aoril 2014


11.2.  Informational References

   [RFC6963]  Saint-Andre, P., "A Uniform Resource Name (URN) Namespace
              for Examples", BCP 183, RFC 6963, May 2013.

   [audience]
              Snell, J., "Audience Targeting for JSON Activity Streams",
              March 2012,
              <http://activitystrea.ms/specs/json/targeting/1.0/>.

   [base-schema]
              Activity Streams Workgroup, "Activity Streams - Base
              Schema", September 2012, <https://github.com/
              activitystreams/activity-schema/blob/master/activity-
              schema.md>.

   [priority]
              Snell, J., "Priority Extension for JSON Activity Streams",
              June 2012, <https://raw.github.com/jasnell/specs/master/
              activitystrea.ms/priority_extension.txt>.

   [responses]
              Snell, J., "Responses for Activity Streams", March 2012,
              <http://activitystrea.ms/specs/json/replies/1.0/>.

Appendix A.  Acknowledgements

   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



Snell                  Expires September 19, 2014              [Page 32]


Internet-Draft               ActivityStreams                  Aoril 2014


   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&#263;, 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 September 19, 2014              [Page 33]


Internet-Draft               ActivityStreams                  Aoril 2014


     {
       "@context": {
         "@vocab": "http://activitystrea.ms/spec/2.0/",
         "verb": "@type",
         "objectType": "@type",
         "id": "@id",
         "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",
       "displayName": "John purchased 'A Tale of Two Cities'",
       "startTime" : "2013-04-02T12:31Z",
       "endTime" : "2013-04-02T12:31Z",
       "actor": {
         "objectType": "person",
         "displayName": "John Doe"
       },
       "object": {
         "objectType": "book",
         "displayName": "A Tale of Two Cities"
       }
     }

Appendix C.  Activity Statement Linguistic Forms

   The Activity Streams format has been intentionally designed to be
   flexible in how statements about past, present or future actions can
   be expressed.

C.1.  Intransitive Activity

   In many situations, the "actor" of an Activity also serves as the
   "direct object".  For example, if I say, "The process terminated",
   then the "process" is both the "actor" and the "object".  Such
   statements are formally known as being "intransitive".

   To describe intransitive actions using the Activity Streams syntax,
   simply omit the "object" property:









Snell                  Expires September 19, 2014              [Page 34]


Internet-Draft               ActivityStreams                  Aoril 2014


     {
       "actor": {
         "objectType": "process",
         "displayName": "Build Process"
       },
       "verb": "terminate"
     }

C.2.  Transitive Activity

   In a "transitive" activity, the actor and direct object are distinct
   entities.  This is the form most commonly expressed using the
   Activity Streams format.  For instance, if I say, "Joe posted a blog
   entry", the actor is "Joe" and the "blog entry" is the direct object.

     {
       "actor": "acct:joe@example.org",
       "verb": "post",
       "object": {
         "objectType": "article",
         "title": "A Blog Entry",
         "content": "..."
       }
     }

C.3.  Ditransitive Activity

   In "ditransitive" activities, there exist distinct actor, direct and
   indirect objects.  The indirect object specifies the target to which
   the action on the direct object has been directed.  For instance, in
   "Joe posted a blog entry to his Weblog", the indirect object (or
   "target") is "Joe's Weblog".

     {
       "actor": "acct:joe@example.org",
       "verb": "post",
       "object": {
         "objectType": "article",
         "title": "A Blog Entry",
         "content": "..."
       },
       "target": {
         "objectType": "blog",
         "title": "Joe's Weblog"
       }
     }





Snell                  Expires September 19, 2014              [Page 35]


Internet-Draft               ActivityStreams                  Aoril 2014


C.4.  Expressing tense and aspect

   By using the "startTime", "endTime", "duration" and "status"
   properties, Activity statements can be used to express past, present
   or future actions.  Implementations should never rely on an activity
   statement's verb identifier to determine the tense or aspect of the
   action.

   For instance, to indicate an activity that has already concluded, the
   startTime and endTime properties would be used to indicate past
   points in time:

     {
       "actor": "acct:joe@example.org",
       "verb": "post",
       "object": "http://example.org/blog/entry/1",
       "startTime": "2012-12-12T12:12:12Z",
       "endTime": "2012-12-12T12:12:12Z"
     }

   If specific start and end times for a concluded activity are not
   available, the "status" property can be used to expressly indicate
   that the action has completed:

     {
       "actor": "acct:joe@example.org",
       "verb": "post",
       "object": "http://example.org/blog/entry/1",
       "status": "completed"
     }

   To indicate an activity that began in the past but is still ongoing,
   only the startTime property would be used:

     {
       "actor": "acct:joe@example.org",
       "verb": "watch",
       "object": "http://movies.example.org/movie/1",
       "startTime": "2014-03-18T04:32:43Z"
     }

   The status property value "active" can also be used to identify
   ongoing activities:








Snell                  Expires September 19, 2014              [Page 36]


Internet-Draft               ActivityStreams                  Aoril 2014


     {
       "actor": "acct:joe@example.org",
       "verb": "watch",
       "object": "http://movies.example.org/movie/1",
       "status": "active"
     }

   To indicate an activity that is expected to begin in the future, the
   startTime property would indicate a future point in time:

     {
       "actor": "acct:joe@example.org",
       "verb": "cook",
       "object": "http://recipes.example.org/recipe/1",
       "startTime": "2015-12-23T12:34:21Z"
     }

   Or, alternatively:

     {
       "actor": "acct:joe@example.org",
       "verb": "cook",
       "object": "http://recipes.example.org/recipe/1",
       "status": "pending"
     }

   The status values "pending" and "tentative" differ in that the former
   is used to mark actions that are expected to happen while the latter
   is used to mark proposed actions that may (or may not) happen.

   As an alternative to explicitly stating the "startTime" or "endTime"
   properties, the "duration" property can be used to indicate a
   specific duration of time relative to either the "startTime" or
   "endTime".  For instance, specifying an "endTime" of
   "2015-12-23T12:23:23Z" with a duration of "PT1H", implies a startTime
   of exactly "2015-12-23T11:23:23Z" (1 hour before the specified
   endTime).

   Note that the value of the "duration" property can be expressed
   either as a non-negative integer specifying a number of seconds, or
   as an [RFC3339] "duration" string such as "PT1H", "P1DT1H", etc.  For
   Activity Streams 2.0 implementations for which backwards
   compatibility with the Activity Streams 1.0 syntax is not critical,
   the RFC 3339 string format is strongly recommended.







Snell                  Expires September 19, 2014              [Page 37]


Internet-Draft               ActivityStreams                  Aoril 2014


C.5.  Activity Duration

   Actions expressed via the Activity Streams format can either be
   instantaneous (semelfactive) or durative (having distinct start and
   end times).  The specific duration of an activity can be optionally
   expressed using the "startTime", "endTime" and "duration" properties.

   By default, all activities are assumed to occur instantaneously, that
   is, occuring at one point in time without any specific duration.
   Such events are indicated by omitting the "startTime", "endTime" or
   "duration" properties:

     {
       "actor": "acct:sally@example.org",
       "verb": "post",
       "object": "http://example.org/notes/1"
     }

   An activity that occurs within a specific period of time can be
   expressed using combinations of either: "startTime" and "endTime",
   "startTime" and "duration", or "endTime" and "duration".  For
   example:

     {
       "actor": "acct:sally@example.org",
       "verb": "watch",
       "object": "http://movies.example.org/movies/1",
       "startTime": "2014-05-23T12:23:12Z",
       "endTime": "2014-05-23T13:25:15Z"
     }

     {
       "actor": "acct:sally@example.org",
       "verb": "watch",
       "object": "http://movies.example.org/movies/1",
       "startTime": "2014-05-23T12:23:12Z",
       "duration": "PT1H2M3S"
     }

     {
       "actor": "acct:sally@example.org",
       "verb": "watch",
       "object": "http://movies.example.org/movies/1",
       "duration": "PT1H2M3S",
       "endTime": "2014-05-23T13:25:15Z"
     }





Snell                  Expires September 19, 2014              [Page 38]


Internet-Draft               ActivityStreams                  Aoril 2014


Appendix D.  Motivational Use Cases

   This specification defines a number of syntax changes relative to the
   JSON Activity Streams 1.0 specification.  The sections that follow
   describe some of the general motivations for these changes with
   illustrative examples.

D.1.  Internationalization (i18n)

   The JSON Activity Streams 1.0 syntax has no inherent notion of a
   "language context".  That is, the core syntax has no internal
   mechanism a publisher can use to identify the language used when
   constructing the Activity Streams document.  Nor are there any
   existing mechanisms at the JSON syntax level that an Activity Streams
   implementation can inherit.  This specification introduces the
   "language" property and Natural Language Value concepts to fill this
   gap.

   Imagine a scenario with a service that receives Activity objects from
   users and republishes those to a distributed audience of interested
   parties.  This service spans international boundaries and the users
   speak a multitude of different languages.  Within this system, a
   native English speaker might subscribe to notifications about
   activities posted by a native French speaker.

   For instance, let's suppose that our native French speaker posts the
   following activity to this system:

     POST /activity/feed HTTP/1.1
     Content-Type: application/activity+xml

     {
       "verb": "post",
       "language": "fr",
       "object": {
         "objectType": "article",
         "displayName": "Un exemple basique",
         ...
       }
     }

   The system receives this activity post and prepares to notify our
   native English speaking user.  Knowing that this user prefers English
   and does not speak a word of French, the system can inspect the
   Activity and detect automatically that a translation ought to be
   provided.  Rather than replacing the original French text, however,
   the service can simply add in the English translation along side it.




Snell                  Expires September 19, 2014              [Page 39]


Internet-Draft               ActivityStreams                  Aoril 2014


     {
       "verb": "post",
       "language": "fr",
       "actor": {
         "id": "urn:example:person:abc",
         "displayName": "Jean Valjean"
       },
       "object": {
         "type": "article",
         "displayName": {
           "fr": "Un exemple basique",
           "en": "A basic example"
         }
         ...
       }
     }

   It is also possible for a Natural Language Value to express
   alternative same-language representations of a string that utilize
   different writing systems or regions.  For instance, it is common for
   Japanese translations to provide equivalent ideographic (kanji) and
   phonetic (katakana or hiragana) alternatives:

     {
       "title": {
         "ja-Hani": "...",
         "ja-Kana": "..."
       }
     }

D.2.  Extensibility (e11y)

   Arguably, the two most important extensibility points in the Activity
   Streams format are the object type and verb properties.
   Implementations are free to come up with their own types and verbs at
   any point.  While such extensibility is extremely powerful, it comes
   with a cost.  Namely, implementations that encounter previously
   unknown verbs and object types may not have enough to knowledge about
   those to do anything significant with them.

   For instance, the most common use case for Activity Streams today is
   the generation of a human-readable "activity feed" that translates
   Activity objects into sentences just as "John uploaded a new photo"
   or "Jane checked in at a hotel", etc.  Given an extension verb such
   as "http://example.org/whatever", an implementation might not have
   sufficient information about that verb to generate a readable
   sentence describing the activity that occurred.




Snell                  Expires September 19, 2014              [Page 40]


Internet-Draft               ActivityStreams                  Aoril 2014


   With Activity Streams 1.0, a number of different approaches have been
   tried to address this problem, but all of the solutions essentially
   deal with the need to provide additional metadata about extension
   verbs and object types so that an implementation can dynamically
   learn and adapt.  The notion of "type values" is added by this
   specification to specifically deal with this issue.

   For example, suppose I have an implementation that generates Activity
   objects that use a new extension verb "urn:example:verbs:upload".
   Knowing that consumers of these objects might not have encountered
   this verb before, I want to make it possible for those
   implementations to automatically discover metadata about the new
   verb.  To do so, I can use a type value to provide some basic
   information.

     {
       "verb": {
         "id": "urn:example:verbs:upload",
         "url": "http://example.org/verbs.json",
         "mediaType": "application/ld+json",
         "displayName": {
           "en": "upload",
           "fr": "televersement"
         },
         "alias": "post"
       },
       "actor": {
         "type": "person",
         "displayName": "John"
       },
       "object": {
         "type": "photo",
         "displayName": "cats.jpg"
       }
     }

   An implementation receiving this has several choices.  It could
   choose to ignore everything other than the verb's identifier,
   treating it generically as one would have to today using the 1.0
   syntax; or, it could inspect the metadata provided and notice that
   the extension verb can be treated generally as an alias of "post" or
   displayed in English as "upload" and in French as "televersement";
   or, it can choose to attempt discovering more information about the
   verb by dereferencing the provided URL.

   The point is, these options are built into the core syntax, making
   extension verbs and object types significantly more usable,
   particularly when combined with the new language context features.



Snell                  Expires September 19, 2014              [Page 41]


Internet-Draft               ActivityStreams                  Aoril 2014


D.2.1.  Publishing Extension objectType and verb Libraries

   By treating extension objectTypes and verbs as objects in their own
   right, it becomes trivially possible to use the Activity Streams
   format as a means of publishing metadata about extension verbs.

   For example:

     {
       "displayName": "My object types and verbs",
       "items": [
         {
           "objectType": "verb",
           "id": "urn:example:verbs:create",
           "alias": "post",
           "displayName": "Create"
         },
         {
           "objectType": "objectType",
           "id": "urn:example:types:article",
           "displayName": "Article"
         }
       ]
     }

   Implementations could use such documents to dynamically learn about
   new verbs and objectTypes.

D.3.  First Class Links

   Linking in the 1.0 syntax is largely undefined and inconsistent.
   There is a general notion of Media Link objects that are used for
   some things like images and videos, along with a "url" property that
   in some cases is used to always point to HTML represenations while in
   other cases might point to JSON documents or image files, and there
   is no reusable concept of a generic link provided for extensions to
   leverage which has led to inconsistent implementation.  The 2.0
   syntax introduced here deals with these issues by introducing a
   clear, consistent, reusable first class linking model.

   For instance, using the 2.0 syntax, an "image" object type can be
   represented simply as:









Snell                  Expires September 19, 2014              [Page 42]


Internet-Draft               ActivityStreams                  Aoril 2014


     {
       "objectType": "image",
       "url": "http://example.org/cats.jpg",
       "mediaType": "image/jpeg",
       "displayName": "A picture of my cats",
       "alternate": {
         "url": "http://example.org/gallery?i=cats.jpg",
         "mediaType": "text/html"
       }
       "preview": "http://example.org/thumbnails/cats.jpg"
     }

   Essentially, any 2.0 object that contains a "url" property can be
   interpreted as a link.  That "url" property points to a
   representation of the object, while the "mediaType" property
   identifies the content type of that linked resource.  RFC 5988 Link
   Relations can be used directly within the 2.0 syntax to provide
   additional data -- in this case, an alternative HTML representation
   of the image as well as a thumbnail preview.

   Another case that the more flexible linking approach allows us to
   address is providing multiple links for a single property.  For
   instance, it is not uncommon for there to be several alternative
   versions of an image resource offered at various resolutions to
   support multiple types of devices.  With the 2.0 syntax, multiple
   choices for a single link can be easily provided.

     {
       "objectType": "application",
       "displayName": "My application",
       "icon": [
         {
           "url": "http://example.org/sd/icon.png",
           "width": 57,
           "height": 57
         },
         {
           "url": "http://example.org/hd/icon.png",
           "width": 114,
           "height": 114
         }
       ],
       "preview": [
         "http://www.example.org/screenshots/1.jpg",
         "http://www.example.org/screenshots/2.jpg",
         "http://www.example.org/screenshots/3.jpg"
       ]
     }



Snell                  Expires September 19, 2014              [Page 43]


Internet-Draft               ActivityStreams                  Aoril 2014


D.4.  Use of External Vocabularies

   Use of an "external vocabulary" within Activity Streams means using
   object types, verbs and properties that are not defined by the core
   Activity Streams specification.  An example would be using concepts
   defined within a microdata vocabulary such as that defined by
   Schema.org (http://schema.org).

   Implementations that wish to use a Activity Streams with such
   external vocabularies face the challenge that, often times, identical
   or overlapping concepts can be expressed in a multitude of ways
   depending on which vocabulary is selected.  This can make it
   difficult to map abstract data models into a specific JSON
   serialization.

   For instance, suppose an application uses the Schema.org model to
   represent an article, described here: http://schema.org/Article.
   Within this model, there are several properties defined that directly
   overlap properties defined by the core Activity Streams syntax.  Such
   properties include "name", "contentLocation", and "articleBody".  In
   order to encode the abstact model of a Schema.org/Article into the
   JSON Activity Streams model, the application needs to determine
   precisely how to map the abstract properties to the serialized
   format.  In Activity Streams 1.0, no guidance was given on how to
   achieve such a mapping, within the 2.0 syntax, the JSON Serialization
   for Linked Data (JSON-LD) provides a foundation.

   Using JSON-LD I can maintain basic Activity Streams 2.0 syntax while
   mapping the physical serialization to the abstract model inline.

     {
       "objectType": "article",
       "displayName": "My article about things",
       "content": "This is my article",
       "@context": {
         "objectType": "@type",
         "article": "http://schema.org/Article",
         "displayName": "http://schema.org/name",
         "content": "http://schema.org/Article/articleBody"
       }
     }

   For any non-JSON-LD aware implementation, this can be processed just
   as if it were an ordinary Activity Streams object, without any
   additional consideration given.  For a JSON-Ld aware implementation,
   however, the addition of the "@context" property allows the
   serialized JSON to be unambiguously mapped to the Schema.org concept
   of an "Article".  The fact that we can support such a mapping allows



Snell                  Expires September 19, 2014              [Page 44]


Internet-Draft               ActivityStreams                  Aoril 2014


   the Activity Streams format to extend to a broader range of scenarios
   without requiring alternative, incompatible vocabulary specific
   models of "actions" or "activities" to be developed.

D.5.  Embedded Actions

   Every Activity Streams object represents a discreet modular component
   that can be distributed, shared, or acted upon in a variety of ways.
   The 2.0 syntax allows these components to not only express
   information about the content but also about the specific types of
   actions that can be performed with the object.

   For example, an email that is automatically generated by an expense
   reporting system could embed a structured Activity Stream object that
   contains a listing of the possible actions the recipient of the email
   can take.  An intelligent email agent can interpret this embedded
   metadata and provide a tailored, in-context UI experience:

     <html>
       <body>
         <script type="application/activity+json">
           {
             "objectType": "expense-report",
             "url": "url": "https://example.org/view?id=abc123",
             "description": "John's trip to San Francisco",
             "actions": {
               "approve": "https://example.org/approve?id=abc123",
               "reject": "https://example.org/reject?id=abc123"
             }
           }
     </script>
       <p>
         Your employee, John Doe, has submitted a new expense
         report for "John's trip to San Francisco"....
       </body>
     </html>

Author's Address

   James M Snell (editor)
   IBM

   Email: jasnell@gmail.com








Snell                  Expires September 19, 2014              [Page 45]