TOC 
Activity Streams Working GroupJ. Snell
 IBM
 March 6, 2012


Audience Targeting for JSON Activity Streams

Abstract

This specification details an extension to the JSON Activity Streams serialization to support explicit identification of the audience for a specific activity.



Table of Contents

1.  Introduction
2.  Notational Conventions
3.  Targeting Properties
    3.1.  Public and Private Audiences
4.  The "alias" Object Property
5.  Security Considerations
6.  License
7.  Normative References
§  Author's Address




 TOC 

1.  Introduction

The Activity Streams specification defines a format for describing socially interesting events, or "Activities", about the people and things an individual may care about.

Every Activity has both a Primary and Secondary audience. The Primary audience consists of those entities either directly involved in the performance of the activity or who "own" the objects involved. The Secondary audience consists of the collection of entities sharing an interest in the activity but who are not directly involved (e.g. "followers").

For instance, suppose a social network of three individuals: Bob, Joe and Jane. Bob and Joe are each friends with Jane but not friends with one another. Bob has chosen to "follow" activities for which Jane is directly involved. Jane shares a file with Joe.

In this example, Jane and Joe are each directly involved in the file sharing activity and together make up the Primary Audience for that event. Bob, having an interest in activities involving Jane, is the Secondary Audience. Knowing this, a system that produces or consumes the activity can more intelligently notify each of the users of the event.

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



 TOC 

2.  Notational Conventions

The text of this specification provides the sole definition of conformance. Examples in this specification are non-normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).



 TOC 

3.  Targeting Properties

The to, cc, bto and bcc 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.

PropertyValueDescription
to  JSON Array of Activity Stream Objects Specifies the public primary audience of an activity.
cc  JSON Array of Activity Stream Objects Specifies the public secondary audience of an activity.
bto  JSON Array of Activity Stream Objects Specifies the private primary audience of an activity.
bcc  JSON Array of Activity Stream Objects Specifies the private secondary audience of an activity.

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.



 TOC 

3.1.  Public and Private Audiences

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.

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

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

The following example illustrates the expected behavior of an intermediary redistributing an activity that has both a public and private audience:

First, the event source generates an activity that is published to the intermediary.

  {
    "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":{
      ...
    }
  }

Upon receiving the activity, the intermediary would generate a modified copy of the activity, omitting the bto and bcc values, and display that to each of the four entities identified.

  {
    "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":{
      ...
    }
  }

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.



 TOC 

4.  The "alias" Object Property

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.

The value of the "alias" property MUST be a non-empty string that matches either the "isegment-nz-nc" or "IRI" productions defined in [RFC3987] (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.). Note that the use of relative references other than a simple name is not allowed.

The following example shows an activity targeted at a group object aliased as "@friends":

  {
    "to":[
      {"objectType":"group",
       "alias":"@friends"}
    ],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }

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.

The following example shows an activity targeted at a group object aliased using a fully-qualified IRI:

  {
    "to":[
      {"objectType":"group",
       "alias":"http://example.org/api/people/@me/@friends"}
    ],
    "verb":"post",
    "actor":{
      "objectType":"person",
      "id":"acct:jane@example.org"},
    "object":{
      ...
    }
  }


 TOC 

5.  Security Considerations

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 bto and bcc 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.



 TOC 

6.  License

This Specification is made available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/.

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.

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.



 TOC 

7. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3987] Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” RFC 3987, January 2005 (TXT).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[json-activity-streams-01] Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.


 TOC 

Author's Address

  James M Snell
  IBM