One document matched: draft-snell-activitystreams-actions-00.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 as2 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-snell-activitystreams-05.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-00" >
  <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="December" year="2013" />
    <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>TBD</t>
    </section>
    
    <section anchor="actionhandler" title="Common Action Handler Properties">
      
      <t>Common base properties available for all Action Handler objects:</t>
      
      <texttable>
        <ttcol>Property</ttcol>
        <ttcol>Value</ttcol>
        <ttcol>Description</ttcol>
        
        <c>confirm</c>
        <c>Boolean</c>
        <c>
          Optional. True if confirmation is required before 
          the action is carried out.
        </c>
        
        <c>context</c>
        <c>JSON Object</c>
        <c>
          Contextual information associated with the action 
          handler, represented as a JSON Object with no particular
          structure. How the context is used is dependent
          entirely on the action handler definition and on how an
          application chooses to implement the Action Handler.
        </c>
        
        <c>expects</c>
        <c><xref target="I-D.snell-activitystreams">Type 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.
        </c>
        
        <c>returns</c>
        <c><xref target="I-D.snell-activitystreams">Type Value</xref></c>
        <c>
          For action handlers with a distinct output, the returns
          property provides a description of the expected output.
        </c>
        
      </texttable>
      
    </section>
    
    <section anchor="httpactionhandler" title="HTTP Action Handler">
      
      <texttable>
        <ttcol>Property</ttcol>
        <ttcol>Value</ttcol>
        <ttcol>Description</ttcol>
        
        <c>url</c>
        <c>Link Value</c>
        <c>Required.</c>
        
        <c>method</c>
        <c>HTTP Method String (e.g. "GET", "POST", "PUT", etc)</c>
        <c>Optional. Defaults to "GET"</c>
        
        <c>objectType</c>
        <c>"HttpActionHandler"</c>
        <c></c>
        
        <c>target</c>
        <c>"DEFAULT", "NONE", "NEW", "CURRENT", or other token value</c>
        <c>
          Optional. Specifies the intended target of the HTTP action.
          This determines whether the action results in a new navigation
          context (e.g. new browser window) or whether the action is 
          "hidden". Defaults to "DEFAULT".
        </c>
      </texttable>
      
      <figure><preamble>Example:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "view": {
        "objectType": "HttpActionHandler",
        "url": "http://example.org/foo",
        "method": "GET"
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Equivalent:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "view": "http://example.org/foo"
    }
  }
      </artwork></figure>
      
      <figure><preamble>"GET" HttpActionHandler using a URL Template:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "review": {
        "objectType": "HttpActionHandler",
        "url": {
          "objectType": "UrlTemplate",
          "template": "http://example.org/note/123{?rating}",
          "parameters": {
            "rating": {
              "id": "http://schema.org/ratingValue",
              "displayName": "Rating",
              "bestRating": 5,
              "worstRating": 1
            }
          }
        },
        "method": "GET",
        "target": "NEW"
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>"GET" HttpActionHandler shortcut using a URL Template:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "review": {
        "objectType": "UrlTemplate",
        "template": "http://example.org/note/123{?rating}",
        "parameters": {
          "rating": {
            "id": "http://schema.org/ratingValue",
            "displayName": "Rating",
            "bestRating": 5,
            "worstRating": 1
          }
        }
      }
    }
  }
      </artwork></figure>
            
    </section>
    
    <section anchor="embedactionhandler" title="Embed Action Handler">
      
      <texttable>
        <ttcol>Property</ttcol>
        <ttcol>Value</ttcol>
        <ttcol>Description</ttcol>
        
        <c>url</c>
        <c>Link Value</c>
        <c>
          Required if "content" is not specified. URL from which to
          retrieve the content for this embed.
        </c>
        
        <c>content</c>
        <c>String</c>
        <c>
          Required if "url" is not specified. Textual content for this
          embed.
        </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>
          Optional CSS Styling hints to apply to the element containing
          the embedded content.
        </c>
        
        <c>preview</c>
        <c>Link Value</c>
        <c>Optional</c>
        
        <c>objectType</c>
        <c>"EmbedActionHandler"</c>
        <c></c>
        
        <c>target</c>
        <c>"DEFAULT", "INLINE" or other</c>
        <c></c>
        
      </texttable>
      
      <figure><preamble>Example:</preamble><artwork><![CDATA[
  {
    "objectType": "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>
      
      <figure><preamble>Example:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "view": {
        "objectType": "EmbedActionHandler",
        "url": "http://example.org/foo",
        "mediaType": "text/html"
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Example:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "view": {
        "objectType": "EmbedActionHandler",
        "url": "http://example.org/foo.mpg",
        "mediaType": "video/mpeg"
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Example:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "view": {
        "objectType": "EmbedActionHandler",
        "content": "This is a pretty useless action handler",
        "mediaType": "text/plain"
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Example:</preamble><artwork>
  {
    “actions”: {
      “view”: { 
        “objectType”: “EmbedActionHandler”,
        “mediaType”: “application/vnd.opensocial.gadget+xml”,
        “url”: “http://example.org/gadget-spec.xml”,
        “context”: {
          “foo”: 123,
          “bar”: “ABC”
        }
      }
    }
  }
      </artwork></figure>
            
    </section>
    
    <section anchor="intentactionhandler" title="Intent Action Handler">
      
      <texttable>
        <ttcol>Property</ttcol>
        <ttcol>Value</ttcol>
        <ttcol>Description</ttcol>
        
        <c>url</c>
        <c>Link Value</c>
        <c>Optiona</c>
        
        <c>objectType</c>
        <c>"IntentActionHandler"</c>
        <c></c>
        
      </texttable>
      
      <figure><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "share": {
        "objectType": "IntentActionHandler",
        "displayName": "Share This",
        "context": {
          "foo": "ABC",
          "bar": 123
        }
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Targeting a specific application:</preamble><artwork>
  {
    "objectType": "note",
    ...,
    "actions": {
      "share": {
        "objectType": "IntentActionHandler",
        "displayName": "Share This",
        "url": "app://com.example.mysharingapp",
        "context": {
          "foo": "ABC",
          "bar": 123
        }
      }
    }
  }
      </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></c>
        <c>parameters</c>
        <c><xref target="parameters">Parameters Object</xref></c>
        <c></c>
      </texttable>
      
      <figure><artwork>
{
  "objectType": "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",
            "id": "http://example.org/FooProperty",
            "required": True
          },
          "bar": {
            "displayName": "Bar",
            "id": "http://example.org/BarProperty",
            "required": True,
            "value": "Provided Value"
          }
        }
      }
    }
  }
}
      </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></c>
        <c>parameters</c>
        <c><xref target="parameters">Parameters Object</xref></c>
        <c></c>  
      </texttable>  
      
      <figure><artwork>
{
  "objectType": "note",
  ...,
  "actions": {
    "review": {
      "objectType": "UrlTemplate",
      "template": "http://example.org/foo/123{?rating}",
      "parameters": {
        "rating": {
          "displayName": "Rating",
          "id": "http://example.org/RatingProperty",
          "required": True
        }
      }
    }
  }
}
      </artwork></figure>
      
    </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 
        <xref target="I-D.snell-activitystreams">Type Values</xref> describing
        the parameters.
      </t>
      
      <t>
        By default, all parameters defined within the object are assumed to be
        required. When a parameter is described using an Object, the object 
        MAY contained 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": "http://example.org/FooProperty",
      "bar": {
        "id": "http://example.org/BarProperty",
        "displayName": "Bar",
        "required": False
      }
    }
  }
      </artwork></figure>
      
      <figure><preamble>Using the Parameters Object in HtmlForm objects:</preamble><artwork>
  {
    "objectType": "HtmlForm",
    "mediaType": "application/x-www-form-urlencoded",
    "parameters": {
      "foo": "http://example.org/FooProperty",
      "bar": {
        "id": "http://example.org/BarProperty",
        "displayName": "Bar",
        "required": False
      }
    }
  }
      </artwork></figure>
      
    </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",
  ...,
  "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",
  ...,
  "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;
      &as2;      
    </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",
    ...,
    "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",
    ...,
    "actions": {
      "review": {
        "objectType": "UrlTemplate",
        "template": "http://example.org/note/123{?rating}",
        "parameters": {
          "rating": {
            "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",
    ...,
    "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"
        }
      ]
    }
  }
        </artwork></figure>
        
      </section>
      
    </section>
    
  </back>
</rfc>