One document matched: draft-snell-activitystreams-actions-06.xml
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc6570 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml'>
<!ENTITY rfc6454 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6454.xml'>
<!ENTITY as2 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-snell-activitystreams-07.xml'>
<!ENTITY xsd PUBLIC '' 'http://xml.resource.org/public/bibxml-w3c/reference.W3C.REC-xmlschema-2-20041028.xml'>
<!ENTITY html5 PUBLIC '' 'http://xml.resource.org/public/bibxml-w3c/reference.W3C.CR-html5-20140429.xml'>
<!ENTITY csp PUBLIC '' 'http://xml.resource.org/public/bibxml-w3c/reference.W3C.WD-CSP11-20140211.xml'>
<!ENTITY jsonld PUBLIC '' 'http://xml.resource.org/public/bibxml-w3c/reference.W3C.REC-json-ld-20140116.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-snell-activitystreams-actions-06" >
<front>
<title abbrev="ActivityStreams">JSON Activity Streams 2.0 - Action Handlers</title>
<author fullname="James M Snell" initials="J." surname="Snell">
<organization>IBM</organization>
<address>
<email>jasnell@gmail.com</email>
</address>
</author>
<author fullname="Matthew Marum" initials="M." surname="Marum">
<organization>SugarCRM</organization>
<address>
<email>mgmarum@gmail.com</email>
</address>
</author>
<date month="May" year="2014" />
<area>General</area>
<workgroup>Activity Streams (http://activitystrea.ms)</workgroup>
<keyword>JSON</keyword>
<keyword>Activity Streams</keyword>
<abstract>
<t>
This specification defines Action Handlers for use with
the Activity Streams 2.0 format.
</t>
</abstract>
<note title="Author's Note">
<t>
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.
</t>
</note>
</front>
<middle>
<section anchor="overview" title="Overview">
<t>
The Activity Streams 2.0 <xref target="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.
</t>
</section>
<section anchor="actionhandler" title="Action Handlers">
<t>
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:
</t>
<figure><artwork>
{
"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"
}
}
}
</artwork></figure>
<t>
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".
</t>
<t>
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:
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>confirm</c>
<c>Boolean</c>
<c>
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.
</c>
<c>context</c>
<c>JSON Object</c>
<c>
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.
</c>
<c>expects</c>
<c><xref target="I-D.snell-activitystreams">Link Value</xref></c>
<c>
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.
</c>
<c>returns</c>
<c><xref target="I-D.snell-activitystreams">Link Value</xref></c>
<c>
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.
</c>
<c>auth</c>
<c><xref target="authentication">Authentication Value</xref></c>
<c>
For action handlers with specific authentication requirements,
the "auth" property provides information about the specific
authentication mechanisms supported.
</c>
<c>requires</c>
<c><xref target="I-D.snell-activitystreams">Link Value</xref></c>
<c>
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.
</c>
<c>prefers</c>
<c><xref target="I-D.snell-activitystreams">Link Value</xref></c>
<c>
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.
</c>
</texttable>
<t>
This specification defines four specific base types of action
handler:
<list style="symbols">
<t><xref target="httpactionhandler">The HTTP Action Handler</xref>,</t>
<t><xref target="viewactionhandler">The View Action Handler</xref>,</t>
<t><xref target="embedactionhandler">The Embed Action Handler</xref>, and</t>
<t><xref target="intentactionhandler">The Intent Action Handler</xref>.</t>
</list>
</t>
<t>
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
<xref target="intentactionhandler">Intent Action Handlers</xref>.
</t>
<t>
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.
</t>
<t>
For example, in the following, the "share" action has two
associated action handlers:
</t>
<figure><artwork><![CDATA[
{
"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>"
}
]
}
}
]]></artwork></figure>
<section anchor="csp" title="Content Security Policy">
<t>
Note that all Action Handler types are subject to any relevant active
<xref target="W3C.WD-CSP11-20140211">Content Security Policy</xref>,
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.
</t>
<t>
Because the successful application of the Content Security Policy
depends on the ability to determine the <xref target="RFC6454">Origin</xref>
with which content is associated, the following rules for determining the
origin for an Action Handler apply:
<list>
<t>
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 <xref target="RFC6454"/>, Section 4.
</t>
<t>
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 <xref target="W3C.REC-json-ld-20140116">JSON-LD specification</xref>.
</t>
</list>
</t>
<t>
For instance, the example below illustrates an HTTP response carrying
an Activity Streams object with three separate Action Handlers, each
with a distinct Origin:
</t>
<figure><artwork>
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"
}
}
}
}
}
</artwork></figure>
<t>
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".
</t>
</section>
</section>
<section anchor="httpactionhandler" title="HTTP Action Handler">
<t>
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".
</t>
<t>
The defining characteristic of the HttpActionHandler is that the
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.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>url</c>
<c>Link Value</c>
<c>
Specifies the HTTP or HTTPS URL to which the HTTP request
is directed.
</c>
<c>method</c>
<c>HTTP Method String (e.g. "GET", "POST", "PUT", etc)</c>
<c>The HTTP method to use. Defaults to "GET"</c>
</texttable>
<figure><preamble>For example:</preamble><artwork>
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"share": {
"objectType": "HttpActionHandler",
"url": "http://example.org/foo",
"method": "POST"
}
}
}
</artwork></figure>
<t>
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 <xref target="urltemplate">UrlTemplate</xref> objectType
specifically intended for such use.
</t>
<t>
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:
</t>
<figure><artwork>
{
"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"
}
}
}
</artwork></figure>
<t>
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 <xref target="htmlform">HtmlForm</xref> objectType to be used
whenever the input of the HTTP request is an HTML Form POST. A new
<xref target="typedPayload">TypedPayload</xref> objectType is defined
for use whenever the input is an arbitrary MIME media type.
</t>
<t>
For example, the following describes an HTML Form post with a
single "foo" parameter submitted using the
"application/x-www-form-urlencoded" format:
</t>
<figure><artwork>
{
"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"
}
}
}
}
}
}
</artwork></figure>
<t>
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 <xref target="W3C.WD-CSP11-20140211"/>.
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 (Section 3.2.5.6).
</t>
</section>
<section anchor="viewactionhandler" title="View Action Handler">
<t>
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".
</t>
<t>
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.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>url</c>
<c>Link Value</c>
<c>
Specifies the HTTP or HTTPS URL to which the HTTP request
is directed.
</c>
<c>method</c>
<c>HTTP Method String (e.g. "GET", "POST", "PUT", etc)</c>
<c>The HTTP method to use. Defaults to "GET"</c>
<c>target</c>
<c>Browsing Context Name or Keyword</c>
<c>
Specifies the Browsing Context Name or keyword, as defined by
<xref target="W3C.CR-html5-20140429"/>, that will be
used when the action handler is invoked.
</c>
<c>sandbox</c>
<c>HTML5 "sandbox" restrictions</c>
<c>
An optional string specifying <xref target="W3C.CR-html5-20140429">HTML5</xref>
sandbox restrictions that ought to be applied to the content
referenced by the "url" property.
</c>
</texttable>
<figure><artwork>
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "ViewActionHandler",
"url": "http://example.org/foo",
"target": "_new"
}
}
}
</artwork></figure>
<t>
As a shortcut, ViewActionHandlers that use the "GET" method
can be specified using a JSON string containing the absolute URL.
For instance:
</t>
<figure><artwork>
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": "http://example.org/foo"
}
}
</artwork></figure>
<t>
In such cases, the "target" property is assumed to be unspecified.
</t>
<t>
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.
</t>
<t>
In other words, the following example:
</t>
<figure><artwork>
{
"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
}
}
}
}
}
}
</artwork></figure>
<t>
Can, instead, be specified as:
</t>
<figure><artwork>
{
"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
}
}
}
}
}
</artwork></figure>
<t>
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.
</t>
</section>
<section anchor="embedactionhandler" title="Embed Action Handler">
<t>
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".
</t>
<t>
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).
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>url</c>
<c>Link Value</c>
<c>
The URL from which to retrieve the content for this embed.
</c>
<c>content</c>
<c>String</c>
<c>
The character based "static" content to be embeded. The "mediaType"
parameter specifies the MIME media type of the content.
</c>
<c>mediaType</c>
<c>MIME Media Type</c>
<c>The MIME Media Type of the embedded content.</c>
<c>style</c>
<c><xref target="stylesobject">Styles Object</xref></c>
<c>
Visual CSS styling hints to apply to the element containing
the embedded content.
</c>
<c>preview</c>
<c>Link Value</c>
<c>
A reference to a "preview" representation of the embedded
content. Typically, this would a URL to a thumbnail or
screenshot image of the content.
</c>
<c>sandbox</c>
<c>HTML5 "sandbox" restrictions</c>
<c>
An optional string specifying <xref target="W3C.CR-html5-20140429">HTML5</xref>
sandbox restrictions that ought to be applied to the content
referenced by the "url" property.
</c>
</texttable>
<t>
In the following example, the "view" action is associated with
an "EmbedActionHandler" containing a static fragment of HTML
markup:
</t>
<figure><artwork><![CDATA[
{
"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"
}
}
}
]]></artwork></figure>
<t>
Alternatively, the embedded content can be referenced by URL:
</t>
<figure><artwork>
{
"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"
}
}
}
</artwork></figure>
<t>
The mediaType parameter specifies the type of content to be
embedded. Consuming applications MAY ignore Embed Action Handlers
that specify unrecognized or unsupported mediaTypes.
</t>
<figure><preamble>Example:</preamble><artwork>
{
"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"
}
}
}
</artwork></figure>
<t>
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.
</t>
<t>
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
<xref target="W3C.WD-CSP11-20140211">Content Security Policy</xref>
specification for a detailed explanation of each of the directives
that may apply.
</t>
</section>
<section anchor="intentactionhandler" title="Intent Action Handler">
<t>
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".
</t>
<figure><preamble>For example:</preamble><artwork>
{
"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
}
}
}
}
</artwork></figure>
<t>
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.
</t>
</section>
<section anchor="serviceapplication" title="Using "service" and "application" objects as action handlers">
<t>
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. When such objectTypes are used
as actions handlers, they are to be treated as specializations
of Intent Action Handler.
</t>
<t>
For example:
</t>
<figure><artwork>
{
"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/..."
}
}
}
</artwork></figure>
</section>
<section anchor="htmlform" title="HTML Form Objects">
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>mediaType</c>
<c>MIME Media Type</c>
<c>Defaults to "application/x-www-form-urlencoded"</c>
<c>parameters</c>
<c><xref target="parameters">Parameters Object</xref></c>
<c>Defines the HTML form parameters.</c>
</texttable>
<figure><preamble>For example:</preamble><artwork>
{
"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"
}
}
}
}
}
}
</artwork></figure>
<t>Is roughly equivalent to the following HTML form:</t>
<figure><artwork><![CDATA[
<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>
]]></artwork></figure>
</section>
<section anchor="typedPayload" title="Typed Payload Objects">
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>mediaType</c>
<c>MIME Media Type</c>
<c>The MIME Media Type of the Payload</c>
<c>type</c>
<c><xref target="I-D.snell-activitystreams">Type Value</xref></c>
<c>
An optional Type Value that describes the payloads semantic type.
</c>
<c>schema</c>
<c><xref target="I-D.snell-activitystreams">Link Value</xref></c>
<c>
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.
</c>
</texttable>
<figure><preamble>For example:</preamble><artwork>
{
"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",
}
}
}
}
</artwork></figure>
</section>
<section anchor="urltemplate" title="URL Template Objects">
<t>
Objects with the "UrlTemplate" object type represent
<xref target="RFC6570"/> URL Templates.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>template</c>
<c>URL Template</c>
<c>The <xref target="RFC6570"/> URL Template</c>
<c>parameters</c>
<c><xref target="parameters">Parameters Object</xref></c>
<c>Defines the URL Template parameters</c>
</texttable>
<figure><artwork>
{
"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
}
}
}
}
}
</artwork></figure>
<t>
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.
</t>
</section>
<section anchor="parameters" title="Parameters Object">
<t>
A Parameters Object is used to provide descriptions of the variable
inputs of objects such as <xref target="htmlform">HTML Forms</xref>
and <xref target="urltemplate">URL Templates</xref>. The object is
expressed as a JSON dictionary mapping parameter names to
parameter descriptions which take the form of either an
<xref target="W3C.REC-xmlschema-2-20041028">XML Schema type name</xref>,
an absolute IRI, a <xref target="ParameterObject">parameter object</xref>,
or in some limited cases, TypedPayload or UrlTemplate objects.
</t>
<t>
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.
</t>
<figure><preamble>Using the Parameters Object in UrlTemplate objects:</preamble><artwork>
{
"objectType": "UrlTemplate",
"template": "http://example.org{/foo,bar}"
"parameters": {
"foo": "string",
"bar": {
"type": "string",
"required": false
}
}
}
</artwork></figure>
<t>
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.
</t>
<figure><preamble>Using the Parameters Object in HtmlForm objects:</preamble><artwork>
{
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": {
"displayName": "Foo",
"type": "string"
},
"bar": {
"displayName": "Bar",
"type": "string",
"required": false
}
}
}
</artwork></figure>
<section anchor="ParameterObject" title="The Parameter Object">
<t>
Parameter objects provide a rich description of a single parameter
in a manner that is aligned with the commonly used
<xref target="W3C.REC-xmlschema-2-20041028">XML Schema type system</xref>.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>Value</ttcol>
<ttcol>Description</ttcol>
<c>displayName</c>
<c><xref target="I-D.snell-activitystreams">Natural Language Value</xref></c>
<c>An Activity Streams 2.0 Natural Language Value.</c>
<c>required</c>
<c>boolean</c>
<c>True if the parameter is required. Defaults to true.</c>
<c>repeated</c>
<c>boolean</c>
<c>True if the parameter can be repeated zero or more times. Defaults to false.</c>
<c>value</c>
<c>(Any)</c>
<c>
Provides a fixed value for the parameter. When specified,
implementations MUST use the specified value.
</c>
<c>default</c>
<c>(Any)</c>
<c>
Provides a default value for the parameter. When specified,
implementations MUST use the specified value if no other
value is not supplied.
</c>
<c>type</c>
<c><xref target="W3C.REC-xmlschema-2-20041028">XSD</xref> type name or IRI</c>
<c>
Identifies the value type using either an
<xref target="W3C.REC-xmlschema-2-20041028">XML Schema</xref> 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".
</c>
<c>enumeration</c>
<c>Array of (Any)</c>
<c>
Provides a fixed array of possible values for the parameter.
When specified, implementations MUST use one of the specified
values.
</c>
<c>minLength</c>
<c>Non-Negative Integer</c>
<c>
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.
</c>
<c>maxLength</c>
<c>Non-Negative Integer</c>
<c>
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.
</c>
<c>maxInclusive</c>
<c>(Any)</c>
<c>
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.
</c>
<c>maxExclusive</c>
<c>(Any)</c>
<c>
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.
</c>
<c>minInclusive</c>
<c>(Any)</c>
<c>
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.
</c>
<c>minExclusive</c>
<c>(Any)</c>
<c>
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.
</c>
<c>step</c>
<c>Non-negative Number</c>
<c>
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.
</c>
<c>totalDigits</c>
<c>Non-negative integer</c>
<c>
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.
</c>
<c>fractionDigits</c>
<c>Non-negative integer</c>
<c>
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.
</c>
<c>pattern</c>
<c>String or Array of Strings</c>
<c>
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.
</c>
<c>placeholder</c>
<c><xref target="I-D.snell-activitystreams">Natural Language Value</xref></c>
<c>
An optional Natural Language Value providing a text hint that
describes the expected value of the parameter.
</c>
</texttable>
<figure><preamble>Using the Parameter Object in HtmlForm objects:</preamble><artwork>
{
"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
}
}
}
</artwork></figure>
</section>
<section anchor="urltemplateparameters" title="Using UrlTemplate and TypedPayload objects as parameter descriptions">
<t>
In certain cases, when the value of a parameter is expected to be
either a URI or IRI, the <xref target="urltemplate">UrlTemplate
objectType</xref> MAY be used as the parameter description. In
such cases, the "required", "repeated", "default"
and "placeholder" properties from the <xref target="ParameterObject">
Parameter objectType</xref> can be used as additional properties
within the UrlTemplate object.
</t>
<t>
For example:
</t>
<figure><artwork>
{
"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
}
}
}
</artwork></figure>
<t>
Likewise, when the value of a parameter is expected to be an instance
of a specific MIME media type, the <xref target="typedPayload">TypedPayload
objectType</xref> can be used.
</t>
<figure><artwork>
{
"objectType": "HtmlForm",
"mediaType": "multipart/form-data",
"parameters": {
"file": {
"objectType": "TypedPayload",
"mediaType": "image/*",
"repeated": true
}
}
}
</artwork></figure>
</section>
</section>
<section anchor="authentication" title="Authentication Object">
<t>
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.
</t>
<figure><preamble>Example Authentication details:</preamble><artwork>
{
"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"
]
}
}
}
}
}
</artwork></figure>
<t>
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.
</t>
</section>
<section anchor="stylesobject" title="Styles Object">
<t>
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.
</t>
<figure><preamble>Example style hints:</preamble><artwork>
{
"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"
}
}
}
}
</artwork></figure>
<figure><preamble>Multiple style hints for specific media query targets:</preamble><artwork>
{
"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"
}
]
}
}
}
</artwork></figure>
</section>
<section anchor="security" title="Security Considerations">
<t>TBD</t>
</section>
<section anchor="iana" title="IANA Considerations">
<t>TBD</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc6570;
&rfc6454;
&as2;
&html5;
&csp;
&xsd;
&jsonld;
</references>
<section anchor="othervocabs" title="Using Action Handlers From Other Vocabularies">
<t>
The Activity Streams 2.0 Actions mechanism is specifically designed
to allow Action Handlers from multiple vocabularies.
</t>
<section title="Schema.org Actions Proposal">
<t>Based on http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf:</t>
<figure><artwork>
{
"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"
}
]
}
}
</artwork></figure>
</section>
<section title="Google's "Actions in the Inbox"">
<t>Based on https://developers.google.com/gmail/actions/reference/review-action:</t>
<figure><artwork>
{
"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"
}
}
}
}
</artwork></figure>
</section>
<section title="Mixing Vocabularies">
<figure><artwork>
{
"objectType": "video",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"watch": [
{
"objectType": "ViewActionHandler",
"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"
}
]
}
}
</artwork></figure>
</section>
<section title="Example Drawing From Multiple Vocabularies">
<figure><artwork>
{
"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": "ViewActionHandler",
"displayName": "Twitter",
"url": "https://twitter.com/share?url=...",
"target": "dialog"
},
{
"objectType": "ViewActionHandler",
"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
}
}
}
}
}
}
</artwork></figure>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 05:24:26 |