Skip to main content

JSON Activity Streams 2.0 - Action Handlers
draft-snell-activitystreams-actions-01

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Authors James M. Snell , Matthew Marum
Last updated 2013-12-13
RFC stream (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-snell-activitystreams-actions-01
Activity Streams (http://activitystrea.ms)                      J. Snell
Internet-Draft                                                       IBM
Intended status: Standards Track                                M. Marum
Expires: June 16, 2014                                          SugarCRM
                                                       December 13, 2013

              JSON Activity Streams 2.0 - Action Handlers
                 draft-snell-activitystreams-actions-01

Abstract

   This specification defines Action Handlers for use with the Activity
   Streams 2.0 format.

Author's Note

   Note that this document is a work-in-progress draft specification
   that does not yet represent a "standard".  It is the intention of
   this specification to propose a few new ideas and openly solicit
   feedback on their definition and use.  While this document might
   eventually evolve into an RFC the ideas described herein have not yet
   been broadly implemented and have definitions that will evolve
   through successive iterations of this draft.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on June 16, 2014.

Copyright Notice

   Copyright (c) 2013 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Snell & Marum            Expires June 16, 2014                  [Page 1]
Internet-Draft              ActivityStreams                December 2013

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Common Action Handler Properties  . . . . . . . . . . . . . .   2
   3.  HTTP Action Handler . . . . . . . . . . . . . . . . . . . . .   3
   4.  Embed Action Handler  . . . . . . . . . . . . . . . . . . . .   6
   5.  Intent Action Handler . . . . . . . . . . . . . . . . . . . .   8
   6.  HTML Form Objects . . . . . . . . . . . . . . . . . . . . . .   9
   7.  URL Template Objects  . . . . . . . . . . . . . . . . . . . .  10
   8.  Parameters Object . . . . . . . . . . . . . . . . . . . . . .  10
   9.  Styles Object . . . . . . . . . . . . . . . . . . . . . . . .  11
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  13
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  13
   12. Normative References  . . . . . . . . . . . . . . . . . . . .  13
   Appendix A.  Using Action Handlers From Other Vocabularies  . . .  13
     A.1.  Schema.org Actions Proposal . . . . . . . . . . . . . . .  13
     A.2.  Google's "Actions in the Inbox" . . . . . . . . . . . . .  14
     A.3.  Mixing Vocabularies . . . . . . . . . . . . . . . . . . .  14
     A.4.  Example Drawing From Multiple Vocabularies  . . . . . . .  15
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  17

1.  Overview

   The Activity Streams 2.0 [I-D.snell-activitystreams] specification
   introduces the notion of "actions" that can be associated with
   objects.  Using the "actions" property described in Sections 3.6 and
   3.6.1 of the Activity Streams 2.0 document, the producer of an object
   can declare a specific set of verbs appropriate for the object and
   map each of those to one or more objects or resources capable of
   "carrying out" the verb.  This document expands on that mechanism by
   defining and describing a core set of "Action Handler" object types.

   TODO: Expand on this.

2.  Common Action Handler Properties

   Common base properties available for all Action Handler objects:

Snell & Marum            Expires June 16, 2014                  [Page 2]
Internet-Draft              ActivityStreams                December 2013

   +-----------+-----------------------------+-------------------------+
   | Property  | Value                       | Description             |
   +-----------+-----------------------------+-------------------------+
   | confirm   | Boolean                     | Optional. True if       |
   |           |                             | confirmation is         |
   |           |                             | required before the     |
   |           |                             | action is carried out.  |
   | context   | JSON Object                 | Contextual information  |
   |           |                             | associated with the     |
   |           |                             | action handler,         |
   |           |                             | represented as a JSON   |
   |           |                             | Object with no          |
   |           |                             | particular structure.   |
   |           |                             | How the context is used |
   |           |                             | is dependent entirely   |
   |           |                             | on the action handler   |
   |           |                             | definition and on how   |
   |           |                             | an application chooses  |
   |           |                             | to implement the Action |
   |           |                             | Handler.                |
   | expects   | Type Value [I-D.snell-      | For action handlers     |
   |           | activitystreams]            | with a distinct input   |
   |           |                             | requirement (e.g.       |
   |           |                             | HttpActionHandler), the |
   |           |                             | expects property        |
   |           |                             | provides a description  |
   |           |                             | of the expected input.  |
   | returns   | Type Value [I-D.snell-      | For action handlers     |
   |           | activitystreams]            | with a distinct output, |
   |           |                             | the returns property    |
   |           |                             | provides a description  |
   |           |                             | of the expected output. |
   +-----------+-----------------------------+-------------------------+

3.  HTTP Action Handler

   +-------------+-------------------------+---------------------------+
   | Property    | Value                   | Description               |
   +-------------+-------------------------+---------------------------+
   | url         | Link Value              | Required.                 |
   | method      | HTTP Method String      | Optional. Defaults to     |
   |             | (e.g. "GET", "POST",    | "GET"                     |
   |             | "PUT", etc)             |                           |
   | objectType  | "HttpActionHandler"     |                           |
   | target      | "DEFAULT", "NONE",      | Optional. Specifies the   |
   |             | "NEW", "CURRENT", or    | intended target of the    |
   |             | other token value       | HTTP action.  This        |

Snell & Marum            Expires June 16, 2014                  [Page 3]
Internet-Draft              ActivityStreams                December 2013

   |             |                         | determines whether the    |
   |             |                         | action results in a new   |
   |             |                         | navigation context (e.g.  |
   |             |                         | new browser window) or    |
   |             |                         | whether the action is     |
   |             |                         | "hidden". Defaults to     |
   |             |                         | "DEFAULT".                |
   +-------------+-------------------------+---------------------------+

   Example:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "HttpActionHandler",
         "url": "http://example.org/foo",
         "method": "GET"
       }
     }
   }

   Equivalent:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": "http://example.org/foo"
     }
   }

   "GET" HttpActionHandler using a URL Template:

Snell & Marum            Expires June 16, 2014                  [Page 4]
Internet-Draft              ActivityStreams                December 2013

   {
     "objectType": "note",
     ...,
     "actions": {
       "review": {
         "objectType": "HttpActionHandler",
         "url": {
           "objectType": "UrlTemplate",
           "template": "http://example.org/note/123{?rating}",
           "parameters": {
             "rating": {
               "id": "http://schema.org/ratingValue",
               "displayName": "Rating",
               "bestRating": 5,
               "worstRating": 1
             }
           }
         },
         "method": "GET",
         "target": "NEW"
       }
     }
   }

   "GET" HttpActionHandler shortcut using a URL Template:

   {
     "objectType": "note",
     ...,
     "actions": {
       "review": {
         "objectType": "UrlTemplate",
         "template": "http://example.org/note/123{?rating}",
         "parameters": {
           "rating": {
             "id": "http://schema.org/ratingValue",
             "displayName": "Rating",
             "bestRating": 5,
             "worstRating": 1
           }
         }
       }
     }
   }

Snell & Marum            Expires June 16, 2014                  [Page 5]
Internet-Draft              ActivityStreams                December 2013

4.  Embed Action Handler

   +--------------+--------------------------+-------------------------+
   | Property     | Value                    | Description             |
   +--------------+--------------------------+-------------------------+
   | url          | Link Value               | Required if "content"   |
   |              |                          | is not specified. URL   |
   |              |                          | from which to retrieve  |
   |              |                          | the content for this    |
   |              |                          | embed.                  |
   | content      | String                   | Required if "url" is    |
   |              |                          | not specified. Textual  |
   |              |                          | content for this embed. |
   | mediaType    | MIME Media Type          | The MIME Media Type of  |
   |              |                          | the embedded content.   |
   | style        | Styles Object (Section   | Optional CSS Styling    |
   |              | 9)                       | hints to apply to the   |
   |              |                          | element containing the  |
   |              |                          | embedded content.       |
   | preview      | Link Value               | Optional                |
   | objectType   | "EmbedActionHandler"     |                         |
   | target       | "DEFAULT", "INLINE" or   |                         |
   |              | other                    |                         |
   +--------------+--------------------------+-------------------------+

   Example:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "content": "<div>This is some bit of embedded HTML</div>",
         "mediaType": "text/html",
         "style": {
           "height": "100px",
           "width": "100px",
           "box-shadow": "10px 10px 5px #888888"
         },
         "displayName": "Some embedded content",
         "preview": "http://example.org/preview/123.jpg"
       }
     }
   }

Snell & Marum            Expires June 16, 2014                  [Page 6]
Internet-Draft              ActivityStreams                December 2013

   Example:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "url": "http://example.org/foo",
         "mediaType": "text/html"
       }
     }
   }

   Example:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "url": "http://example.org/foo.mpg",
         "mediaType": "video/mpeg"
       }
     }
   }

   Example:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "content": "This is a pretty useless action handler",
         "mediaType": "text/plain"
       }
     }
   }

   Example:

Snell & Marum            Expires June 16, 2014                  [Page 7]
Internet-Draft              ActivityStreams                December 2013

   {
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "mediaType": "application/vnd.opensocial.gadget+xml",
         "url": "http://example.org/gadget-spec.xml",
         "context": {
           "foo": 123,
           "bar": "ABC"
         }
       }
     }
   }

5.  Intent Action Handler

           +------------+-----------------------+-------------+
           | Property   | Value                 | Description |
           +------------+-----------------------+-------------+
           | url        | Link Value            | Optiona     |
           | objectType | "IntentActionHandler" |             |
           +------------+-----------------------+-------------+

   {
     "objectType": "note",
     ...,
     "actions": {
       "share": {
         "objectType": "IntentActionHandler",
         "displayName": "Share This",
         "context": {
           "foo": "ABC",
           "bar": 123
         }
       }
     }
   }

   Targeting a specific application:

Snell & Marum            Expires June 16, 2014                  [Page 8]
Internet-Draft              ActivityStreams                December 2013

   {
     "objectType": "note",
     ...,
     "actions": {
       "share": {
         "objectType": "IntentActionHandler",
         "displayName": "Share This",
         "url": "app://com.example.mysharingapp",
         "context": {
           "foo": "ABC",
           "bar": 123
         }
       }
     }
   }

6.  HTML Form Objects

       +------------+-------------------------------+-------------+
       | Property   | Value                         | Description |
       +------------+-------------------------------+-------------+
       | mediaType  | MIME Media Type               |             |
       | parameters | Parameters Object (Section 8) |             |
       +------------+-------------------------------+-------------+

   {
     "objectType": "note",
     ...,
     "actions": {
       "review": {
         "objectType": "HttpActionHandler",
         "method": "POST",
         "url": "http://example.org/foo",
         "expects": {
           "objectType": "HtmlForm",
           "mediaType": "application/x-www-form-urlencoded",
           "parameters": {
             "foo": {
               "displayName": "Foo",
               "id": "http://example.org/FooProperty",
               "required": True
             },
             "bar": {
               "displayName": "Bar",
               "id": "http://example.org/BarProperty",
               "required": True,

Snell & Marum            Expires June 16, 2014                  [Page 9]
Internet-Draft              ActivityStreams                December 2013

               "value": "Provided Value"
             }
           }
         }
       }
     }
   }

7.  URL Template Objects

   Objects with the "UrlTemplate" object type represent [RFC6570] URL
   Templates.

       +------------+-------------------------------+-------------+
       | Property   | Value                         | Description |
       +------------+-------------------------------+-------------+
       | template   | URL Template                  |             |
       | parameters | Parameters Object (Section 8) |             |
       +------------+-------------------------------+-------------+

   {
     "objectType": "note",
     ...,
     "actions": {
       "review": {
         "objectType": "UrlTemplate",
         "template": "http://example.org/foo/123{?rating}",
         "parameters": {
           "rating": {
             "displayName": "Rating",
             "id": "http://example.org/RatingProperty",
             "required": True
           }
         }
       }
     }
   }

8.  Parameters Object

   A Parameters Object is used to provide descriptions of the variable
   inputs of objects such as HTML Forms (Section 6) and URL Templates
   (Section 7).  The object is expressed as a JSON dictionary mapping
   parameter names to Type Values [I-D.snell-activitystreams] describing
   the parameters.

Snell & Marum            Expires June 16, 2014                 [Page 10]
Internet-Draft              ActivityStreams                December 2013

   By default, all parameters defined within the object are assumed to
   be required.  When a parameter is described using an Object, the
   object MAY contained a boolean "required" member.  If "required" is
   false, use of the parameter is assumed to be optional.

   Using the Parameters Object in UrlTemplate objects:

   {
     "objectType": "UrlTemplate",
     "template": "http://example.org{/foo,bar}"
     "parameters": {
       "foo": "http://example.org/FooProperty",
       "bar": {
         "id": "http://example.org/BarProperty",
         "displayName": "Bar",
         "required": False
       }
     }
   }

   Using the Parameters Object in HtmlForm objects:

   {
     "objectType": "HtmlForm",
     "mediaType": "application/x-www-form-urlencoded",
     "parameters": {
       "foo": "http://example.org/FooProperty",
       "bar": {
         "id": "http://example.org/BarProperty",
         "displayName": "Bar",
         "required": False
       }
     }
   }

9.  Styles Object

   A Styles Object is used by EmbedActionHandlers to provide CSS style
   hints for the container within which embedded content is to be
   displayed.  The object is expressed as either a single JSON
   dictionary object mapping CSS property names to appropriate CSS
   values, or an array of JSON dictionary objects.  An optional "media"
   member can be included within the dictionary providing a CSS Media
   Query.

Snell & Marum            Expires June 16, 2014                 [Page 11]
Internet-Draft              ActivityStreams                December 2013

   Example style hints:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "content": "Some plain text content",
         "mediaType": "text/plain",
         "style": {
           "height": "100px",
           "width": "100px",
           "box-shadow": "10px 10px 5px #888888"
         }
       }
     }
   }

   Multiple style hints for specific media query targets:

   {
     "objectType": "note",
     ...,
     "actions": {
       "view": {
         "objectType": "EmbedActionHandler",
         "content": "Some plain text content",
         "mediaType": "text/plain",
         "style": [
           {
             "media": "print",
             "height": "100px",
             "width": "100px",
             "box-shadow": "10px 10px 5px #888888"
           },
           {
             "media": "screen and (orientation: landscape)",
             "height": "100px",
             "width": "100px",
             "box-shadow": "10px 10px 5px #888888"
           }
         ]
       }
     }
   }

Snell & Marum            Expires June 16, 2014                 [Page 12]
Internet-Draft              ActivityStreams                December 2013

10.  Security Considerations

   TBD

11.  IANA Considerations

   TBD

12.  Normative References

   [I-D.snell-activitystreams]
              Snell, J., "JSON Activity Streams 2.0", draft-snell-
              activitystreams-05 (work in progress), November 2013.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570, March 2012.

Appendix A.  Using Action Handlers From Other Vocabularies

   The Activity Streams 2.0 Actions mechanism is specifically designed
   to allow Action Handlers from multiple vocabularies.

A.1.  Schema.org Actions Proposal

   Based on http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf:

   {
     "objectType": "video",
     ...,
     "actions": {
       "watch": [
         {
           "objectType": "http://schema.org/WebPageHandler",
           "url": "http://movies.example.com/player?id=123"
         },
         {
           "objectType": "http://schema.org/AndroidHandler",
           "url": "http://movies.example.com/player?id=123",
           "package": "com.movies"
         }
       ]
     }
   }

Snell & Marum            Expires June 16, 2014                 [Page 13]
Internet-Draft              ActivityStreams                December 2013

A.2.  Google's "Actions in the Inbox"

   Based on https://developers.google.com/gmail/actions/reference/
   review-action:

   {
     "objectType": "note",
     ...,
     "actions": {
       "review": {
         "objectType": "http://schema.org/ReviewAction",
         "review": {
           "objectType": "http://schema.org/Review",
           "itemReviewed": {
             "objectType": "http://schema.org/FoodEstablishment",
             "name": "Joe's Diner"
           },
           "reviewRating": {
             "objectType": "http://schema.org/Rating",
             "bestRating": "5",
             "worstRating": "1"
           }
         },
         "handler": {
           "objectType": "http://schema.org/HttpActionHandler",
           "url": "http://reviews.com/review?id=123",
           "requiredProperty": {
             "objectType": "http://schema.org/Property",
             "name": "review.reviewRating.ratingValue"
           },
           "method": "http://schema.org/HttpRequestMethod/POST"
         }
       }
     }
   }

A.3.  Mixing Vocabularies

   {
     "objectType": "video",
     ...,
     "actions": {
       "watch": [
         {
           "objectType": "HttpActionHandler",
           "url": "http://movies.example.com/player?id=123",
           "target": "NEW"

Snell & Marum            Expires June 16, 2014                 [Page 14]
Internet-Draft              ActivityStreams                December 2013

         },
         {
           "objectType": "http://schema.org/AndroidHandler",
           "url": "http://movies.example.com/player?id=123",
           "package": "com.movies"
         }
       ]
     }
   }

A.4.  Example Drawing From Multiple Vocabularies

   {
     "objectType": "video",
     "displayName": "A Movie!",
     ...,
     "actions": {
       "watch": [
         {
           "objectType": "EmbedActionHandler",
           "displayName": "HD",
           "mediaType": "video/mpeg",
           "url": "http://cdn.example.org?id=123amp;fmt=HD",
         },
         {
           "objectType": "EmbedActionHandler",
           "displayName": "SD",
           "mediaType": "video/mpeg",
           "url": "http://cdn.example.org?id=123&fmt=SD",
         },
         {
           "objectType": "IntentActionHandler",
           "url": "app://com.netflix",
           "context": {
             "id": 123
           }
         }
       ],
       "like": {
         "objectType": "EmbedActionHandler",
         "mediaType": "text/html",
         "url": "http://www.facebook.com/plugins/like.php...",
         "style": {
           "width": "150px",
           "height": "50px"
         }
       },

Snell & Marum            Expires June 16, 2014                 [Page 15]
Internet-Draft              ActivityStreams                December 2013

       "share": [
         {
           "objectType": "HttpActionHandler",
           "displayName": "Twitter",
           "url": "https://twitter.com/share?url=...",
           "target": "DIALOG"
         },
         {
           "objectType": "HttpActionHandler",
           "displayName": "Facebook",
           "url": "https://www.facebook.com/sharer/sharer.php?u=...",
           "target": "DIALOG"
         }
       ],
       "save": [
         {
           "objectType": "service",
           "id": "http://getpocket.com",
           "displayName": "Pocket",
           "context": {
             "url": "http://example.org/movie?id=123",
             "title": "A Movie!",
             "tags": "foo, bar, baz"
           }
         },
         {
           "objectType": "service",
           "id": "http://instapaper.com",
           "displayName": "Instapaper",
           "context": {
             "url": "http://example.org/movie?id=123",
             "title": "A Movie!",
             "selection": "An action movie!"
           }
         }
       ],
       "review": {
         "objectType": "HttpActionHandler",
         "displayName": "Rate this movie!",
         "url": "http://review.example.org/movie?id=123",
         "method": "POST",
         "expects": {
           "objectType": "HtmlForm",
           "mediaType": "application/x-www-form-urlencoded",
           "parameters": {
             "rating": {
               "id": "http://schema.org/ratingValue",
               "bestRating": 5,

Snell & Marum            Expires June 16, 2014                 [Page 16]
Internet-Draft              ActivityStreams                December 2013

               "worstRating": 0,
               "displayName": "Rating",
               "required": true
             },
             "comments": {
               "id": "http://schema.org/commentText",
               "displayName": "Comments",
               "required": "false"
             }
           }
         }
       }
     }
   }

Authors' Addresses

   James M Snell
   IBM

   Email: jasnell@gmail.com

   Matthew Marum
   SugarCRM

   Email: mgmarum@gmail.com

Snell & Marum            Expires June 16, 2014                 [Page 17]