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.

Introduction

The Activity Streams 2.0 [[!AS2]] specification introduces the notion of "actions" that can be associated with objects. Using the actions 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.

For instance, given the following example:
{
  "objectType": "note",
  "displayName": "Title of the note",
  "content": "This is a simple note.",
  "actions": {
    "share": {
      "objectType": "ViewActionHandler",
      "url": "http://example.org/share",
      "target": "_blank"
    },
    "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 "ViewActionHandler", while the "like" action has an "EmbedActionHandler".

Action Handlers

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 type and how a consuming application chooses to implement the action handler.
auth Authentication Value For Action Handlers with specific authentication requirements, the auth property provides information about the specific authentication mechanisms supported.
requires 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.
prefers 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.

In the following example, 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",
       "returns": {
         "objectType": "TypedPayload",
         "mediaType": "text/html"
       }
     },
     {
       "objectType": "EmbedActionHandler",
       "mediaType": "text/html",
       "content": "<div>...</div>"
     }
   ]
  }
}

Common Attributes for Protocol-based Action Handlers

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.

Property Value Description
expects Link Value For Action Handlers with a distinct input requirement, the expects property provides a description of the expected input. The value is expressed as a Link Value. When multiple values are provided, they MUST be considered mutually exclusive alternatives.
returns Link Value For Action Handlers with a distinct output, the returns property provides a description of the expected output. The value is expressed as a Link Value. When multiple values are provided, they MUST be considered mutually exclusive alternatives.

Content-Security Policy

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:

The example below illustrates an HTTP response carrying an Activity Streams object with three separate Action Handlers, each with a distinct Origin:
HTTP/1.1 200 OK
Content-Type: application/activity+json
Content-Location: http://example.net/baz

{
   "objectType": "note",
   "content": "This is a simple note",
   "actions": {
     "view": {
       {
         "objectType": "ViewActionHandler",
         "url": "http://example.org/foo"
       },
       {
         "objectType": "EmbedActionHandler",
         "content": "<div>This is fun</div>",
         "@context": {
           "@base": "https://example.com:8443/bar"
         }
       },
       {
         "objectType": "IntentActionHandler",
         "context": {
           "a": "b",
           "b": "c"
         }
       }
     }
   }
}

The Origin for the "ViewActionHandler" is determined to be "http://example.org:80"; the Origin for the "EmbedActionHandler" is "http://example.com:8443"; and the Origin for the "IntentActionHandler" is "http://example.net".

HTTP Action Handler

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

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 expects and returns attributes, HttpActionHandler objects support the following properties:

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.
Example HTTP Action Handler:
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note.",
  "actions": {
   "share": {
     "objectType": "HttpActionHandler",
     "url": "http://example.org/foo",
     "method": "POST"
   }
  }
}

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

If the HTTP request requires an input payload, the HttpActionHandler object can contain an expects property. The value of 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 HtmlForm 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 "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"
          }
        }
      }
    }
  }
}

When a Content Security Policy is in effect, invocation of the HTTP Action Handler is always governed by the "connect-src" directive defined in Section 3.2.5.3 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 "form-action" directive.

View Action Handler

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

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:

Property Value Description
target 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.
sandbox [[HTML5]] "sandbox" restrictions An optional string specifying [[HTML5]] sandbox restrictions that ought to be applied to the content referenced by the url property.
For example:
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note.",
  "actions": {
    "view": {
      "objectType": "ViewActionHandler",
      "url": "http://example.org/foo",
      "target": "_new"
    }
  }
}

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

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

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.

In other words, the following example:
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note.",
  "actions": {
    "view": {
      "objectType": "ViewActionHandler",
      "method": "GET",
      "url": {
        "objectType": "UrlTemplate",
        "template": "http://example.org/note/{noteid}",
        "parameters": {
          "noteid": {
            "type": "nonNegativeInteger",
            "totalDigits": 5
          }
        }
      }
    }
  }
}
Can, instead, be specified as:
{
  "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
        }
      }
    }
  }
}

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 "form_action" directive governs a View Action Handler that uses any method other than GET and whose input is an HTML Form.

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

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 url, content and 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. The content property is used to specify the embedded content directly within the Embed Action Handler. The mediaType 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:

Property Value Description
style Styles Value CSS styling hints to apply to the element containing the embedded content.
preview 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:

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

Alternatively, the embedded content can be referenced by URL:

Reference 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.

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. "image/png") 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.

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

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.

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 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.

Using "service" and "application"
{
  "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/..."
    }
  }
}

HTML Form Objects

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 value "HtmlForm".

In addition to the properties common to all Activity Streams objectTypes, HTML Form objects define the following additional properties:

Property Value Description
parameters Parameters Object Defines the HTML form parameters

For HTML Form objects, the mediaType property is used to identify the MIME media type used to encode the form data. The default value is assumed to be "application/x-www-form-urlencoded".

For example:
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note.",
  "actions": {
    "review": {
      "objectType": "ViewActionHandler",
      "method": "POST",
      "target": "_new",
      "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" target="_new">
  <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>

Typed Payload Objects

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 "TypedPayload".

In addition to the properties common to all objectTypes, Typed Payload objects define the following additional properties:

Property Value Description
type Type Value 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 mediaType attribute.
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.
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": "application/ld+json",
        "type": "http://xmlns.com/foaf/0.1/Person"
      }
    }
  }
}

URL Template Objects

The URL Template objectType is used to provide a description of an [[!RFC6570]] URL Template. The URL Template is identified using the objectType value "UrlTemplate".

In addition to the common properties support by all objectTypes, the URL Template object defines the following additional properties:

Property Value Description
template [[!RFC6570]] URL Template The URL Template
parameters Parameters Object Defines the URL Template parameters
For example:
{
  "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.

Parameters Object

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

Parameter Object

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:

Property Value Description
displayName Natural Language Value A Natural Language Value
required Boolean true if the parameter is required, false if it is optional. 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 supplied.
type [[!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 xsd:string.
enumeration 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.
minLength Non-Negative Integer Specifies the minimum unit of length for the value. The unit of length depends entirely on the value type as defined by the type property. For instance, for string, the length is determined by the number of encoded characters; for 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 defined by the type property. For instance, for string, the length is determined by the number of encoded characters; for 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 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 type is a number the step MUST conform to the specified type. For instance, if type is unsignedInt, then a step value of 2 would indicate acceptable values of 0, 2, 4, 6, and so on. If the type corresponds to a timestamp of any sort, the step is expressed as an RFC 3339 duration (e.g. a step of "PT1D" indicates that values are expressed in one day intervals). 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 is not numeric.
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 is not a numeric type. If specified, the fractionDigit MUST be equal to or less than the totalDigits property.
pattern String or Array of Strings One or more Regular Expressions that describe the acceptable structure of the value. Typically used when the value type is string. Multiple patterns are mutually exclusive options. That is, the value is expected to conform to at least one of the given patterns but is not required to conform to all of the patterns.
placeholder Natural Language Value A Natural Language Value providing a text hint describing the expected value of the parameter.
Using the Parameter Object in HTML Form 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
    }
  }
}

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 URL Template object MAY be used as the parameter description. In such cases, the required, repeated, default and placeholder properties from the Parameter object can be used as additional properties within the URL Template 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 Typed Payload objectType can be used.

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

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.

For example:
{
  "objectType": "note",
  "displayName": "A simple note object",
  "content": "This is a simple note",
  "actions": {
    "view": {
      "objectType": "ViewActionHandler",
      "method": "GET",
      "url": "http://example.org/notes/1",
      "target": "_new",
      "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.

Styles Object

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 media member can be included within the dictionary providing a CSS Media Query [[!CSS3-MEDIAQUERIES]].

For example:
{
  "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 can be specified for separate media query targets.

For example:
{
  "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"
        }
      ]
    }
  }
}

Security Considerations

TBD

Implementation

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.

Relationship to the HTML5 Commands Model

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 Browsing Context.

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 img, object and iframe elements.

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.

A Strawman WebIDL Interface for Action Handlers

readonly attribute InvokeHandler command
The callback function that implements the action
HTMLButtonElement asButton(optional dictionary? options)
Creates a HTML button whose onclick event handler triggers the command.
HTMLAnchorElement asAnchor(optional dictionary? options)
Creates a HTML anchor whose onclick event handler triggers the command.
HTMLMenuItemElement asMenuItem(optional dictionary? options)
Creates a HTML menuitem whose onclick event handler triggers the command.
[TreatNonCallableAsNull] attribute Function? onInputRequired
Called when invoking the Action Handler requires input to be provided. The invoked function's return value is used as the input.
[TreatNonCallableAsNull] attribute Function? onAuthRequired
Called when invoking the Action Handler requires authentication details to be provider. The invoked function's return value is used to provide the authentication detail.
[TreatNonCallableAsNull] attribute Function? onError
Called when an error occurs attempting to invoke the Action Handler.
[TreatNonCallableAsNull] attribute Function? onComplete
Called when invoking the Action Handler is complete and a result may or may not be available.

The events supported by the ActionCommand object include:

Event Handler
inputRequired onInputRequired
authRequired onAuthRequired
complete onComplete
error onError

Example

For example:
var actionHandler = {
  objectType: 'ViewActionHandler',
  displayName: 'Open!'
  url: 'http://example.org/foo',
  target: '_new'
};
var actionCommand = new ActionCommand(actionHandler);
var btn = actionCommand.asButton();
document.getElementById('container').appendChild(btn);
// btn will be an HTMLButtonElement with the text label "Open!"
// and an onclick event that triggers the actionHandler.command
// callback.