activity-streams-target.xml

<?xml version="1.0" encoding="US-ASCII"?>
<?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 rfc4627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.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 private="Activity Streams Working Group"?>
<rfc>
  <front>
    <title abbrev="ActivityStreams">Audience Targeting for JSON 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 serialization to support explicit identification of 
      the audience for a specific activity.</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.</t>
      
      <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 more intelligently notify each of the users
      of the event.</t>
      
      <t>The core Activity Streams specification does not define a means of 
      explicitly identifying the Primary or Secondary audience for an event. 
      There are means, based on the verb, actor, object and target of the 
      activity, to infer the primary audience for many types of activities,
      but not all. This specification introduces four optional extension 
      properties for an Activity to explicitly describe the Primary and
      Secondary audience. An activity utilizing these extension properties 
      is hereafter referred to as a "Targeted Activity".</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="properties" title="Targeting Properties">
        
        <t>The <spanx style="verb">to</spanx>, <spanx style="verb">cc</spanx>, 
        <spanx style="verb">bto</spanx> and <spanx style="verb">bcc</spanx> 
        properties MAY be used within an Activity to identify the Primary and 
        Secondary audiences. The value of each of these properties when 
        serialized using the JSON format is an array of Objects. The objects 
        can be of any objectType but will typically represent individuals or 
        groups of individuals.</t>
        
        <texttable>
          <ttcol align="left" width="15%">Property</ttcol>
          <ttcol align="left" width="21%">Value</ttcol>
          <ttcol align="left">Description</ttcol>

          <c><spanx style="verb">to</spanx></c>
          <c>JSON Array of Activity Stream Objects</c>
          <c>Specifies the public primary audience of an activity.</c>

          <c><spanx style="verb">cc</spanx></c>
          <c>JSON Array of Activity Stream Objects</c>
          <c>Specifies the public secondary audience of an activity.</c>
          
          <c><spanx style="verb">bto</spanx></c>
          <c>JSON Array of Activity Stream Objects</c>
          <c>Specifies the private primary audience of an activity.</c>  
          
          <c><spanx style="verb">bcc</spanx></c>
          <c>JSON Array of Activity Stream Objects</c>
          <c>Specifies the private secondary audience of an activity.</c>                             
                                       
        </texttable>          
        
        <t>This specification places no restrictions on the types
        of objects that can be used within the values for each of these
        properties. This means that any type of object, not only those 
        representing individual people or groups, can be included within 
        the target audience for an Activity.</t>
        
        <section anchor="cc-bcc" title="Public and Private Audiences">
        
          <t>The prototypical use case for a Targeted Activity is the 
          publication and redistribution of Activities through an intermediary.
          An event source generates the activity and publishes it to the 
          intermediary which determines the 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 <spanx style="verb">to</spanx> and <spanx style="verb">cc</spanx> 
          fields, the intermediary SHOULD redistribute
          that event with the values of those fields intact, allowing any 
          entity receiving and processing that entity 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 <spanx style="verb">bto</spanx> and 
          <spanx style="verb">bcc</spanx> properties to list entities to whom the activity should be 
          privately targeted. When the intermediary receives an activity 
          containing these properties, it MUST remove their values prior to 
          redistributing the activity. The intermediary MAY insert new "bto" 
          and "bcc" property values containing empty arrays as an indication 
          that a private audience exists without disclosing the specific 
          individual members of that private audience.</t>
          
          <t>The following example illustrates the expected behavior of 
          an intermediary redistributing an activity that has both a 
          public and private audience:</t>
        
          <t>First, the event source generates an activity that is published
          to the intermediary.</t>
<figure><artwork><![CDATA[
  {
    "to":[
      {"objectType":"person",
       "id":"acct:jane@example.org"}
    ],
    "bto":[
      {"objectType":"person",
       "id":"tag:example.org,2011/12/11:joe"}
    ],
    "cc":[
      {"objectType":"person",
       "id":"http://example.com/profiles/bob"}
    ],
    "bcc":[
      {"objectType":"person",
       "id":"tag:example.org,2011:lisa"}
    ],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }
]]></artwork></figure>
        
        <t>Upon receiving the activity, the intermediary would generate a
        modified copy of the activity, omitting the <spanx style="verb">bto</spanx> 
        and <spanx style="verb">bcc</spanx> values, 
        and display that to each of the four entities identified.</t>
       
<figure><artwork><![CDATA[
  {
    "to":[
      {"objectType":"person",
       "id":"acct:jane@example.org"}
    ],
    "cc":[
      {"objectType":"person",
       "id":"http://example.com/profiles/bob"}
    ],
    "bto":[],
    "bcc":[],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }
]]></artwork></figure> 

      <t>Implementations are free to use what they know about an activity's 
      primary and secondary audiences to determine access, change and redistribution
      controls for the activity (e.g. limiting who is able to see the activity). However,
      the mere presence of targeting properties does not imply that distribution 
      of the activity is limited to only explicitly targeted entities.
      Audience targeting information included within an Activity
      using these mechanisms is intended only to express the intent of the 
      entity creating the activity. With clear exception given to the 
      appropriate handling of "bto" and "bcc", this specification leaves it 
      up to individual implementations to determine how the audience targeting
      information is to be utilized. Further, in the absence of any targeting
      information within an Activity, this specification does not define any
      default primary or secondary audience. The selection of default primary or
      secondary audiences is solely at the discretion of the implementation.</t>
        
        </section>
        
    </section> 

    <section title="The &quot;alias&quot; Object Property">
    
      <t>Within Activity Streams objects, the value of the "alias" property 
      serves as an alternative meaningful label for the object in addition to 
      the "id". For instance, within some systems, groups can be identified by 
      both a unique global ID and a more friendly label such as "@friends" or 
      "@network", etc. In some systems, the alias can be used as an alternative 
      to the "id" in certain situations.</t>
      
      <t>The value of the "alias" property MUST be a non-empty string that 
      matches either the "isegment-nz-nc" or "IRI" productions defined in
      <xref target="RFC3987"/>. Note that the use of relative references 
      other than a simple name is not allowed.</t>

      <figure><preamble>The following example shows an activity targeted at a group object 
      aliased as "@friends":</preamble><artwork>
  {
    "to":[
      {"objectType":"group",
       "alias":"@friends"}
    ],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }
      </artwork></figure>
      
      <t>Note that the use of simple alias values is intentionally ambiguous and
      that such aliases are only meaningful within specific limited application
      contexts. For instance, two separate systems may each interpret the "@friends"
      alias in distinctly different ways. It is recommended that use of such simple aliases 
      be limited to communication between parties that share a common understanding 
      of their meaning and interpretation.</t>
     
      <figure><preamble>The following example shows an activity targeted at a group object 
      aliased using a fully-qualified IRI:</preamble><artwork>
  {
    "to":[
      {"objectType":"group",
       "alias":"http://example.org/api/people/@me/@friends"}
    ],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }
      </artwork></figure>
      
    </section>

    <section title="Security Considerations">
      <t>Targeted Activities are subject to the same security considerations
      as all activities. Applications publishing targeted activities to 
      untrusted intermediaries must be aware of the risk that the intermediary 
      may not properly handle (intentionally or unintentionally) 
      the <spanx style="verb">bto</spanx> and 
      <spanx style="verb">bcc</spanx> properties leading to inappropriate 
      disclosure of a target's private audience. Intermediaries and consumers
      of targeted activities must be aware of the potential for spoofing 
      and phishing attacks caused by inappropriately or maliciously targeted
      activities.</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">
      &rfc2119;
      &rfc3987;
      &rfc4627;
      <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>
      </references>

  </back>
</rfc>