draft-snell-activitystreams-02.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
  <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'> 
  <!ENTITY rfc3987 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml'>
  <!ENTITY rfc3986 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
  <!ENTITY rfc3339 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml'>
  <!ENTITY rfc4627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>
  <!ENTITY rfc5988 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml'>
  <!ENTITY rfc6963 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6963.xml'>
  <!ENTITY rfc5646 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5646.xml'>
  <!ENTITY rfc5226 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml'>
  <!ENTITY jsonld  PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.WD-json-ld-20130411.xml'>
]>

<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-snell-activitystreams-02" >
  <front>
    <title abbrev="ActivityStreams">JSON Activity Streams 2.0</title>

    <author fullname="James M Snell" initials="J." surname="Snell" role="editor">
      <organization>IBM</organization>
      <address> 
        <email>jasnell@gmail.com</email> 
      </address> 
    </author>

    <date month="July" year="2013" />
    <area>General</area> 
    <workgroup>Activity Streams (http://activitystrea.ms)</workgroup>
    <keyword>JSON</keyword>
    <keyword>Activity Streams</keyword>

    <abstract>
      <t>
        This specification details a model for representing potential and 
        completed activities using the JSON format.
      </t>
    </abstract>
    
    <note title="Author's Note">
      <t>
        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.
      </t>
      <t>
        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). 
      </t>
    </note>

  </front>

  <middle>
    <section anchor="introduction" title="Introduction">

      <t>
        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.
      </t>

      <t>
        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.
      </t>
      
      <t>
        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 
        <xref target="RFC2119" />.
      </t>
      
      <section title="Relationship to JSON Activity Streams 1.0" anchor="asms-1">
        
        <t>
          The <xref target="activitystreams-1.0">JSON Activity 
          Streams 1.0</xref> 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.
        </t>
        
        <t>
          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.
        </t>
        
      </section>

      <section title="Relationship to JSON-LD 1.0" anchor="json-ld" >
        
        <t>
          The <xref target="W3C.WD-json-ld-20130411">JSON-based Serialization for 
          Linked Data (JSON-LD)</xref> 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.
        </t>
        
        <t>
          There are a few differences between JSON-LD and the 
          serialization syntax described here, specifically:
          <list style="symbols">
            <t>
              JSON-LD uses certain field names with a leading "@" character,
              such as "@id" and "@language". In this specification, the 
              leading "@" is omitted.
            </t>
            <t>
              While JSON-LD allows using relative IRI references
              in the values of "id" properties, this specification 
              limits identifiers to absolute IRIs.
            </t>
            <t>
              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.
            </t>
          </list>
        </t>
        
        <t>
          When processing an Activity Streams document as JSON-LD, the 
          following rules apply:
          <list style="symbols">
            <t>
              The "objectType" property MUST be treated as an alias of 
              JSON-LD "@type".
            </t>
            <t>
              The "id" property MUST be treated as an alias of JSON-LD "@id".
            </t>
            <t>
              The "language" property MUST be treated as an alias of JSON-LD 
              "@language".
            </t>
            <t>
              A JSON array used to convey <xref target="link">Link</xref> values
              MUST be treated as an unordered JSON-LD @set (@container = @set).
            </t>
            <t>
              The JSON array value for the "items" property defined in
              <xref target="collection" /> MUST be treated as an ordered
              JSON-LD @list (@container = @list).
            </t>
            <t>
              The "displayName", "title", "content" and "summary" properties
              defined in <xref target="object" /> and <xref target="object-ext" />
              MUST be treated as JSON-LD Language Maps (@container = @language).
            </t>
          </list>
        </t>
        
      </section>
      
      <section anchor="serialization" title="Syntax Conventions">
        
        <t>
          This specification defines a <xref target="RFC4627">JSON-based</xref> 
          serialization syntax.
        </t>
        
        <t>
          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.
        </t>

        <t>
          This specification uses IRIs <xref target="RFC3987"/>.
          Every URI <xref target="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
          <xref target="RFC3987"/> and (2) when an IRI is serving as
          an "id" value, it MUST NOT be so mapped.
        </t>

        <t>
          Unless otherwise specified, all properties with date and
          time values MUST conform to the "date-time" production in 
          <xref target="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).
        </t>
        
      </section>

    </section>
    
    <section anchor="examples" title="Example Activities">

      <t>
        Following are three examples of activities with varying 
        degrees of detail.
      </t>

      <section title="Example 1: Minimal Activity">
        
        <t>
          Expresses the statement "'urn:example:person:martin' posted
          'http://example.org/foo.jpg'". No additional detail is 
          given.
        </t>
        
        <figure>
          <artwork><![CDATA[
  {
    "verb": "post",
    "actor": "urn:example:person:martin",
    "object": "http://example.org/foo.jpg"
  }
          ]]></artwork>
        </figure>
        
      </section>
      
      <section title="Example 2: Basic activity with some additional detail">

        <t>
          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.</t>

<figure><artwork><![CDATA[
  {
    "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/"
    }
  }
]]></artwork></figure>

        </section>

        <section title="Example 3: An extended activity">

        <t>
          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.
        </t>

<figure><artwork><![CDATA[
  {
    "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 físeán 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
          }
        },
        "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 Máirtín"
          },
          "image": {
            "url": "http://example.org/album/thumbnail.jpg",
            "mediaType": "image/jpeg",
            "width": 250,
            "height": 250
          }
        }
      }
    ]
  }
]]></artwork></figure>

      </section>

    </section>
    
    <section anchor="model" title="Object Model">

      <section anchor="object" title="Object">

        <t>
          The following "core properties" apply to all JSON objects serialized
          within an Activity Stream document.
        </t>
 
        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>     
          <c>id</c>
          <c>IRI</c>
          <c>
            Provides a permanent, universally unique identifier for the
            object in the form of an absolute IRI <xref target="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.
          </c>
          <c>objectType</c>
          <c><xref target="type-value">Type value</xref></c>
          <c>
            Identifies the type of object. An object MAY contain a "objectType"
            property whose value is a <xref target="type-value">Type value</xref>. 
            If no "objectType" property is specified, the object has no specific type.
          </c>
          
          <c>language</c>
          <c><xref target="RFC5646"/> Language Tag</c>
          <c>
            Establishes the default language assumed for human-readable, 
            natural-language metadata values included in the object. An 
            object MAY contain a "language" property whose value MUST be a 
            <xref target="RFC5646"/> Language-Tag.
          </c>
          
          <c>displayName</c>
          <c><xref target="lang">Natural Language value</xref></c>
          <c>
            A simple human-readable, plain-text name for the 
            object. HTML markup MUST NOT be included. An object MAY contain a 
            "displayName" property. If the object does not specify a "objectType"
            property, the object SHOULD specify a "displayName".
          </c>
          
          <c>url</c>
          <c>Link</c>
          <c>
            A <xref target="link">Link</xref> value describing a resource 
            that provides a representation of the object. An object 
            MAY contain a "url" property.
          </c>  
        </texttable>
        
      </section>

      <section anchor="lang" title="Natural Language Values">
        
        <t>
          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 <xref target="RFC5646" /> Language-Tags to localized,
          equivalent translations of the same string value. 
        </t>
        
        <t>
          For instance, the "displayName" property in all objects is a
          Natural Language value.
        </t>
        
        <figure>
          <preamble>A single String value using the default language:</preamble>
          <artwork>
  {
    "language": "en",
    "displayName": "This is the title"
  }
          </artwork>
        </figure>
        
        <figure>
          <preamble>Multiple, language-specific values:</preamble>
          <artwork>
  {
    "displayName": {
      "en": "This is the name",
      "fr": "C'est le titre",
      "sp": "Este es el título"
    }
  }
          </artwork>
        </figure>
        
        <t>
          Each key in the JSON dictionary MUST be an <xref target="RFC5646" />
          Language Tag. The associated values MUST be Strings.
        </t>
        
      </section>
      
      <section anchor="type-value" title="Type Values">
        
        <t>
          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 
          <xref target="RFC3987"/> or (2) an <xref target="object">Object</xref>. 
          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.
        </t>
        
        <t>
          Within the Activity Streams 2.0, Type values are used only
          by the "objectType" and "verb" properties.
        </t>
        
        <figure><preamble>Object type as a simple name (isegment-nz-nc):</preamble><artwork>
  {
    "objectType": "person",
    "displayName": "John"
  }
        </artwork></figure>
        
        <figure><preamble>Object type as an absolute IRI:</preamble><artwork>
  {
    "objectType": "http://example.org/Person",
    "displayName": "John"
  }
        </artwork></figure>
        
        <figure><preamble>Object type as an object:</preamble><artwork>
  {
    "objectType": {
      "id": "http://example.org/Person",
      "displayName": "Person"
    },
    "displayName": "John"
  }
        </artwork></figure>
        
        <t>
          Because the second and third examples above each specify
          "http://example.org/Person", the two examples are considered
          to specify the same type.
        </t>
        
        <figure><preamble>Verb as a simple name (isegment-nz-nc):</preamble><artwork>
  {
    "verb": "post",
    "actor": "acct:john.doe@example.org",
    "object": "http://example.org/123"
  }
        </artwork></figure>
        
        <figure><preamble>Verb as an absolute IRI:</preamble><artwork>
  {
    "verb": "http://example.com/Upload",
    "actor": "acct:john.doe@example.org",
    "object": "http://example.org/123"
  }
        </artwork></figure>
        
        <figure><preamble>Verb as an object:</preamble><artwork>
  {
    "verb": {
      "id": "http://example.com/Upload",
      "displayName": "Upload"
    },
    "actor": "acct:john.doe@example.org",
    "object": "http://example.org/123"
  }
        </artwork></figure>
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
      </section>

      <section anchor="link" title="Link Values">

        <t>
          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 <xref target="object">Object</xref>,
          or (3) a JSON Array containing a mixture of IRIs or 
          <xref target="object">Objects</xref>. Link values are closely related 
          to the conceptual model of Links as established in 
          <xref target="RFC5988"/>.
        </t>
        
        <t>
          For example, as defined previously, all 
          <xref target="object">objects</xref> 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.
        </t>
        
        <figure><preamble>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:</preamble><artwork>
  {
    "objectType": "application",
    "id": "http://example.org/application/123",
    "displayName": "My Application",
    "image": "http://example.org/application/123.png"
  }
        </artwork></figure>
          
        <figure><preamble>Alternatively, if additional metadata is required, 
          the link can be expressed as an object containing the url 
          property.</preamble>
          <artwork>
  {
    "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
    }
  }
          </artwork>
        </figure>
        
        <figure><preamble>If more than one link value is to be expressed,
          A JSON Array with a mix of string and object elements can be 
          used:</preamble><artwork>
  {
    "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
      }
    ]
  }
        </artwork></figure>
        
        <t>
          Individual items contained in such an array are independent
          of the others and no significance is given to the ordering of 
          those items.
        </t>

        <t>
          RFC 5988 defines that all Links have a "link relation" 
          that describes the contextual purpose of the link. Within 
          an <xref target="object">object</xref>, 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. 
        </t>
        
        <figure><preamble>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.</preamble><artwork><![CDATA[
  {
    "objectType": "application",
    "image": [
      "http://example.org/foo.jpg",
      {
        "url": "http://example.org/screens/1.jpg",
        "rel": "preview",
        "mediaType": "image/jpeg"
      }
    ]
  }
        ]]></artwork></figure>
        
        <t>
          When an <xref target="object">object</xref> is used to represent
          a Link value, the following additional properties MAY be used:
        </t>
        
        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>

          <c>rel</c>
          <c>RFC 5988 Link Relation</c>
          <c>
            The RFC 5988 Link Relation associated with this link value.
            If absent, the name of the property is assumed to specify 
            the link relation. 
          </c>
          
          <c>mediaType</c>
          <c>MIME Media Type</c>
          <c>
            The MIME media type of the resource being referenced.
          </c>

        </texttable>

      </section>

      <section anchor="activity" title="Activity">

        <t>
          Activity objects are specializations of the base
          <xref target="object">Object</xref> type that provide
          metadata about potential or completed actions.
        </t>
        
        <t>
          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.
        </t>

        <t>
          Activity objects extend the core <xref target="object">object</xref>
          definition with the following additional, optional properties:
        </t>

        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>

          <c>verb</c>
          <c><xref target="type-value">Type value</xref></c>
          <c>
            Identifies the type of activity. An activity SHOULD contain a "verb"
            property whose value is a <xref target="type-value">Type value</xref>. 
            If the "verb" property is not specified, the activity MUST contain a 
            "objectType" property.
          </c>

          <c>actor</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            Describes one or more entities that either peformed or are 
            expected to perform the activity.
          </c>
 
          <c>object</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            Describes the primary object of the 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" property. If the "object" property is not contained, the
            primary object of the activity MAY be implied by context.
          </c>

          <c>target</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            Describes the target of 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 identity an indirect object that is
            not a target of the activity.
          </c>

          <c>result</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            Describes the result of the activity. For instance, if a particular
            action results in the creation of a new resource, the "result" 
            property can be used to describe that new resource.
          </c>
          
          <c>priority</c>
          <c>Decimal Number between 0.00 and 1.00</c>
          <c>
            An indicator of the relative priority or importance that
            the creator of an activity considers 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 0.00 represents the lowest possible
            priority while 1.00 represents the highest.
          </c>
        </texttable>
                
        <section title="Considerations on the use of &quot;priority&quot;">
          
          <t>
            The presence of the "priority" property does not impose any 
            specific processing or display requirements on the part of any 
            entity consuming the activity.
          </t>
          
          <t>
            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.
          </t>
          
          <t>
            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.
          </t>
          
        </section>
        
        <section anchor="audience-targeting" title="Audience Targeting Properties">
      
          <t>
            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").
          </t>

          <t>
            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.
          </t>

          <t>
            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.
          </t>

          <t>
            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.
          </t>
      
          <texttable>
            <ttcol align="left" width="15%">Property</ttcol>
            <ttcol align="left" width="21%">Value</ttcol>
            <ttcol align="left">Description</ttcol>

            <c>to</c>
            <c><xref target="link">Link</xref> value</c>
            <c>
              Specifies the public primary audience.
            </c>
        
            <c>cc</c>
            <c><xref target="link">Link</xref> value</c>
            <c>
              Specifies the public secondary audience.
            </c>
        
            <c>bto</c>
            <c><xref target="link">Link</xref> value</c>
            <c>
              Specifies the private primary audience.
            </c>
        
            <c>bcc</c>
            <c><xref target="link">Link</xref> value</c>
            <c>
              Specifies the private secondary audience.
            </c>
        
          </texttable>
      
          <t>
            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.
          </t>

          <t>
            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.
          </t>

          <t>
            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.
          </t>
      
          <t>
            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.
          </t>
      
        </section>

                
      </section>
      
      <section anchor="object-ext" title="Additional Object Properties">
        
        <t>
           The following "additional properties" MAY be used with any 
           JSON Object serialized within an Activity Stream document.
         </t>
        
        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>

          <c>alias</c>
          <c>IRI</c>
          <c>
            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 <xref target="RFC3987"/>. The use of a
            relative reference other than a simple name is not allowed. 
          </c>

          <c>attachments</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing one or more 
            objects associated with the containing object. These are similiar 
            in concept to files attached to an email message.
          </c>

          <c>author</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing one or more
            entity that created or authored the object.
          </c>

          <c>content</c>
          <c><xref target="lang">Natural Language value</xref></c>
          <c>
            A Natural-language description of the object encoded as a single
            JSON String containing HTML markup. Visual elements such as 
            thumbnail images MAY be included.
          </c>

          <c>duplicates</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref>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.
          </c>

          <c>icon</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> 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.
          </c>

          <c>image</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing one or more
            visual, graphic represenations of the object. Unlike the "icon"
            property, there are no aspect ratio or display restrictions.
          </c>
          
          <c>location</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value describing one or more 
            physical or virtual locations associated with which the object.
          </c>

          <c>published</c>
          <c><xref target="RFC3339"/> date-time</c>
          <c>
            The date and time at which the object was published.
          </c>

          <c>generator</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the 
            application that generated the object.
          </c>
          
          <c>provider</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the 
            application that published the object. Note that this 
            is not necessarily the same entity that generated the 
            object.
          </c>

          <c>summary</c>
          <c><xref target="lang">Natural Language value</xref></c>
          <c>
            A Natural-language summarization of the object encoded as a single
            JSON String containing a fragment of HTML markup. Visual elements 
            such as thumbnail images can be included.
          </c>

          <c>updated</c>
          <c><xref target="RFC3339"/> date-time</c>
          <c>
            The date and time at which a previously published object has
            been modified.
          </c>
          
          <c>startTime</c>
          <c><xref target="RFC3339"/> date-time</c>
          <c>
            A date-time describing the actual 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.
          </c>
          
          <c>endTime</c>
          <c><xref target="RFC3339" /> date-time</c>
          <c>
            A date-time describing the actual 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.
          </c>
          
          <c>rating</c>
          <c>Decimal Number between 1.0 and 5.0</c>
          <c>
            A quality rating expressed as a number between 1.0 and 5.0 
            (inclusive) with one decimal place of precision.  
          </c>
          
          <c>tags</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> 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". 
          </c>
          
          <c>title</c>
          <c><xref target="lang">Natural Language</xref> value</c>
          <c>
            A Natural-language title for the object expressed as a fragment 
            of HTML markup. The "title" and "displayName" properties are closely 
            related and overlap in function with the key difference being 
            that "title" is permitted to contain HTML markup, while "displayName" 
            is not.
          </c>
          
          <c>duration</c>
          <c>Integer or <xref target="RFC3339" /> duration</c>
          <c>
            When the object describes a time-based resource, such as audio 
            or 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.
          </c>

          <c>height</c>
          <c>Integer</c>
          <c>
            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.
          </c>
          
          <c>width</c>
          <c>Integer</c>
          <c>
            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.
          </c>
          
          <c>inReplyTo</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value identifying one or 
            more other objects to which the containing object can be 
            considered a response.
          </c>
          
        </texttable>
        
      </section>

      <section anchor="collection" title="Collection">

        <t>
          Collection objects are a specialization of the base
          <xref target="object">Object</xref> that contain a 
          listing of other <xref target="object">objects</xref>
          The Collection object is used primarily as the root of an
          Activity Streams document as described in <xref target="document"/>,
          but can be used as the value of object properties.
        </t>
        
        <t>
          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 <xref target="link">Link</xref>
          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".
        </t>
        
        <t>
          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.
        </t>
        
        <t>
          Collection objects extend the core <xref target="object">object</xref>
          definition with the following additional properties:
        </t>

        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>

          <c>totalItems</c>
          <c>Integer</c>
          <c>
            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.
          </c>

          <c>items</c>
          <c>
            Array of <xref target="object">Objects</xref>
          </c>
          <c>
            An array containing a listing of <xref target="object">Objects</xref> 
            of any type.
          </c>

          <c>itemsAfter</c>
          <c><xref target="RFC3339" /> date-time</c>
          <c>
            A RFC 3339 date-time that indicates that the collection contains
            only items published or updated strictly after the date and time 
            specified.
          </c>
          
          <c>itemsBefore</c>
          <c><xref target="RFC3339" /> date-time</c>
          <c>
            A RFC 3339 date-time that indicates that the collection contains
            only items published or updated strictly before the date and time 
            specified.
          </c>
          
          <c>itemsPerPage</c>
          <c>Integer</c>
          <c>
            A non-negative integer specifying the maximum number of items 
            that will be included in the value of the items array.
          </c>
          
          <c>startIndex</c>
          <c>Integer</c>
          <c>
            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.
          </c>
          
          <c>first</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the 
            furthest preceeding page of a multi-page collection.
          </c>
          
          <c>last</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the 
            furthest following page of a multi-page collection.
          </c>
          
          <c>prev</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> 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.
          </c>
          
          <c>next</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the immediately 
            following page of the multi-page collection.
          </c>      
          
          <c>current</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing the page 
            containing the items that have been updated or published most 
            recently.
          </c>    
          
          <c>self</c>
          <c><xref target="link">Link</xref> value</c>
          <c>
            A <xref target="link">Link</xref> value referencing this page.
          </c>
          
        </texttable>
        
        <section anchor="summary-properties" title="Using Collections as Summary Values">
          
          <t>
            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.
          </t>
          
          <t>
            This specification defines the following properties that 
            MAY be used within any <xref target="object">object</xref> 
            as "summary values":
          </t>
          
          <texttable>
            <ttcol align="left" width="15%">Property</ttcol>
            <ttcol align="left" width="21%">Value</ttcol>
            <ttcol align="left">Description</ttcol>
            <c>replies</c>
            <c><xref target="collection">Collection</xref></c>
            <c>
              Provides information about the set of objects that can be 
              considered to be replies to the containing object.
            </c>
          </texttable>
          
          <figure>
            <preamble>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:</preamble>
            <artwork>{
  "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."
      }
    ]
  }
}</artwork></figure>
          
        </section>

      </section>

    </section>

    <section anchor="document" title="The Activity Stream JSON Document">

      <t>
        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.
      </t>

      <t>
        Publishers using this format MUST produce a valid JSON document
        whose root value is a <xref target="collection">Collection</xref>.
      </t>
      
      <t>
        The MIME media type of this document MUST be 
        "application/activity+json".
      </t>

    </section>
    
    <section anchor="deprecated-syntax" title="Deprecated Activity Streams 1.0 Syntax">
      
      <t>
        The JSON syntax defined by this specification differs somewhat
        from that defined in the original 
        <xref target="activitystreams-1.0">JSON Activity Streams 1.0</xref> 
        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.
      </t>
      
      <t>
        Specifically:
        <list style="numbers">
          <t>
            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.
          </t>
          <t>
            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 
            <xref target="activitystreams-1.0"/>. The 2.0 syntax and 
            processing rules apply only when handling serializations 
            using the "application/activity+json" media type.
          </t>
          <t>
            This document renames the 1.0 "objectType" property to "objectType"
            to better align syntactically with JSON-LD. For backwards 
            compatibility, implementations MUST treat "objectType"
            as an alias of "objectType".
          </t>
          <t>
            This document redefines the "displayName", "title", "content" 
            and "summary" properties as <xref target="lang">Natural Language 
            values</xref>, 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.
          </t>
          <t>
            This document redefines a large number of common properties 
            defined originally as Objects in 1.0 as 
            <xref target="link">Link values</xref>. 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.
          </t>
          <t>
            This specification replaces the "upstreamDuplicates" and 
            "downstreamDuplicates" properties defined in the 1.0 syntax
            with a singular "duplicates" property with a 
            <xref target="link">Link value</xref>. 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.
          </t>
        </list>
      </t>
      
      <t>
        By following these requirements, all JSON Activity Streams 1.0
        serializations can be processed successfully by 2.0 implementations.
      </t>
      
    </section>

    <section anchor="id-comparison" title="Comparison of Identifier Values">
      <t>
        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 be based solely on the character strings themselves and MUST NOT 
        rely on dereferencing the IRIs or URIs mapped from them.
      </t>

      <t>
        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.
      </t>
    </section>
    
    <section anchor="extensions" title="Extensibility">

      <t>
        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.
      </t>

    </section>
    
    <section anchor="security" title="Security Considerations">
      <t>
        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.
      </t>

      <t>
        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.
      </t>

      <t>
        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.
      </t>

      <t>
        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.
      </t>

      <t>
        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.
      </t>

      <t>
        Activity Streams are JSON Documents and are subject to the same
        security considerations described in <xref target="RFC4627"/>.
      </t>

      <t>
        Activity Streams implementations handle URIs.  See Section 7 of
        <xref target="RFC3986"/>.
      </t>

      <t>
        Activity Streams implementations handle IRIs.  See Section 8 of
        <xref target="RFC3987"/>.
      </t>

    </section>

    <section anchor="iana" title="IANA Considerations">
      
      <section anchor="media-type" title="application/activity+xml Media Type">
        
        <t>
          This specification registers the application/activity+json 
          MIME Media Type:
        </t>

        <t><list>
        <t>Type name: application</t>
        <t>Subtype name: activity+json</t>
        <t>Required parameters: None</t>
        <t>
          Optional parameters: "charset" : Specifies the character set encoding.
          If not specified, a default of "UTF-8" is assumed.
        </t>
        <t>
          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 <xref target="RFC4627">Section 6</xref>.
        </t>
        <t>Security considerations: As defined in this specification</t>
        <t>Published specification: This specification.</t>
        <t>
          Applications that use this media type: JSON Activity Streams are implemented
          by a wide range of existing applications.
        </t>
        <t>Additional information:
        <list>
        <t>Magic number(s): N/A</t>
        <t>File extension(s): N/A</t>
        <t>Macintosh file type code(s): TEXT</t>
        </list></t>
        <t>Person &amp; email address to contact for further information: James M Snell &lt;jasnell@gmail.com&gt;</t>
        <t>Intended usage: COMMON</t>
        <t>Restrictions on usage: None.</t>
        <t>Author: James M Snell &lt;jasnell@gmail.com&gt;</t>
        <t>Change controller: IESG</t>
        </list></t>
        
      </section>

    </section>

  </middle>

  <back>
    <references title="Normative References">      
      &rfc2119;
      &rfc3986;
      &rfc3987;
      &rfc4627;
      &rfc3339;
      &rfc5988;   
      &rfc5646;  
      &jsonld; 
      
      <reference anchor="activitystreams-1.0">
        <front>
          <title abbrev="ActivityStreams">JSON Activity Streams 1.0</title>

          <author fullname="James M Snell" initials="J.M." surname="Snell">
            <organization>IBM</organization>
          </author>

          <author fullname="Martin Atkins" initials="M." surname="Atkins">
            <organization>SAY Media</organization>
          </author>

          <author fullname="Will Norris" initials="W." surname="Norris">
            <organization>Google</organization>
          </author>

          <author fullname="Chris Messina" initials="C." surname="Messina">
            <organization>Citizen Agency, Google</organization>
          </author>

          <author fullname="Monica Wilkinson" initials="M." surname="Wilkinson">
            <organization>MySpace, Facebook, VMware</organization>
          </author>

          <author fullname="Rob Dolin" initials="R." surname="Dolin">
            <organization>Microsoft</organization>
          </author>

          <date month="May" year="2011" />

          <abstract>
            <t>This specification details the serialization of a stream of social
              activities using the JSON format. Activities are important in that
              they allow individuals to process the latest news of people and things
              they care about.</t>
          </abstract>

        </front>
      </reference>
      
    </references>
    <references title="Informational References">
      &rfc6963;
    </references>

    <section anchor="acknowledgements" title="Acknowledgements">
      <t>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 hÓra, 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 Engeström, Kaliya Hamlin, Kevin Marks, Laurent Eschenauer,
      Laurie Voss, Leah Culver, Libby Miller, Manu Mukerji, Mark Weitzel, Marko
      Degenkolb, Marshall Kirkpatrick, Martin Atkins, Martin Svensson, Marty Alchin, Mary
      Hoder, Matt Leventi, Matt Wilkinson, Matthias Müller-Prove, Max Engel, Max
      Wegmueller, Melvin Carvalho, Michael Buckbee, Michael Chan, Michael
      Richardson, Michael Sullivan, Mike Macgirvin, Mislav Marohnić, Mo Jangda,
      Monica Wilkinson, Nate Benes, NeilFred Picciotto, Nick Howard, Nick Lothian, Nissan
      Dookeran, Nitya Narasimhan, Pablo Martin, Pádraic 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 Çelik, Tatu
      Saloranta, Tim Moore, Timothy Young, Todd Barnard, Tosh Meston, Tyler
      Gillies, Will Norris, Zach Copley, and Zach Shepherd.</t>
    </section>
  
    <section anchor="Appendix-A" title="Processing as JSON-LD">
      
      <t>
        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.
      </t>
      
      <figure><artwork>
  {
    "@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"
    }
  }
      </artwork></figure> 

    </section>
    
    <section anchor="Appendix-B" title="Motivational Use Cases">
      
      <t>
        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.
      </t>
      
      <section title="Internationalization (i18n)">
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
        <t>
          For instance, let's suppose that our native French speaker posts
          the following activity to this system:
        </t>
        
        <figure><artwork><![CDATA[
  POST /activity/feed HTTP/1.1
  Content-Type: application/activity+xml
  
  {
    "verb": "post",
    "language": "fr",
    "object": {
      "objectType": "article",
      "displayName": "Un exemple basique",
      ...
    }
  }
        ]]></artwork></figure>
        
        <t>
          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.
        </t>
        
        <figure><artwork><![CDATA[
  {
    "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"
      }
      ...
    }
  }
        ]]></artwork></figure>
  
      </section>
  
      <section title="Extensibility (e11y)">
        
        <t>
          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.
        </t>
        
        <t>
          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. 
        </t>
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
        <figure><artwork><![CDATA[
  {
    "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"
    }
  }
        ]]></artwork></figure>
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
      </section>
      
      <section title="First Class Links">
        
        <t>
          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.
        </t>
        
        <t>
          For instance, using the 2.0 syntax, an "image" object type can
          be represented simply as:
        </t>
        
        <figure><artwork><![CDATA[
  {
    "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"
  }
        ]]></artwork></figure>
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
        <figure><artwork><![CDATA[
  {
    "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"
    ]
  }  
        ]]></artwork></figure>
              
      </section>
      
      <section title="Use of External Vocabularies">
        
        <t>
          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).
        </t>
        
        <t>
          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.
        </t>
        
        <t>
          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.
        </t>
        
        <t>
          Using JSON-LD I can maintain basic Activity Streams 2.0 syntax 
          while mapping the physical serialization to the abstract model
          inline.
        </t>
        
        <figure><artwork><![CDATA[
  {
    "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"
    }
  }  
        ]]></artwork></figure>
        
        <t>
          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 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.
        </t>
        
      </section>
      
    </section>
    
  </back>
</rfc>