Activity Streams (http://activitystrea.ms) J. Snell Internet-Draft IBM Intended status: Standards Track M. Marum Expires: June 15, 2014 SugarCRM December 12, 2013 JSON Activity Streams 2.0 - Action Handlers draft-snell-activitystreams-actions-00 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 15, 2014. Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. Snell & Marum Expires June 15, 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 . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 1. Overview TBD 2. Common Action Handler Properties Common base properties available for all Action Handler objects: +-----------+-----------------------------+-------------------------+ | 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, | Snell & Marum Expires June 15, 2014 [Page 2] Internet-Draft ActivityStreams December 2013 | | | 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 | | | | determines whether the | | | | action results in a new | | | | navigation context (e.g. | | | | new browser window) or | | | | whether the action is | | | | "hidden". Defaults to | | | | "DEFAULT". | +-------------+-------------------------+---------------------------+ Snell & Marum Expires June 15, 2014 [Page 3] Internet-Draft ActivityStreams December 2013 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 15, 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 15, 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": "
This is some bit of embedded HTML
", "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 15, 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 15, 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 15, 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 15, 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 15, 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 15, 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 15, 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 15, 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": "UrlTemplate", "template": "http://example.org/note/123{?rating}", "parameters": { "rating": { "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" } } } } } } Snell & Marum Expires June 15, 2014 [Page 14] Internet-Draft ActivityStreams December 2013 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" } ] } } Authors' Addresses James M Snell IBM Email: jasnell@gmail.com Matthew Marum SugarCRM Email: mgmarum@gmail.com Snell & Marum Expires June 15, 2014 [Page 15]