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.

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

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:

3. HTTP Action Handler

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:

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

4. Embed Action Handler

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

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:

  {
    “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

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

Targeting a specific application:

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

6. HTML Form Objects

{
  "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,
            "value": "Provided Value"
          }
        }
      }
    }
  }
}
      

7. URL Template Objects

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

{
  "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 [htmlform] and URL Templates [urltemplate]. The object is expressed as a JSON dictionary mapping parameter names to Type Values [I-D.snell-activitystreams] describing the parameters.

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.

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"
        }
      ]
    }
  }
}
      

10. Security Considerations

TBD

11. IANA Considerations

TBD

12. Normative References

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"
        }
      ]
    }
  }
        

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"
        },
        {
          "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"
        }
      },
      "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,
              "worstRating": 0,
              "displayName": "Rating",
              "required": true
            },
            "comments": {
              "id": "http://schema.org/commentText",
              "displayName": "Comments",
              "required": "false"
            }
          }
        }
      }
    }
  }
        

Authors' Addresses