Activity Streams (http://activitystrea.ms) J. Snell
Internet-Draft IBM
Intended status: Standards Track M. Marum
Expires: November 02, 2014 SugarCRM
May 01, 2014

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

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 November 02, 2014.

Copyright Notice

Copyright (c) 2014 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

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 ("action handlers") 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.

2. Action Handlers

An action handler is an Activity Streams 2.0 object whose objectType and member properties instruct a consuming application how to carry out the verb the action handler has been associated with. For instance, given the following example:

  {
    "objectType": "note",
    "displayName": "Title of the note",
    "content": "This is a simple note.",
    "actions": {
      "share": {
        "objectType": "HttpActionHandler",
        "url": "http://example.org/share"
      },
      "like": {
        "objectType": "EmbedActionHandler",
        "mediaType": "text/plain",
        "content": "Hello World"
      }
    }
  }
      

The "note" object has two declared actions, "share" and "like". Each of those is associated with one action handler object. The "share" action has a action handler of type "HttpActionHandler", while the "like" action has an "EmbedActionHandler".

As illustrated in the example, action handlers are represented as Activity Streams 2.0 objects. All such objects share a common set of base member properties as defined in the following table:

Property Value Description
confirm Boolean True if the consuming application ought to seek confirmation prior to using the action handler to carry out it's associated action. Defaults to False.
context JSON Object Contextual information associated with the action handler, represented as a JSON Object without any particular structure. How the context is used is dependent entirely on the action handler definition and on how a consuming application chooses to implement the action handler.
expects Link Value [I-D.snell-activitystreams] For action handlers with a distinct input requirement (e.g. HttpActionHandler), the expects property provides a description of the expected input. The value is expressed as either a String containing a fully qualified IRI, an Activity Stream Object, or an Array of IRI's or Objects. When multiple values are provided, they MUST be considered as mutually exclusive alternatives.
returns Link Value [I-D.snell-activitystreams] For action handlers with a distinct output, the returns property provides a description of the expected output. The value is expressed as either a String containing a fully qualified IRI, an Activity Stream Object, or an Array of IRI's or Objects. When multiple values are provided, they MUST be considered as mutually exclusive alternatives.
auth Authentication Value [authentication] For action handlers with specific authentication requirements, the "auth" property provides information about the specific authentication mechanisms supported.
requires Link Value [I-D.snell-activitystreams] An optional Link Value whose value(s) describe features or behaviors an implementation MUST support in order to carry out the action. Requirements are designed to be intentionally open-ended and will vary depending on specific Action Handler type. Any implementation that does not support any specified required feature MUST ignore the Action Handler.
prefers Link Value [I-D.snell-activitystreams] An optional Link Value whose value(s) describe features or behaviors an implementation SHOULD support in order to carry out the action. Requirements are designed to be intentionally open-ended and will vary depending on specific Action Handler type. Any implementation that does not support any specified preferred feature MAY ignore the feature.

This specification defines three specific base types of action handler:

Implementations are free to use Activity Stream objects of any objectType as an action handler. Consuming applications MAY ignore any object it encounters that use objectTypes that are not recognized or supported as action handlers. Alternatively, the consuming application MAY treat such objects as implied Intent Action Handlers [intentactionhandler].

Multiple independent action handlers can be associated with any single verb using a JSON Array. The ordering of objects within such an array is not considered to be significant.

For example, in the following, the "share" action has two associated action handlers:

  {
    "objectType": "event",
    "displayName": "Party!",
    "content": "We're going to party like it's 1999!",
    "id": "urn:example:events:123",
    "actions": {
      "share": [
        {
          "objectType": "HttpActionHandler",
          "method": "POST",
          "url": "http://example.org/share-this/123",
          "target": "DIALOG",
          "returns": {
            "objectType": "TypedPayload",
            "mediaType": "text/html"
          }
        },
        {
          "objectType": "EmbedActionHandler",
          "mediaType": "text/html",
          "content": "<div>...</div>"
        }
      ]  
    }
  }
      

3. HTTP Action Handler

An HTTP Action Handler describes an HTTP request/response flow that is used to carry out an action. It is identified using an objectType value of "HttpActionHandler".

Property Value Description
url Link Value Specifies the HTTP or HTTPS URL to which the HTTP request is directed.
method HTTP Method String (e.g. "GET", "POST", "PUT", etc) The HTTP method to use. Defaults to "GET"
target "DEFAULT" - Consumer defined default; "NONE" - No navigation or UI context (e.g. a hidden HTTP action that does not result in the creation or use of a browser window); "NEW" - A new navigation or UI context (e.g. show the results of the HTTP request in a browser window or tab.); "CURRENT" - Reuse the existing navigation or UI context (e.g. show the results of the HTTP request in an existing browser window or tab.); {Other token value} - Any other TOKEN value. Interpretation and support of such extension tokens is dependent on the consuming application. Unknown or unsupported values MUST be ignored. Specifies the intended target of the HTTP action. This determines whether the action results in a new navigation context (e.g. new browser window) or whether the action is "hidden". When not specified, defaults to "DEFAULT", meaning that the consuming application is free to determine an appropriate target context.

For example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "view": {
        "objectType": "HttpActionHandler",
        "url": "http://example.org/foo",
        "method": "GET"
      }
    }
  }
      

As a shortcut, HttpActionHandlers that use the "GET" method and a "DEFAULT" target can be specified using a JSON string containing the absolute URL. For instance:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "view": "http://example.org/foo"
    }
  }
      

In the Activity Streams 2.0 format, the "url" property is defined as a "Link Value", this means that it is possible for the value of the "url" property to be an Activity Stream object that a consuming application can use to resolve the actual target URL. This specification defines a new UrlTemplate [urltemplate] objectType specifically intended for such use.

The UrlTemplate object can be used within an HTTP Action Handler, for instance, whenever carrying out the HTTP request requires the construction of a new URL that includes variable parameters:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "review": {
        "objectType": "HttpActionHandler",
        "url": {
          "objectType": "UrlTemplate",
          "template": "http://example.org/note/123{?rating}",
          "parameters": {
            "rating": {
              "displayName": "Rating",
              "maxInclusive": 5,
              "minInclusive": 1,
              "type": "unsignedInt"
            }
          }
        },
        "method": "POST",
        "target": "NEW"
      }
    }
  }
      

If the intended HTTP request uses the GET method and DEFAULT target, the UrlTemplate object itself can be used directly as the action handler.

"GET" HttpActionHandler shortcut using a URL Template:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "view": {
        "objectType": "UrlTemplate",
        "template": "http://example.org/note/{noteid}",
        "parameters": {
          "noteid": {
            "type": "nonNegativeInteger",
            "totalDigits": 5
          }
        }
      }
    }
  }
      

If the HTTP request requires an input payload, the HttpActionHandler object can contain an "expects" property. The value of "expects" is an Activity Streams 2.0 "Link Value" represented either as a simple JSON string containing a fully qualified IRI, an Activity Stream object, or an array of IRI's or Objects. This specification defines a new HtmlForm [htmlform] objectType to be used whenever the input of the HTTP request is an HTML Form POST. A new TypedPayload [typedPayload] objectType is defined for use whenever the input is an arbitrary MIME media type.

For example, the following describes an HTML Form post with a single "foo" parameter submitted using the "application/x-www-form-urlencoded" format:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "share": {
        "objectType": "HttpActionHandler",
        "method": "POST",
        "url": "http://example.org/foo",
        "expects": {
          "objectType": "HtmlForm",
          "mediaType": "application/x-www-form-urlencoded",
          "parameters": {
            "foo": {
              "type": "string",
              "displayName": "Foo Property"
            }
          }
        }
      }
    }
  }
      

4. Embed Action Handler

An Embed Action Handler defines static or dynamic content to be visually rendered to carry out an action. Examples of embeds can include static HTML, images, videos, gadgets and applications. It is identified using an objectType value of "EmbedActionHandler".

Property Value Description
url Link Value The URL from which to retrieve the content for this embed.
content String The character based "static" content to be embeded. The "mediaType" parameter specifies the MIME media type of the content.
mediaType MIME Media Type The MIME Media Type of the embedded content.
style Styles Object [stylesobject] Visual CSS styling hints to apply to the element containing the embedded content.
preview Link Value A reference to a "preview" representation of the embedded content. Typically, this would a URL to a thumbnail or screenshot image of the content.
target "DEFAULT"; "INLINE"; {Other token value}

In the following example, the "view" action is associated with an "EmbedActionHandler" containing a static fragment of HTML markup:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple 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"
      }
    }
  }
      

Alternatively, the embedded content can be referenced by URL:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "view": {
        "objectType": "EmbedActionHandler",
        "url": "http://example.org/foo",
        "mediaType": "text/html"
      }
    }
  }
      

The mediaType parameter specifies the type of content to be embedded. Consuming applications MAY ignore Embed Action Handlers that specify unrecognized or unsupported mediaTypes.

Example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "view": {
        "objectType": "EmbedActionHandler",
        "url": "http://example.org/foo.mpg",
        "mediaType": "video/mpeg"
      }
    }
  }
      

5. Intent Action Handler

An Intent Action Handler provides a generic way for the publisher of an Activity object to tell the consuming application to figure out how to handle the action on it's own. The consumer can, for instance, pass the object off to some other native platform application. It is identified using an objectType value of "IntentActionHandler".

For example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "share": {
        "objectType": "IntentActionHandler",
        "displayName": "Share This",
        "context": {
          "foo": "ABC",
          "bar": 123
        }
      }
    }
  }
      

6. Using "service" and "application" objects as action handlers

The "service" and "application" object are existing objectTypes defined by the Activity Streams 1.0 core schema. While these objects were not originally designed to be used as action handlers, they can be. Specifically, the "service" objectType can be used when the action is to be carried out using some specific third party service interface; the "application" objectType can be used when the action is to be carried out by deferring some some specific native platform application.

For example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "share": {
        "objectType": "service",
        "displayName": "My Sharing Service",
        "url": "http://share.example.org/api"
      },
      "save": {
        "objectType": "application",
        "displayName": "Read this later!",
        "platform": "android",
        "id": "123",
        "url": "http://play.google.com/..."
      }
    }
  }
      

7. HTML Form Objects

Property Value Description
mediaType MIME Media Type Defaults to "application/x-www-form-urlencoded"
parameters Parameters Object [parameters] Defines the HTML form parameters.

For example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple 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",
              "type": "string",
              "placeholder": "Foo"
            },
            "bar": {
              "type": "string",
              "value": "Provided Value"
            }
          }
        }
      }
    }
  }
      

Is roughly equivalent to the following HTML form:

  <form method="post" action="http://example.org/foo">
    <label for="foo">Foo:</label>
    <input id="foo" name="foo" type="input" placeholder="Foo" />
    <input name="bar" type="hidden" value="Provided Value" />
    <input type="submit" />
  </form>

8. Typed Payload Objects

Property Value Description
mediaType MIME Media Type The MIME Media Type of the Payload
type Type Value [I-D.snell-activitystreams] An optional Type Value that describes the payloads semantic type.
schema Link Value [I-D.snell-activitystreams] An optional Link Value whose value(s) describe the structure of the payload data. The value is represented either as a String with a fully qualified IRI, an Activity Stream object, or an Array of IRIs and Objects. If multiple values are provided, they are to be considered mutually exclusive alternatives.

For example:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "actions": {
      "review": {
        "objectType": "HttpActionHandler",
        "method": "POST",
        "url": "http://example.org/foo",
        "expects": {
          "objectType": "TypedPayload",
          "mediaType": "text/json",
        }
      }
    }
  }
      

9. URL Template Objects

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

Property Value Description
template URL Template The [RFC6570] URL Template
parameters Parameters Object [parameters] Defines the URL Template parameters
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note.",
  "actions": {
    "review": {
      "objectType": "UrlTemplate",
      "template": "http://example.org/notes/{noteid}",
      "parameters": {
        "noteid": {
          "type": "nonNegativeInteger",
          "totalDigits": 5
        }
      }
    }
  }
}
      

If the given URL template includes any parameter tokens that do not appear within the "parameters" property, the parameter value type is assumed to be a UTF-8 encoded xsd:string with no maximum length.

10. 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 parameter descriptions which take the form of either an XML Schema type name [W3C.REC-xmlschema-2-20041028], an absolute IRI, a parameter object [ParameterObject], or in some limited cases, TypedPayload or UrlTemplate objects.

By default, all parameters are assumed to be required. When a parameter is described using an object, the object MAY contain 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": "string",
      "bar": {
        "type": "string",
        "required": false
      }
    }
  }
      

In this example, both the "foo" and "bar" parameter conform to the XML Schema type "xsd:string". The "foo" parameter is required while the "bar" parameter is optional.

Using the Parameters Object in HtmlForm objects:

  {
    "objectType": "HtmlForm",
    "mediaType": "application/x-www-form-urlencoded",
    "parameters": {
      "foo": {
        "displayName": "Foo",
        "type": "string"
      },
      "bar": {
        "displayName": "Bar",
        "type": "string",
        "required": false
      }
    }
  }
      

10.1. The Parameter Object

Parameter objects provide a rich description of a single parameter in a manner that is aligned with the commonly used XML Schema type system [W3C.REC-xmlschema-2-20041028].

Property Value Description
displayName Natural Language Value [I-D.snell-activitystreams] An Activity Streams 2.0 Natural Language Value.
required boolean True if the parameter is required. Defaults to true.
repeated boolean True if the parameter can be repeated zero or more times. Defaults to false.
value (Any) Provides a fixed value for the parameter. When specified, implementations MUST use the specified value.
default (Any) Provides a default value for the parameter. When specified, implementations MUST use the specified value if no other value is not supplied.
type XSD [W3C.REC-xmlschema-2-20041028] type name or IRI Identifies the value type using either an XML Schema [W3C.REC-xmlschema-2-20041028] simple type name or an absolute IRI. If an implementation encounters a type it does not recognize, the property MAY be ignored. When not specified, the value type is assumed to be a UTF-8 encoded "xsd:string".
enumeration Array of (Any) Provides a fixed array of possible values for the parameter. When specified, implementations MUST use one of the specified values.
minLength Non-Negative Integer Specifies the minimum "unit of length" for the value. The "unit of length" depends entirely on the value type as specified by the "type" property. For instance, For xsd:string, the length is determined by the number of characters; for xsd:hexBinary, the length is determined by the number of encoded 8-bit octets.
maxLength Non-Negative Integer Specifies the maximum "unit of length" for the value. The "unit of length" depends entirely on the value type as specified by the "type" property. For instance, For xsd:string, the length is determined by the number of characters; for xsd:hexBinary, the length is determined by the number of encoded 8-bit octets.
maxInclusive (Any) A value that is considered to be the inclusive upper bound of a range of possible values. This would typically be used only with numeric parameters.
maxExclusive (Any) A value that is considered to be the exclusive upper bound of a range of possible values. This would typically be used only with numeric parameters.
minInclusive (Any) A value that is considered to be the inclusive lower bound of a range of possible values. This would typically be used only with numeric parameters.
minExclusive (Any) A value that is considered to be the exclusive lower bound of a range of possible values. This would typically be used only with numeric parameters.
step Non-negative Number Specifies the legal numeric interval between acceptable values for the parameter. The step value MUST be a number and MUST conform to the specified type. For instance, if type is "unsignedInt", then step=2 would indicate legal values of 0, 2, 4, 6, and so on. The step property MAY be ignored if it's value does not correspond to the expected type.
totalDigits Non-negative integer Specifies the maximum number of digits (integer and fractional) that can be included in numeric values. The totalDigits property MUST be ignored if the value type identified by the type property is not a numeric type.
fractionDigits Non-negative integer Specifies the maximum number of fractional digits that can be included in numeric values. The fractionDigits property MUST be ignored if the value type identified by the type property is not a numeric type.
pattern String or Array of Strings One or more Regular Expressions that describe the acceptable structure of the value. Typically used when the value is a string. Multiple patterns are mutually exclusive options. That is, the parameter value is expected to conform to at least one of the given patterns.
placeholder Natural Language Value [I-D.snell-activitystreams] An optional Natural Language Value providing a text hint that describes the expected value of the parameter.

Using the Parameter Object in HtmlForm objects:

  {
    "objectType": "HtmlForm",
    "mediaType": "application/x-www-form-urlencoded",
    "parameters": {
      "foo": "string",
      "bar": {
        "displayName": "Bar",
        "required": false,
        "repeated": false,
        "type": "unsignedInt",
        "default": 3,
        "minInclusive": 1,
        "maxInclusive": 5
      }
    }
  }
      

10.2. Using UrlTemplate and TypedPayload objects as parameter descriptions

In certain cases, when the value of a parameter is expected to be either a URI or IRI, the UrlTemplate objectType [urltemplate] MAY be used as the parameter description. In such cases, the "required", "repeated", "default" and "placeholder" properties from the Parameter objectType [ParameterObject] can be used as additional properties within the UrlTemplate object.

For example:

          {
            "objectType": "HtmlForm",
            "mediaType": "application/x-www-form-urlencoded",
            "parameters": {
              "foo": "http://example.org/FooProperty",
              "bar": {
                "objectType": "UrlTemplate",
                "template": "http://example.org{/baz}",
                "displayName": "Bar",
                "required": false,
                "repeated": false
              }
            }
          }
        

Likewise, when the value of a parameter is expected to be an instance of a specific MIME media type, the TypedPayload objectType [typedPayload] can be used.

          {
            "objectType": "HtmlForm",
            "mediaType": "multipart/form-data",
            "parameters": {
              "file": {
                "objectType": "TypedPayload",
                "mediaType": "image/*",
                "repeated": true
              }
            }
          }
        

11. Authentication Object

An Authentication Object is used by Action Handlers that require specific authentication options to be supported in order to carry out the Action. The object is expresed as a JSON dictionary mapping authentication schema labels to JSON dictionaries that provide a specific description of properties and requirements specific to the scheme.

Example Authentication details:

  {
    "objectType": "note",
    "displayName": "A simple note object",
    "content": "This is a simple note",
    "actions": {
      "view": {
        "objectType": "HttpActionHandler",
        "method": "GET",
        "url": "http://example.org/notes/1",
        "auth": {
          "basic": {
            "realm": "http://example.org"
          },
          "oauth": {
            "scopes": [
              "some.oauth.scope",
              "another.oauth.scope"
            ]
          }
        }
      }
    }
  }
      

This specification does not define the authentication schemes or their associated properties. Unrecognized authentication schemes MAY be ignored. However, if an implementation fails to recognize any of the authentication schemes specified by an Action Handler, it might not be possible to successfully carry out the Action.

12. 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",
  "displayName": "A simple note object",
  "content": "This is a simple 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",
  "displayName": "A simple note object",
  "content": "This is a simple 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"
        }
      ]
    }
  }
}
      

13. Security Considerations

TBD

14. IANA Considerations

TBD

15. Normative References

[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.
[I-D.snell-activitystreams] Snell, J., "JSON Activity Streams 2.0", Internet-Draft draft-snell-activitystreams-07, April 2014.
[W3C.REC-xmlschema-2-20041028] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004.

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",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "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",
    "displayName": "A simple note object",
    "content": "This is a simple 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",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "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!",
    "displayName": "A simple note object",
    "content": "This is a simple note.",
    "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": "application",
          "displayName": "Watch on Netflix",
          "url": "http://netflix.com..."
        }
      ],
      "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": {
              "maxInclusive": 5,
              "minInclusive": 0,
              "fractionDigits": 2,
              "totalDigits": 3
              "type": "float",
              "displayName": "Rating"
            },
            "comments": {
              "displayName": "Comments",
              "type": "string",
              "required": false
            }
          }
        }
      }
    }
  }
        

Authors' Addresses

James M Snell IBM EMail: jasnell@gmail.com
Matthew Marum SugarCRM EMail: mgmarum@gmail.com