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.

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

This specification defines four specific base types of Action Handler:

• The HTTP Action Handler,
• The View Action Handler,
• The Embed Action Handler, and
• The Intent 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.

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

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:

• If the Action Handler contains a url property, 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.
• Otherwise, the Origin is derived from the Base URI of the Action Handler as determined by following the guidelines specified in Section 6.1 of the JSON-LD specification [[!JSON-LD]].

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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