activity-streams-replies.xml

<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?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 private="Activity Streams Working Group"?>
<rfc>
  <front>
    <title abbrev="ActivityStreams">Responses for Activity Streams</title>

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

    <date month="March" year="2012" />

    <abstract>
      <t>This specification details an extension to the JSON Activity Streams
      to express the serialization of responses and reactions to an Activity or
      an Object.</t>
    </abstract>

  </front>

  <middle>
    <section title="Introduction">
      <t>The Activity Streams specification defines a format for describing
      socially interesting events, or "Activities", about the people and things 
      an individual may care about. This specification describes the mechanisms
      by which responses or reactions to those events or their related objects
       may also be described.</t>
      
      <t>The possible range of reactions to an event or object vary broadly 
      and include such actions as posting a comment, sharing the event with 
      others, "liking" or "favoriting" the event or object, RSVP'ing to an
      event invite and so on. This specification does not attempt to cover 
      the full range of possible reactions. Rather, it seeks to establish a
      common pattern for the expression of those reactions within an Activity
      Stream and defines a set of extension properties exemplifying that 
      pattern.</t>
      
    </section>

    <section title="Notational Conventions">
      <t>The text of this specification provides the sole definition of
      conformance. Examples in this specification are non-normative.</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>
    
    <section anchor="inreplyto" title="The &quot;inReplyTo&quot; Property">
      <t>The <spanx style="verb">inReplyTo</spanx> property MAY be used within any Activity Stream 
      object to identify other objects for which the containing object is
      considered a response. The value of the <spanx style="verb">inReplyTo</spanx>
      property is a <xref target="RFC4627">JSON</xref> Array of 
      Activity Stream Objects. For example:</t>    
      
<figure><artwork><![CDATA[
  {
    "objectType": "comment",
    "content": "<p>This is a comment</p>",
    "inReplyTo": [
      {
        "objectType": "note",
        "id": "http://example.org/objects/123",
        "displayName": "A simple note"
      }
    ]
  }
]]></artwork></figure>
          
       <t>In many cases, such as when an object appears as a member of a collection
       of objects in a property that clearly indicates a response or reaction 
       relationship with a parent object, the <spanx style="verb">inReplyTo</spanx>
       property can be implied. For instance, the <spanx style="verb">replies</spanx>
       property defined below in <xref target="stream" /> may contain a listing
       of child objects with an implied <spanx style="verb">inReplyTo</spanx> 
       property referring to the parent object.</t>
          
    </section> 

    <section anchor="stream" title="Responses and Activity Summaries">
    
      <t>It is common practice to provide summary information on the number 
      and types of activities that have occurred with respect to a given 
      object. For instance, a "note" object may have been the target of 
      any number of comment, like, or share activities. This summary information 
      MAY be expressed in the JSON serialization of an object by using a property
      name descriptive of the data being summarized and using the Collection
      object as defined by <xref target="json-activity-streams-01">JSON Activity Streams</xref>.</t>
      
      <t>The following properties MAY be used on any object type or activity 
      for each of the specified situations:</t>
      
      <texttable>
        <ttcol align="left" width="15%">Property</ttcol>
        <ttcol align="left">Description</ttcol>
        
        <c><spanx style="verb">attending</spanx></c>
        <c>Used to provide information about the collection of actors that 
        have responded to an <spanx style="verb">event</spanx> using the 
        <spanx style="verb">rsvp-yes</spanx> verb.</c>
        
        <c><spanx style="verb">followers</spanx></c>
        <c>Used to provide information about the collection of objects (typically
        person objects) that are "following" the containing object.</c>
        
        <c><spanx style="verb">following</spanx></c>
        <c>Used to provide information about the collection of objects that this 
        object is "following".</c>
        
        <c><spanx style="verb">friends</spanx></c>
        <c>Used to provide information about the collection of objects with which
        a "friendship" relationship has been established using the <spanx style="verb">make-friend</spanx>
        verb. This property will typically only be relevant for the <spanx style="verb">person</spanx> object type.</c>
        
        <c><spanx style="verb">friend-requests</spanx></c>
        <c>Used to provide information about the collection of objects with which
        a "friendship" relationship is being requested using the <spanx style="verb">request-friend</spanx>
        verb. This property will typically only be relevant for the <spanx style="verb">person</spanx> object type.</c>
        
        <c><spanx style="verb">likes</spanx></c>
        <c>Used to provide information about the actors (typically person 
        objects) that have favorited or liked the containing object.</c>
        
        <c><spanx style="verb">notAttending</spanx></c>
        <c>Used to provide information about the collection of actors that 
        have responded to an <spanx style="verb">event</spanx> using the 
        <spanx style="verb">rsvp-no</spanx> verb.</c>
        
        <c><spanx style="verb">maybeAttending</spanx></c>
        <c>Used to provide information about the collection of actors that 
        have responded to an <spanx style="verb">event</spanx> using the 
        <spanx style="verb">rsvp-maybe</spanx> verb.</c>
        
        <c><spanx style="verb">members</spanx></c>
        <c>Used to provide information about the actors (typically person 
        objects) that have "joined" the containing object. This is typically
        only useful for object types that represent groups.</c>
        
        <c><spanx style="verb">replies</spanx></c>
        <c>Used to provide information about the thread of discussion associated
        with a given object. Typically, the objects contained will have an 
        implied <spanx style="verb">inReplyTo</spanx> property value equal to
        the object containing the <spanx style="verb">replies</spanx> property.</c>
        
        <c><spanx style="verb">reviews</spanx></c>
        <c>Used to provide information about reviews available for the containing 
        object.</c>
        
        <c><spanx style="verb">saves</spanx></c>
        <c>Used to provide information about the actors (typically person 
        objects) that have "saved" the containing object.</c>
        
        <c><spanx style="verb">shares</spanx></c>
        <c>Used to provide information about the actors (typically person 
        objects) that have "shared" the containing object.</c>      
      </texttable>
    
      <t>The following example illustrates the use of these 
      properties. Note that the value of the <spanx style="verb">totalItems</spanx>
      property indicates the total number of items in the associated 
      collections and may not match the actual number of objects in the 
      <spanx style="verb">items</spanx> property. For instance, in the example
      below, for the <spanx style="verb">likes</spanx> property, the 
      <spanx style="verb">totalItems</spanx> property specifies the value 120 but
      includes only a single object. This SHOULD be interpreted along the 
      lines of "John and 119 other users like this note".</t>
      
<figure><artwork><![CDATA[
  {
    "objectType": "note",
    "displayName": "A Simple Note",
    "content": "<p>This is a simple note</p>",
    "replies": {
      "totalItems": 10,
      "url": "http://example.org/comments-stream",
    },
    "followers": {
      "totalItems": 15,
      "url": "http://example.org/followers-stream",
      "items": [
        {
          "objectType": "person",
          "displayName": "Jane"
        }
      ]
    },
    "likes": {
      "totalItems": 120,
      "items": [
        {
          "objectType": "person",
          "displayName": "John"
        }
      ]
    },
    "reviews": {
      "totalItems": 1,
      "items": [
        {
          "objectType": "review",
          "author": {
            "displayName": "Joe",
            "objectType": "person"
          },
          "rating": 4.5
        }
      ]
    }
  }
]]></artwork></figure>
    
    </section>

    <section title="Security Considerations">
      <t>The mechanisms defined herein are subject to the same security considerations
      as all activities. Applications must be aware of the risk posed by a 
      malicious third party attempting to artificially inject inappropriate 
      content into the stream of responses and replies of an object. For instance, 
      services that aggregate activity streams from multiple sources and attempt
      to reconstruct a thread of discussion using replies and response from across
      those sources could be tricked into displaying illegitimate content if 
      appropriate consideration is not given to the content origin. Mitigation 
      of such threats is considered out of scope for this specification.</t>     
    </section>

    <section title="License">
    
      <t>This Specification is made available under the Open Web 
      Foundation Agreement Version 1.0, which is available at 
      http://www.openwebfoundation.org/legal/.</t>

      <t>You can review the signed copies of the Open Web Foundation 
      Agreement Version 1.0 for this Specification at 
      http://activitystrea.ms/licensing/, which may also include additional 
      parties to the authors.</t>

      <t>Your use of this Specification may be subject to other third party 
      rights. THIS SPECIFICATION IS PROVIDED "AS IS." The contributors 
      expressly disclaim any warranties (express, implied, or otherwise), 
      including implied warranties of merchantability, non-infringement, 
      fitness for a particular purpose, or title, related to the Specification. 
      The entire risk as to implementing or otherwise using the Specification 
      is assumed by the Specification implementer and user. IN NO EVENT WILL 
      ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF 
      INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER 
      FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS SPECIFICATION 
      OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT 
      (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY 
      HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</t>
    
    </section>

  </middle>

  <back>
    <references title="Normative References">
<reference anchor="RFC2119">
        <front>
          <title>Key words for use in RFCs to Indicate Requirement
          Levels</title>

          <author fullname="Scott Bradner" initials="S." surname="Bradner">
            <organization></organization>
          </author>

          <date month="March" year="1997" />
        </front>
      </reference>
      <reference anchor="json-activity-streams-01" 
        target="http://activitystrea.ms/specs/json/1.0/">      
         <front>
            <title>JSON Activity Streams 1.0</title>
            
            <author fullname="James Snell" initials="J.M." surname="Snell">
              <organization>IBM</organization>
            </author>
            
            <author fullname="Martin Atkins" initials="M." surname="Atkins">
              <organization>Six Apart</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, Socialcast</organization>
            </author>

            <author fullname="Rob Dolin" initials="R." surname="Dolin">
              <organization>Microsoft</organization>
            </author>
            
            <date month="May" year="2011" />
          </front>
      </reference>

      <reference anchor="RFC4627">
        <front>
          <title>The application/json Media Type for JavaScript Object
          Notation (JSON)</title>

          <author fullname="Douglas Crockford" initials="D."
                  surname="Crockford">
            <organization>JSON.org</organization>
          </author>

          <date month="July" year="2006" />
        </front>
      </reference>
      </references>
  </back>
</rfc>