This specification defines Action Handlers for use with the Activity Streams 2.0 format.
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 a recommendation the ideas described herein have not yet been broadly implemented and have definitions that will evolve through successive iterations of this draft.
The Activity Streams 2.0 [[!AS2]] specification introduces the notion
of "actions" that can be associated with objects. Using the
property, 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.
An Action Handler is an
Activity Streams 2.0 object whose
objectType and other properties
instruct a consuming application how to carry out the verb the action handler
has been associated with.
note" object has two declared actions: "
like". Each of those is associated with one action handler
object. The "
share" action has a action handler of type
ViewActionHandler", while the "
like" action has an
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:
True if the consuming application ought to seek confirmation
prior to using the action handler to carry out it's associated
action. Defaults to
||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 type and how a consuming application chooses to implement the action handler.|
For Action Handlers with specific authentication requirements, the
||Link Value||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 requirement MUST ignore the Action Handler.|
||Link Value||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 preference MAY simply choose to ignore the preference.|
This specification defines four 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.
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.
Certain Action Handlers types, such as the View Action Handler and HTTP Action Handler, are considered to be "Protocol-Based" -- that is, implementation of the action requires an application to invoke a request-and-response type transaction. Such Action Handlers MAY contain additional properties that describe the expected inputs, outputs, authentication, and other requirements necessary to complete the action.
For Action Handlers with a distinct input requirement, the
For Action Handlers with a distinct output, the
Note that all Action Handler types are subject to any relevant active Content Security Policy [[!CSP11]], or CSP, that is in-scope for the context in which the Action Handler is being invoked.
The specific CSP directive that applies to a particular action handler type may vary depending on the Action Handler's objectType.
Because the successful application of the Content Security Policy depends on the ability to determine the Origin [[!RFC6454]] with which content is associated, the following rules for determining the origin for an Action Handler apply:
urlproperty, and that property is being used to invoke the handler, the URL specified is used to establish the origin as defined in [[!RFC6454]], Section 4.
The Origin for the "
ViewActionHandler" is determined to be
http://example.org:80"; the Origin for the
EmbedActionHandler" is "
and the Origin for the "
An HTTP Action Handler describes
an HTTP request/response flow used to carry out an action. It is
identified using an objectType value of "
The defining characteristic of the HttpActionHandler is that the HTTP request and response flow occur independently of any browser or navigation context. In other words, invocation of the handler MUST NOT directly cause the user agent to navigate to or visually display the results of the HTTP request. This makes the HttpActionHandler suited primarily for RESTful API style operations in much the same way that a web application developer would use the XMLHttpRequest object.
In addition to the core properties supported by all Action Handlers,
and the additional
attributes, HttpActionHandler objects support the following properties:
||Link Value||Specifies the HTTP or HTTPS URL to which the HTTP request is directed.|
HTTP Method String (e.g.
The HTTP method to use. Defaults to
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
objectType specifically intended for such use.
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:
If the HTTP request requires an input payload, the HttpActionHandler
object can contain an
expects property. The value
expects is a Link Value represented either as a simple
JSON string containing a fully qualified IRI, an Object, or an array of
IRI's or Objects. This specification defines a new
objectType to be used whenever the input of the HTTP request is an HTML
Form POST. A new 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
When a Content Security Policy is in effect, invocation of the HTTP
Action Handler is always governed by the "
defined in Section 188.8.131.52 of [[!CSP11]]. Further, when
the HTTP Action Hander specifies any method other than "
GET", and the
input when invoking the action handler is an HTML Form, the handler
is additionally governed by the CSP "
The View Action Handler describes
an action that causes either an existing or new browser context to be
navigated to the identified resource. It is specified using an objectType
value of "
ViewActionHandler is roughly equivalent to the HTML anchor tag in that invocation of the handler causes the user agent to navigate to the identified resource. Unlike the anchor tag, however, the ViewActionHandler can specify the HTTP method, input payload and expected output.
The View Action Handler adopts all of the same properties as the HTTP Action Handler and adds the following two additional, optional properties:
||Browsing Context Name or Keyword||Specifies the Browsing Context Name or Keyword as defined by [[HTML5]], that will be used when the action handler is invoked.|
||[[HTML5]] "sandbox" restrictions||
An optional string specifying [[HTML5]] sandbox restrictions
that ought to be applied to the content referenced by the
As a shortcut, ViewActionHandlers that use the "
GET" method can be
specified using a JSON string containing the absolute URL. For
In such cases, the "target" property is assumed to be unspecified.
If the intended HTTP request uses the
GET method, and the target URL
is to be constructed by expanding a URL Template, the UrlTemplate
object itself can be used directly as the action handler.
When a Content Security Policy is in effect, View Action Handlers are
subject to the same processing requirements as HTML anchor and form
elements. For instance, the "
child_src" directive governs whether or
not the View Action Handler is permitted to create nested or
auxiliary browsing contexts, while the "
governs a View Action Handler that uses any method other than
and whose input is an HTML Form.
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
The defining characteristic that differentiates an Embed Action Handler from a View Action Handler is that the former always implies the use of the current browsing context and that content is expected to be displayed inline as embedded content (similar to the way HTML5 img, audio, video and iframe tags are handled).
Embed Action Handlers use the
mediaType properties defined by the Activity
Streams 2.0 specification. The
url property is used
to specify the URL from which to retrieve the content to embed.
content property is used to specify the embedded
content directly within the Embed Action Handler. The
property specifies the MIME Media Type of the embedded content.
As with the View Action Handler, an Embed Action Handler MAY contain a sandbox property whose value is a string specifying [[!HTML5]] sandbox restrictionsthat ought to be applied to the embedded content.
Additional properties support by the Embed Action Handler include:
||Styles Value||CSS styling hints to apply to the element containing the embedded content.|
||Link Value||A Link Value referencing a "preview" representation of the embedded content. Typically, this would be a URL to a thumbnail or screenshot image of the content.|
In the following example, the "view" action is associated with an
EmbedActionHandler" containing a static fragment of HTML markup:
Alternatively, the embedded content can be referenced by URL:
mediaType parameter specifies the type of
content to be embedded. Consuming applications MAY ignore Embed
Action Handlers that specify unrecognized or unsupported mediaTypes.
Exactly how the content referenced by the Action Handler is embedded
and displayed is dependent on the implementation and may vary by
content type. For instance, an implementation invoking an Embed
Action Handler that references an image resource (e.g. "
might use the HTML5 img tag to embed the content.
When a Content Security Policy is in effect, the specific directives
that apply will be entirely dependent on the type of content being
embedded and how the implementation chooses to embed it. For
instance, embedded image resources will be governed by the
image_src" directive while embedded video will be governed by the
media_src" directive. Please refer to the Content Security Policy
[[!CSP11]] specification for a detailed explanation of
each of the directives that may apply.
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
Whether and how the Intent Action Handler is invoked is dependent
entirely on the implementation. Regardless of how the handler is
invoked, the implementation MUST, at a minimum, pass the value of the
context property along.
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 adapted to that purpose. 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. When such objectTypes are used as actions handlers,
they are to be treated as specializations of Intent Action Handler.
The HTML Form objectType
is used to provide an abstracted description of an HTML form. The
primary motivation for expressing forms using the HTML Form object
is to separate the definition of the form from the presentation.
When used within an Action Handler, this objectType allows the
creator of the objectType to express required inputs without
the need to express how that form is to be presented to the end
user. HTML Form objects are identified using the objectType
In addition to the properties common to all Activity Streams objectTypes, HTML Form objects define the following additional properties:
||Parameters Object||Defines the HTML form parameters|
For HTML Form objects, the
is used to identify the MIME media type used to encode the form
data. The default value is assumed to be "
The Typed Payload objectType is used
to provide an abstract description of an arbitrary data payload of
any Media Type. In an HTTP Action Handler, for instance, the
Typed Payload can be used to describe that a REST API requires a
JSON-formatted input. The Typed Payload object is identified using
the objectType value "
In addition to the properties common to all objectTypes, Typed Payload objects define the following additional properties:
An optional Type Value that describes the payload's
semantic type. Note that this is distinct from the
MIME Media Type, which is expressed using the
|schema||Link Value||An optional Link Value whose value(s) describe the structure of the payload data. If multiple values are provided, they are to be considered mutually exclusive alternatives.|
The URL Template
objectType is used to provide a description of an [[!RFC6570]]
URL Template. The URL Template is identified using the objectType
In addition to the common properties support by all objectTypes, the URL Template object defines the following additional properties:
||[[!RFC6570]] URL Template||The URL Template|
||Parameters Object||Defines the URL Template parameters|
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.
A Parameters Object is used to provide descriptions of the variable inputs of objects such as HTML Forms and URL Templates. 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 [[!XMLSCHEMA-2]], an absolute IRI, a Parameter Object, or in some limited cases, Typed Payload or URL Template objects.
By default, all parameters are assumed to be required. When a
parameter is described using an object, the object MAY contain a
required member. If
false, use of the parameter is assumed to be optional.
In this example, both the "
foo" and "
parameters conform to the XML Schema type "
foo" parameter is required while the "
parameter is optional.
A Parameter Object provides a rich description of a single parameter in a manner that is aligned with the commonly used XML Schema Type System [[!XMLSCHEMA-2]].
Parameter objects are simple JSON Objects with the following optional attributes:
||Natural Language Value||A Natural Language Value|
||(Any)||Provides a fixed value for the parameter. When specified, implementations MUST use the specified value.|
||(Any)||Provides a default value for the parameter. When specified, implementations MUST use the specified value if no other value is supplied.|
||[[!XMLSCHEMA-2]] type name or IRI||
Identifies the value type using either an XML Schema simple type name
or an absolute IRI. If an implementation encounters a type it does
not recognize, the property type MAY be assumed to be a UTF-8 encoded
||Array of (Any)||Provides a fixed array of possible values for the parameter. When specified, the property value MUST be one of the specified values.|
Specifies the minimum unit of length for the value. The unit of length
depends entirely on the value type as defined by the
Specifies the maximum unit of length for the value. The unit of length
depends entirely on the value type as defined by the
||(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.|
||(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.|
||(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.|
||(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.|
||Non-negative Number or [[!RFC3339]] durations||
Specifies the allowable numeric interval between acceptable values for the parameter.
The step value MUST either be a number or a date, time or date-time. If the
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
Specifies the maximum number of fractional digits that can be included
in numeric values. The fractionDigits property MUST be ignored if the
||String or Array of Strings||
One or more Regular Expressions that describe the acceptable structure
of the value. Typically used when the value
||Natural Language Value||A Natural Language Value providing a text hint describing the expected value of the parameter.|
In certain cases, when the value of a parameter is expected to be
either a URI or IRI, the URL Template object MAY be
used as the parameter description. In such cases, the
from the Parameter object can be used as additional properties within
the URL Template object.
Likewise, when the value of a parameter is expected to be an instance of a specific MIME media type, the Typed Payload objectType can be used.
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.
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.
A Styles Object is
used by the Embed Action Handler 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
member can be included within the dictionary providing a CSS Media
Multiple style hints can be specified for separate media query targets.
Each of the four basic Action Handler types defined herein are, for the most part, designed to map directly to concrete implementation strategies within a user agent. While the action handler descriptions themselves are largely independent of the user interface and try not to make too many assumptions about how the action will be presented to a user, it is important to understand how each has been originally intended to be implemented.
The [[!HTML5]] specification defines a Command as "the abstraction behind menu items, buttons, and links." In other words, a command is the code that is invoked when you click on a link, press a button or select an item from a menu. For every command, there are essentially two elements: the user interface component used to trigger the command, and the code that is invoked once the command is triggered.
An Action Handler is a declarative description of what ought to happen when a Command is triggered.
Implementation of the View Action Handler is, perhaps, the most straightforward of the four basic Action Handler types. It is essentially
the same as an HTML
anchor tag with the notable exception that a View Action Handler can use any HTTP method and can define distinct
expected inputs and outputs. The end result, however, is the same: triggering a View Action Handler results in either creating or navigating an HTML
The HTTP Action Handler is nearly identical to View Action Handler with the exception that the HTTP request is sent and processed independently of any Browsing Context. That is, the HTTP Action Handler is roughly equivalent to using the [[XMLHTTPREQUEST]] to perform an asychronous background HTTP request flow.
The Embed Action Handler, on the other hand, is more closely aligned with HTML5's
Embedded Content model. Triggering an Embed Action Handler will mean embedding content within an existing Browsing Context using mechanisms such as HTML's
The Intent Action Handler is unique in that is does not directly map to any one particular HTML5 concept. Rather, the Intent Action Handler communicates exactly what it's name says: the intent to carry out an action, without details as to how that is done. It might be the case that the user agent is capable of performing the action itself. More likely, however, the user agent will be required to call out to an external native application. This pattern is common on many mobile platform operating systems in use today.
As new Action Handler types are created, it will be important for the specifications that define those handlers to also comment on how the handler is expected to be implemented so that developers can ensure a clear, consistent and reliable user experience.
The events supported by the ActionCommand object include: