JSON Activity Streams 2.0 - Action Handlers
draft-snell-activitystreams-actions-05
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Authors | James M. Snell , Matthew Marum | ||
| Last updated | 2014-05-01 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-snell-activitystreams-actions-05
Activity Streams (http://activitystrea.ms) J. Snell
Internet-Draft IBM
Intended status: Standards Track M. Marum
Expires: November 2, 2014 SugarCRM
May 1, 2014
JSON Activity Streams 2.0 - Action Handlers
draft-snell-activitystreams-actions-05
Abstract
This specification defines Action Handlers for use with the Activity
Streams 2.0 format.
Author's Note
Note that this document is a work-in-progress draft specification
that does not yet represent a "standard". It is the intention of
this specification to propose a few new ideas and openly solicit
feedback on their definition and use. While this document might
eventually evolve into an RFC the ideas described herein have not yet
been broadly implemented and have definitions that will evolve
through successive iterations of this draft.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 2, 2014.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
Snell & Marum Expires November 2, 2014 [Page 1]
Internet-Draft ActivityStreams May 2014
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Action Handlers . . . . . . . . . . . . . . . . . . . . . . . 3
3. HTTP Action Handler . . . . . . . . . . . . . . . . . . . . . 6
4. Embed Action Handler . . . . . . . . . . . . . . . . . . . . 10
5. Intent Action Handler . . . . . . . . . . . . . . . . . . . . 12
6. Using "service" and "application" objects as action handlers 13
7. HTML Form Objects . . . . . . . . . . . . . . . . . . . . . . 14
8. Typed Payload Objects . . . . . . . . . . . . . . . . . . . . 15
9. URL Template Objects . . . . . . . . . . . . . . . . . . . . 16
10. Parameters Object . . . . . . . . . . . . . . . . . . . . . . 17
10.1. The Parameter Object . . . . . . . . . . . . . . . . . . 18
10.2. Using UrlTemplate and TypedPayload objects as parameter
descriptions . . . . . . . . . . . . . . . . . . . . . . 22
11. Authentication Object . . . . . . . . . . . . . . . . . . . . 23
12. Styles Object . . . . . . . . . . . . . . . . . . . . . . . . 24
13. Security Considerations . . . . . . . . . . . . . . . . . . . 26
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
15. Normative References . . . . . . . . . . . . . . . . . . . . 26
Appendix A. Using Action Handlers From Other Vocabularies . . . 26
A.1. Schema.org Actions Proposal . . . . . . . . . . . . . . . 26
A.2. Google's "Actions in the Inbox" . . . . . . . . . . . . . 27
A.3. Mixing Vocabularies . . . . . . . . . . . . . . . . . . . 28
A.4. Example Drawing From Multiple Vocabularies . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
1. Overview
The Activity Streams 2.0 [I-D.snell-activitystreams] specification
introduces the notion of "actions" that can be associated with
objects. Using the "actions" property described in Sections 3.6 and
3.6.1 of the Activity Streams 2.0 document, the producer of an object
can declare a specific set of verbs appropriate for the object and
map each of those to one or more objects ("action handlers") or
resources capable of "carrying out" the verb. This document expands
on that mechanism by defining and describing a core set of action
handler object types.
Snell & Marum Expires November 2, 2014 [Page 2]
Internet-Draft ActivityStreams May 2014
2. Action Handlers
An action handler is an Activity Streams 2.0 object whose objectType
and member properties instruct a consuming application how to carry
out the verb the action handler has been associated with. For
instance, given the following example:
{
"objectType": "note",
"displayName": "Title of the note",
"content": "This is a simple note.",
"actions": {
"share": {
"objectType": "HttpActionHandler",
"url": "http://example.org/share"
},
"like": {
"objectType": "EmbedActionHandler",
"mediaType": "text/plain",
"content": "Hello World"
}
}
}
The "note" object has two declared actions, "share" and "like". Each
of those is associated with one action handler object. The "share"
action has a action handler of type "HttpActionHandler", while the
"like" action has an "EmbedActionHandler".
As illustrated in the example, action handlers are represented as
Activity Streams 2.0 objects. All such objects share a common set of
base member properties as defined in the following table:
+----------+-----------------------------+--------------------------+
| Property | Value | Description |
+----------+-----------------------------+--------------------------+
| confirm | Boolean | True if the consuming |
| | | application ought to |
| | | seek confirmation prior |
| | | to using the action |
| | | handler to carry out |
| | | it's associated action. |
| | | Defaults to False. |
| context | JSON Object | Contextual information |
| | | associated with the |
| | | action handler, |
| | | represented as a JSON |
| | | Object without any |
Snell & Marum Expires November 2, 2014 [Page 3]
Internet-Draft ActivityStreams May 2014
| | | particular structure. |
| | | How the context is used |
| | | is dependent entirely on |
| | | the action handler |
| | | definition and on how a |
| | | consuming application |
| | | chooses to implement the |
| | | action handler. |
| expects | Link Value | For action handlers with |
| | [I-D.snell-activitystreams] | a distinct input |
| | | requirement (e.g. |
| | | HttpActionHandler), the |
| | | expects property |
| | | provides a description |
| | | of the expected input. |
| | | The value is expressed |
| | | as either a String |
| | | containing a fully |
| | | qualified IRI, an |
| | | Activity Stream Object, |
| | | or an Array of IRI's or |
| | | Objects. When multiple |
| | | values are provided, |
| | | they MUST be considered |
| | | as mutually exclusive |
| | | alternatives. |
| returns | Link Value | For action handlers with |
| | [I-D.snell-activitystreams] | a distinct output, the |
| | | returns property |
| | | provides a description |
| | | of the expected output. |
| | | The value is expressed |
| | | as either a String |
| | | containing a fully |
| | | qualified IRI, an |
| | | Activity Stream Object, |
| | | or an Array of IRI's or |
| | | Objects. When multiple |
| | | values are provided, |
| | | they MUST be considered |
| | | as mutually exclusive |
| | | alternatives. |
| auth | Authentication Value | For action handlers with |
| | (Section 11) | specific authentication |
| | | requirements, the "auth" |
| | | property provides |
| | | information about the |
| | | specific authentication |
Snell & Marum Expires November 2, 2014 [Page 4]
Internet-Draft ActivityStreams May 2014
| | | mechanisms supported. |
| requires | Link Value | An optional Link Value |
| | [I-D.snell-activitystreams] | whose value(s) describe |
| | | features or behaviors an |
| | | implementation MUST |
| | | support in order to |
| | | carry out the action. |
| | | Requirements are |
| | | designed to be |
| | | intentionally open-ended |
| | | and will vary depending |
| | | on specific Action |
| | | Handler type. Any |
| | | implementation that does |
| | | not support any |
| | | specified required |
| | | feature MUST ignore the |
| | | Action Handler. |
| prefers | Link Value | An optional Link Value |
| | [I-D.snell-activitystreams] | whose value(s) describe |
| | | features or behaviors an |
| | | implementation SHOULD |
| | | support in order to |
| | | carry out the action. |
| | | Requirements are |
| | | designed to be |
| | | intentionally open-ended |
| | | and will vary depending |
| | | on specific Action |
| | | Handler type. Any |
| | | implementation that does |
| | | not support any |
| | | specified preferred |
| | | feature MAY ignore the |
| | | feature. |
+----------+-----------------------------+--------------------------+
This specification defines three specific base types of action
handler:
o The HTTP Action Handler (Section 3),
o The Embed Action Handler (Section 4), and
o The Intent Action Handler (Section 5).
Implementations are free to use Activity Stream objects of any
objectType as an action handler. Consuming applications MAY ignore
Snell & Marum Expires November 2, 2014 [Page 5]
Internet-Draft ActivityStreams May 2014
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
(Section 5).
Multiple independent action handlers can be associated with any
single verb using a JSON Array. The ordering of objects within such
an array is not considered to be significant.
For example, in the following, the "share" action has two associated
action handlers:
{
"objectType": "event",
"displayName": "Party!",
"content": "We're going to party like it's 1999!",
"id": "urn:example:events:123",
"actions": {
"share": [
{
"objectType": "HttpActionHandler",
"method": "POST",
"url": "http://example.org/share-this/123",
"target": "DIALOG",
"returns": {
"objectType": "TypedPayload",
"mediaType": "text/html"
}
},
{
"objectType": "EmbedActionHandler",
"mediaType": "text/html",
"content": "<div>...</div>"
}
]
}
}
3. HTTP Action Handler
An HTTP Action Handler describes an HTTP request/response flow that
is used to carry out an action. It is identified using an objectType
value of "HttpActionHandler".
Snell & Marum Expires November 2, 2014 [Page 6]
Internet-Draft ActivityStreams May 2014
+----------+-----------------------------------+--------------------+
| 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", | The HTTP method to |
| | "POST", "PUT", etc) | use. Defaults to |
| | | "GET" |
| target | "DEFAULT" - Consumer defined | Specifies the |
| | default; "NONE" - No navigation | intended target of |
| | or UI context (e.g. a hidden HTTP | the HTTP action. |
| | action that does not result in | This determines |
| | the creation or use of a browser | whether the action |
| | window); "NEW" - A new navigation | results in a new |
| | or UI context (e.g. show the | navigation context |
| | results of the HTTP request in a | (e.g. new browser |
| | browser window or tab.); | window) or whether |
| | "CURRENT" - Reuse the existing | the action is |
| | navigation or UI context (e.g. | "hidden". When not |
| | show the results of the HTTP | specified, |
| | request in an existing browser | defaults to |
| | window or tab.); {Other token | "DEFAULT", meaning |
| | value} - Any other TOKEN value. | that the consuming |
| | Interpretation and support of | application is |
| | such extension tokens is | free to determine |
| | dependent on the consuming | an appropriate |
| | application. Unknown or | target context. |
| | unsupported values MUST be | |
| | ignored. | |
+----------+-----------------------------------+--------------------+
For example:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "HttpActionHandler",
"url": "http://example.org/foo",
"method": "GET"
}
}
}
Snell & Marum Expires November 2, 2014 [Page 7]
Internet-Draft ActivityStreams May 2014
As a shortcut, HttpActionHandlers that use the "GET" method and a
"DEFAULT" target can be specified using a JSON string containing the
absolute URL. For instance:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": "http://example.org/foo"
}
}
In the Activity Streams 2.0 format, the "url" property is defined as
a "Link Value", this means that it is possible for the value of the
"url" property to be an Activity Stream object that a consuming
application can use to resolve the actual target URL. This
specification defines a new UrlTemplate (Section 9) objectType
specifically intended for such use.
The UrlTemplate object can be used within an HTTP Action Handler, for
instance, whenever carrying out the HTTP request requires the
construction of a new URL that includes variable parameters:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"review": {
"objectType": "HttpActionHandler",
"url": {
"objectType": "UrlTemplate",
"template": "http://example.org/note/123{?rating}",
"parameters": {
"rating": {
"displayName": "Rating",
"maxInclusive": 5,
"minInclusive": 1,
"type": "unsignedInt"
}
}
},
"method": "POST",
"target": "NEW"
}
}
}
Snell & Marum Expires November 2, 2014 [Page 8]
Internet-Draft ActivityStreams May 2014
If the intended HTTP request uses the GET method and DEFAULT target,
the UrlTemplate object itself can be used directly as the action
handler.
"GET" HttpActionHandler shortcut using a URL Template:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "UrlTemplate",
"template": "http://example.org/note/{noteid}",
"parameters": {
"noteid": {
"type": "nonNegativeInteger",
"totalDigits": 5
}
}
}
}
}
If the HTTP request requires an input payload, the HttpActionHandler
object can contain an "expects" property. The value of "expects" is
an Activity Streams 2.0 "Link Value" represented either as a simple
JSON string containing a fully qualified IRI, an Activity Stream
object, or an array of IRI's or Objects. This specification defines
a new HtmlForm (Section 7) objectType to be used whenever the input
of the HTTP request is an HTML Form POST. A new TypedPayload
(Section 8) 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:
Snell & Marum Expires November 2, 2014 [Page 9]
Internet-Draft ActivityStreams May 2014
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"share": {
"objectType": "HttpActionHandler",
"method": "POST",
"url": "http://example.org/foo",
"expects": {
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": {
"type": "string",
"displayName": "Foo Property"
}
}
}
}
}
}
4. Embed Action Handler
An Embed Action Handler defines static or dynamic content to be
visually rendered to carry out an action. Examples of embeds can
include static HTML, images, videos, gadgets and applications. It is
identified using an objectType value of "EmbedActionHandler".
Snell & Marum Expires November 2, 2014 [Page 10]
Internet-Draft ActivityStreams May 2014
+-----------+--------------+----------------------------------------+
| Property | Value | Description |
+-----------+--------------+----------------------------------------+
| url | Link Value | The URL from which to retrieve the |
| | | content for this embed. |
| content | String | The character based "static" content |
| | | to be embeded. The "mediaType" |
| | | parameter specifies the MIME media |
| | | type of the content. |
| mediaType | MIME Media | The MIME Media Type of the embedded |
| | Type | content. |
| style | Styles | Visual CSS styling hints to apply to |
| | Object | the element containing the embedded |
| | (Section 12) | content. |
| preview | Link Value | A reference to a "preview" |
| | | representation of the embedded |
| | | content. Typically, this would a URL |
| | | to a thumbnail or screenshot image of |
| | | the content. |
| target | "DEFAULT"; | |
| | "INLINE"; | |
| | {Other token | |
| | value} | |
+-----------+--------------+----------------------------------------+
In the following example, the "view" action is associated with an
"EmbedActionHandler" containing a static fragment of HTML markup:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "EmbedActionHandler",
"content": "<div>This is some bit of embedded HTML</div>",
"mediaType": "text/html",
"style": {
"height": "100px",
"width": "100px",
"box-shadow": "10px 10px 5px #888888"
},
"displayName": "Some embedded content",
"preview": "http://example.org/preview/123.jpg"
}
}
}
Snell & Marum Expires November 2, 2014 [Page 11]
Internet-Draft ActivityStreams May 2014
Alternatively, the embedded content can be referenced by URL:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "EmbedActionHandler",
"url": "http://example.org/foo",
"mediaType": "text/html"
}
}
}
The mediaType parameter specifies the type of content to be embedded.
Consuming applications MAY ignore Embed Action Handlers that specify
unrecognized or unsupported mediaTypes.
Example:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "EmbedActionHandler",
"url": "http://example.org/foo.mpg",
"mediaType": "video/mpeg"
}
}
}
5. Intent Action Handler
An Intent Action Handler provides a generic way for the publisher of
an Activity object to tell the consuming application to figure out
how to handle the action on it's own. The consumer can, for
instance, pass the object off to some other native platform
application. It is identified using an objectType value of
"IntentActionHandler".
Snell & Marum Expires November 2, 2014 [Page 12]
Internet-Draft ActivityStreams May 2014
For example:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"share": {
"objectType": "IntentActionHandler",
"displayName": "Share This",
"context": {
"foo": "ABC",
"bar": 123
}
}
}
}
6. Using "service" and "application" objects as action handlers
The "service" and "application" object are existing objectTypes
defined by the Activity Streams 1.0 core schema. While these objects
were not originally designed to be used as action handlers, they can
be. Specifically, the "service" objectType can be used when the
action is to be carried out using some specific third party service
interface; the "application" objectType can be used when the action
is to be carried out by deferring some some specific native platform
application.
For example:
Snell & Marum Expires November 2, 2014 [Page 13]
Internet-Draft ActivityStreams May 2014
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"share": {
"objectType": "service",
"displayName": "My Sharing Service",
"url": "http://share.example.org/api"
},
"save": {
"objectType": "application",
"displayName": "Read this later!",
"platform": "android",
"id": "123",
"url": "http://play.google.com/..."
}
}
}
7. HTML Form Objects
+------------+----------------+-------------------------------------+
| Property | Value | Description |
+------------+----------------+-------------------------------------+
| mediaType | MIME Media | Defaults to "application/x-www- |
| | Type | form-urlencoded" |
| parameters | Parameters | Defines the HTML form parameters. |
| | Object | |
| | (Section 10) | |
+------------+----------------+-------------------------------------+
Snell & Marum Expires November 2, 2014 [Page 14]
Internet-Draft ActivityStreams May 2014
For example:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"review": {
"objectType": "HttpActionHandler",
"method": "POST",
"url": "http://example.org/foo",
"expects": {
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": {
"displayName": "Foo",
"type": "string",
"placeholder": "Foo"
},
"bar": {
"type": "string",
"value": "Provided Value"
}
}
}
}
}
}
Is roughly equivalent to the following HTML form:
<form method="post" action="http://example.org/foo">
<label for="foo">Foo:</label>
<input id="foo" name="foo" type="input" placeholder="Foo" />
<input name="bar" type="hidden" value="Provided Value" />
<input type="submit" />
</form>
8. Typed Payload Objects
Snell & Marum Expires November 2, 2014 [Page 15]
Internet-Draft ActivityStreams May 2014
+-----------+-----------------------------+-------------------------+
| Property | Value | Description |
+-----------+-----------------------------+-------------------------+
| mediaType | MIME Media Type | The MIME Media Type of |
| | | the Payload |
| type | Type Value | An optional Type Value |
| | [I-D.snell-activitystreams] | that describes the |
| | | payloads semantic type. |
| schema | Link Value | An optional Link Value |
| | [I-D.snell-activitystreams] | whose value(s) describe |
| | | the structure of the |
| | | payload data. The value |
| | | is represented either |
| | | as a String with a |
| | | fully qualified IRI, an |
| | | Activity Stream object, |
| | | or an Array of IRIs and |
| | | Objects. If multiple |
| | | values are provided, |
| | | they are to be |
| | | considered mutually |
| | | exclusive alternatives. |
+-----------+-----------------------------+-------------------------+
For example:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"review": {
"objectType": "HttpActionHandler",
"method": "POST",
"url": "http://example.org/foo",
"expects": {
"objectType": "TypedPayload",
"mediaType": "text/json",
}
}
}
}
9. URL Template Objects
Objects with the "UrlTemplate" object type represent [RFC6570] URL
Templates.
Snell & Marum Expires November 2, 2014 [Page 16]
Internet-Draft ActivityStreams May 2014
+------------+-------------------------+----------------------------+
| Property | Value | Description |
+------------+-------------------------+----------------------------+
| template | URL Template | The [RFC6570] URL Template |
| parameters | Parameters Object | Defines the URL Template |
| | (Section 10) | parameters |
+------------+-------------------------+----------------------------+
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"review": {
"objectType": "UrlTemplate",
"template": "http://example.org/notes/{noteid}",
"parameters": {
"noteid": {
"type": "nonNegativeInteger",
"totalDigits": 5
}
}
}
}
}
If the given URL template includes any parameter tokens that do not
appear within the "parameters" property, the parameter value type is
assumed to be a UTF-8 encoded xsd:string with no maximum length.
10. Parameters Object
A Parameters Object is used to provide descriptions of the variable
inputs of objects such as HTML Forms (Section 7) and URL Templates
(Section 9). The object is expressed as a JSON dictionary mapping
parameter names to parameter descriptions which take the form of
either an XML Schema type name [W3C.REC-xmlschema-2-20041028], an
absolute IRI, a parameter object (Section 10.1), or in some limited
cases, TypedPayload or UrlTemplate objects.
By default, all parameters are assumed to be required. When a
parameter is described using an object, the object MAY contain a
boolean "required" member. If "required" is false, use of the
parameter is assumed to be optional.
Snell & Marum Expires November 2, 2014 [Page 17]
Internet-Draft ActivityStreams May 2014
Using the Parameters Object in UrlTemplate objects:
{
"objectType": "UrlTemplate",
"template": "http://example.org{/foo,bar}"
"parameters": {
"foo": "string",
"bar": {
"type": "string",
"required": false
}
}
}
In this example, both the "foo" and "bar" parameter conform to the
XML Schema type "xsd:string". The "foo" parameter is required while
the "bar" parameter is optional.
Using the Parameters Object in HtmlForm objects:
{
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": {
"displayName": "Foo",
"type": "string"
},
"bar": {
"displayName": "Bar",
"type": "string",
"required": false
}
}
}
10.1. The Parameter Object
Parameter objects provide a rich description of a single parameter in
a manner that is aligned with the commonly used XML Schema type
system [W3C.REC-xmlschema-2-20041028].
+-------------+--------------------------+--------------------------+
| Property | Value | Description |
+-------------+--------------------------+--------------------------+
| displayName | Natural Language Value [ | An Activity Streams 2.0 |
| | I-D.snell-activitystream | Natural Language Value. |
| | s] | |
Snell & Marum Expires November 2, 2014 [Page 18]
Internet-Draft ActivityStreams May 2014
| required | boolean | True if the parameter is |
| | | required. Defaults to |
| | | true. |
| repeated | boolean | True if the parameter |
| | | can be repeated zero or |
| | | more times. Defaults to |
| | | false. |
| value | (Any) | Provides a fixed value |
| | | for the parameter. When |
| | | specified, |
| | | implementations MUST use |
| | | the specified value. |
| default | (Any) | Provides a default value |
| | | for the parameter. When |
| | | specified, |
| | | implementations MUST use |
| | | the specified value if |
| | | no other value is not |
| | | supplied. |
| type | XSD [W3C.REC-xmlschema-2 | Identifies the value |
| | -20041028] type name or | type using either an XML |
| | IRI | Schema [W3C.REC-xmlschem |
| | | a-2-20041028] simple |
| | | type name or an absolute |
| | | IRI. If an |
| | | implementation |
| | | encounters a type it |
| | | does not recognize, the |
| | | property MAY be ignored. |
| | | When not specified, the |
| | | value type is assumed to |
| | | be a UTF-8 encoded |
| | | "xsd:string". |
| enumeration | Array of (Any) | Provides a fixed array |
| | | of possible values for |
| | | the parameter. When |
| | | specified, |
| | | implementations MUST use |
| | | one of the specified |
| | | values. |
| minLength | Non-Negative Integer | Specifies the minimum |
| | | "unit of length" for the |
| | | value. The "unit of |
| | | length" depends entirely |
| | | on the value type as |
| | | specified by the "type" |
| | | property. For instance, |
| | | For xsd:string, the |
Snell & Marum Expires November 2, 2014 [Page 19]
Internet-Draft ActivityStreams May 2014
| | | length is determined by |
| | | the number of |
| | | characters; for |
| | | xsd:hexBinary, the |
| | | length is determined by |
| | | the number of encoded |
| | | 8-bit octets. |
| maxLength | Non-Negative Integer | Specifies the maximum |
| | | "unit of length" for the |
| | | value. The "unit of |
| | | length" depends entirely |
| | | on the value type as |
| | | specified by the "type" |
| | | property. For instance, |
| | | For xsd:string, the |
| | | length is determined by |
| | | the number of |
| | | characters; for |
| | | xsd:hexBinary, the |
| | | length is determined by |
| | | the number of encoded |
| | | 8-bit octets. |
| maxInclusiv | (Any) | A value that is |
| e | | considered to be the |
| | | inclusive upper bound of |
| | | a range of possible |
| | | values. This would |
| | | typically be used only |
| | | with numeric parameters. |
| maxExclusiv | (Any) | A value that is |
| e | | considered to be the |
| | | exclusive upper bound of |
| | | a range of possible |
| | | values. This would |
| | | typically be used only |
| | | with numeric parameters. |
| minInclusiv | (Any) | A value that is |
| e | | considered to be the |
| | | inclusive lower bound of |
| | | a range of possible |
| | | values. This would |
| | | typically be used only |
| | | with numeric parameters. |
| minExclusiv | (Any) | A value that is |
| e | | considered to be the |
| | | exclusive lower bound of |
| | | a range of possible |
| | | values. This would |
Snell & Marum Expires November 2, 2014 [Page 20]
Internet-Draft ActivityStreams May 2014
| | | typically be used only |
| | | with numeric parameters. |
| step | Non-negative Number | Specifies the legal |
| | | numeric interval between |
| | | acceptable values for |
| | | the parameter. The step |
| | | value MUST be a number |
| | | and MUST conform to the |
| | | specified type. For |
| | | instance, if type is |
| | | "unsignedInt", then |
| | | step=2 would indicate |
| | | legal values of 0, 2, 4, |
| | | 6, and so on. The step |
| | | property MAY be ignored |
| | | if it's value does not |
| | | correspond to the |
| | | expected type. |
| totalDigits | Non-negative integer | Specifies the maximum |
| | | number of digits |
| | | (integer and fractional) |
| | | that can be included in |
| | | numeric values. The |
| | | totalDigits property |
| | | MUST be ignored if the |
| | | value type identified by |
| | | the type property is not |
| | | a numeric type. |
| fractionDig | Non-negative integer | Specifies the maximum |
| its | | number of fractional |
| | | digits that can be |
| | | included in numeric |
| | | values. The |
| | | fractionDigits property |
| | | MUST be ignored if the |
| | | value type identified by |
| | | the type property is not |
| | | a numeric type. |
| pattern | String or Array of | One or more Regular |
| | Strings | 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 |
Snell & Marum Expires November 2, 2014 [Page 21]
Internet-Draft ActivityStreams May 2014
| | | expected to conform to |
| | | at least one of the |
| | | given patterns. |
| placeholder | Natural Language Value [ | An optional Natural |
| | I-D.snell-activitystream | Language Value providing |
| | s] | a text hint that |
| | | describes the expected |
| | | value of the parameter. |
+-------------+--------------------------+--------------------------+
Using the Parameter Object in HtmlForm objects:
{
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": "string",
"bar": {
"displayName": "Bar",
"required": false,
"repeated": false,
"type": "unsignedInt",
"default": 3,
"minInclusive": 1,
"maxInclusive": 5
}
}
}
10.2. Using UrlTemplate and TypedPayload objects as parameter
descriptions
In certain cases, when the value of a parameter is expected to be
either a URI or IRI, the UrlTemplate objectType (Section 9) MAY be
used as the parameter description. In such cases, the "required",
"repeated", "default" and "placeholder" properties from the Parameter
objectType (Section 10.1) can be used as additional properties within
the UrlTemplate object.
For example:
Snell & Marum Expires November 2, 2014 [Page 22]
Internet-Draft ActivityStreams May 2014
{
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"foo": "http://example.org/FooProperty",
"bar": {
"objectType": "UrlTemplate",
"template": "http://example.org{/baz}",
"displayName": "Bar",
"required": false,
"repeated": false
}
}
}
Likewise, when the value of a parameter is expected to be an instance
of a specific MIME media type, the TypedPayload objectType
(Section 8) can be used.
{
"objectType": "HtmlForm",
"mediaType": "multipart/form-data",
"parameters": {
"file": {
"objectType": "TypedPayload",
"mediaType": "image/*",
"repeated": true
}
}
}
11. Authentication Object
An Authentication Object is used by Action Handlers that require
specific authentication options to be supported in order to carry out
the Action. The object is expresed as a JSON dictionary mapping
authentication schema labels to JSON dictionaries that provide a
specific description of properties and requirements specific to the
scheme.
Snell & Marum Expires November 2, 2014 [Page 23]
Internet-Draft ActivityStreams May 2014
Example Authentication details:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note",
"actions": {
"view": {
"objectType": "HttpActionHandler",
"method": "GET",
"url": "http://example.org/notes/1",
"auth": {
"basic": {
"realm": "http://example.org"
},
"oauth": {
"scopes": [
"some.oauth.scope",
"another.oauth.scope"
]
}
}
}
}
}
This specification does not define the authentication schemes or
their associated properties. Unrecognized authentication schemes MAY
be ignored. However, if an implementation fails to recognize any of
the authentication schemes specified by an Action Handler, it might
not be possible to successfully carry out the Action.
12. Styles Object
A Styles Object is used by EmbedActionHandlers to provide CSS style
hints for the container within which embedded content is to be
displayed. The object is expressed as either a single JSON
dictionary object mapping CSS property names to appropriate CSS
values, or an array of JSON dictionary objects. An optional "media"
member can be included within the dictionary providing a CSS Media
Query.
Snell & Marum Expires November 2, 2014 [Page 24]
Internet-Draft ActivityStreams May 2014
Example style hints:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "EmbedActionHandler",
"content": "Some plain text content",
"mediaType": "text/plain",
"style": {
"height": "100px",
"width": "100px",
"box-shadow": "10px 10px 5px #888888"
}
}
}
}
Multiple style hints for specific media query targets:
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"view": {
"objectType": "EmbedActionHandler",
"content": "Some plain text content",
"mediaType": "text/plain",
"style": [
{
"media": "print",
"height": "100px",
"width": "100px",
"box-shadow": "10px 10px 5px #888888"
},
{
"media": "screen and (orientation: landscape)",
"height": "100px",
"width": "100px",
"box-shadow": "10px 10px 5px #888888"
}
]
}
}
}
Snell & Marum Expires November 2, 2014 [Page 25]
Internet-Draft ActivityStreams May 2014
13. Security Considerations
TBD
14. IANA Considerations
TBD
15. Normative References
[I-D.snell-activitystreams]
Snell, J., "JSON Activity Streams 2.0", draft-snell-
activitystreams-07 (work in progress), April 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012.
[W3C.REC-xmlschema-2-20041028]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium Recommendation
REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
Appendix A. Using Action Handlers From Other Vocabularies
The Activity Streams 2.0 Actions mechanism is specifically designed
to allow Action Handlers from multiple vocabularies.
A.1. Schema.org Actions Proposal
Based on http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf:
Snell & Marum Expires November 2, 2014 [Page 26]
Internet-Draft ActivityStreams May 2014
{
"objectType": "video",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"watch": [
{
"objectType": "http://schema.org/WebPageHandler",
"url": "http://movies.example.com/player?id=123"
},
{
"objectType": "http://schema.org/AndroidHandler",
"url": "http://movies.example.com/player?id=123",
"package": "com.movies"
}
]
}
}
A.2. Google's "Actions in the Inbox"
Based on https://developers.google.com/gmail/actions/reference/
review-action:
Snell & Marum Expires November 2, 2014 [Page 27]
Internet-Draft ActivityStreams May 2014
{
"objectType": "note",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"review": {
"objectType": "http://schema.org/ReviewAction",
"review": {
"objectType": "http://schema.org/Review",
"itemReviewed": {
"objectType": "http://schema.org/FoodEstablishment",
"name": "Joe's Diner"
},
"reviewRating": {
"objectType": "http://schema.org/Rating",
"bestRating": "5",
"worstRating": "1"
}
},
"handler": {
"objectType": "http://schema.org/HttpActionHandler",
"url": "http://reviews.com/review?id=123",
"requiredProperty": {
"objectType": "http://schema.org/Property",
"name": "review.reviewRating.ratingValue"
},
"method": "http://schema.org/HttpRequestMethod/POST"
}
}
}
}
A.3. Mixing Vocabularies
Snell & Marum Expires November 2, 2014 [Page 28]
Internet-Draft ActivityStreams May 2014
{
"objectType": "video",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"watch": [
{
"objectType": "HttpActionHandler",
"url": "http://movies.example.com/player?id=123",
"target": "NEW"
},
{
"objectType": "http://schema.org/AndroidHandler",
"url": "http://movies.example.com/player?id=123",
"package": "com.movies"
}
]
}
}
A.4. Example Drawing From Multiple Vocabularies
{
"objectType": "video",
"displayName": "A Movie!",
"displayName": "A simple note object",
"content": "This is a simple note.",
"actions": {
"watch": [
{
"objectType": "EmbedActionHandler",
"displayName": "HD",
"mediaType": "video/mpeg",
"url": "http://cdn.example.org?id=123amp;fmt=HD",
},
{
"objectType": "EmbedActionHandler",
"displayName": "SD",
"mediaType": "video/mpeg",
"url": "http://cdn.example.org?id=123&fmt=SD",
},
{
"objectType": "application",
"displayName": "Watch on Netflix",
"url": "http://netflix.com..."
}
],
"like": {
Snell & Marum Expires November 2, 2014 [Page 29]
Internet-Draft ActivityStreams May 2014
"objectType": "EmbedActionHandler",
"mediaType": "text/html",
"url": "http://www.facebook.com/plugins/like.php...",
"style": {
"width": "150px",
"height": "50px"
}
},
"share": [
{
"objectType": "HttpActionHandler",
"displayName": "Twitter",
"url": "https://twitter.com/share?url=...",
"target": "DIALOG"
},
{
"objectType": "HttpActionHandler",
"displayName": "Facebook",
"url": "https://www.facebook.com/sharer/sharer.php?u=...",
"target": "DIALOG"
}
],
"save": [
{
"objectType": "service",
"id": "http://getpocket.com",
"displayName": "Pocket",
"context": {
"url": "http://example.org/movie?id=123",
"title": "A Movie!",
"tags": "foo, bar, baz"
}
},
{
"objectType": "service",
"id": "http://instapaper.com",
"displayName": "Instapaper",
"context": {
"url": "http://example.org/movie?id=123",
"title": "A Movie!",
"selection": "An action movie!"
}
}
],
"review": {
"objectType": "HttpActionHandler",
"displayName": "Rate this movie!",
"url": "http://review.example.org/movie?id=123",
Snell & Marum Expires November 2, 2014 [Page 30]
Internet-Draft ActivityStreams May 2014
"method": "POST",
"expects": {
"objectType": "HtmlForm",
"mediaType": "application/x-www-form-urlencoded",
"parameters": {
"rating": {
"maxInclusive": 5,
"minInclusive": 0,
"fractionDigits": 2,
"totalDigits": 3
"type": "float",
"displayName": "Rating"
},
"comments": {
"displayName": "Comments",
"type": "string",
"required": false
}
}
}
}
}
}
Authors' Addresses
James M Snell
IBM
Email: jasnell@gmail.com
Matthew Marum
SugarCRM
Email: mgmarum@gmail.com
Snell & Marum Expires November 2, 2014 [Page 31]