idnits 2.17.1 draft-snell-activitystreams-actions-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (December 12, 2013) is 3781 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2119' is defined on line 539, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-snell-activitystreams-05 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Activity Streams (http://activitystrea.ms) J. Snell 3 Internet-Draft IBM 4 Intended status: Standards Track M. Marum 5 Expires: June 15, 2014 SugarCRM 6 December 12, 2013 8 JSON Activity Streams 2.0 - Action Handlers 9 draft-snell-activitystreams-actions-00 11 Abstract 13 This specification defines Action Handlers for use with the Activity 14 Streams 2.0 format. 16 Author's Note 18 Note that this document is a work-in-progress draft specification 19 that does not yet represent a "standard". It is the intention of 20 this specification to propose a few new ideas and openly solicit 21 feedback on their definition and use. While this document might 22 eventually evolve into an RFC the ideas described herein have not yet 23 been broadly implemented and have definitions that will evolve 24 through successive iterations of this draft. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on June 15, 2014. 43 Copyright Notice 45 Copyright (c) 2013 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Common Action Handler Properties . . . . . . . . . . . . . . 2 62 3. HTTP Action Handler . . . . . . . . . . . . . . . . . . . . . 3 63 4. Embed Action Handler . . . . . . . . . . . . . . . . . . . . 6 64 5. Intent Action Handler . . . . . . . . . . . . . . . . . . . . 8 65 6. HTML Form Objects . . . . . . . . . . . . . . . . . . . . . . 9 66 7. URL Template Objects . . . . . . . . . . . . . . . . . . . . 10 67 8. Parameters Object . . . . . . . . . . . . . . . . . . . . . . 10 68 9. Styles Object . . . . . . . . . . . . . . . . . . . . . . . . 11 69 10. Security Considerations . . . . . . . . . . . . . . . . . . . 13 70 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 71 12. Normative References . . . . . . . . . . . . . . . . . . . . 13 72 Appendix A. Using Action Handlers From Other Vocabularies . . . 13 73 A.1. Schema.org Actions Proposal . . . . . . . . . . . . . . . 13 74 A.2. Google's "Actions in the Inbox" . . . . . . . . . . . . . 14 75 A.3. Mixing Vocabularies . . . . . . . . . . . . . . . . . . . 15 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 78 1. Overview 80 TBD 82 2. Common Action Handler Properties 84 Common base properties available for all Action Handler objects: 86 +-----------+-----------------------------+-------------------------+ 87 | Property | Value | Description | 88 +-----------+-----------------------------+-------------------------+ 89 | confirm | Boolean | Optional. True if | 90 | | | confirmation is | 91 | | | required before the | 92 | | | action is carried out. | 93 | context | JSON Object | Contextual information | 94 | | | associated with the | 95 | | | action handler, | 96 | | | represented as a JSON | 97 | | | Object with no | 98 | | | particular structure. | 99 | | | How the context is used | 100 | | | is dependent entirely | 101 | | | on the action handler | 102 | | | definition and on how | 103 | | | an application chooses | 104 | | | to implement the Action | 105 | | | Handler. | 106 | expects | Type Value [I-D.snell- | For action handlers | 107 | | activitystreams] | with a distinct input | 108 | | | requirement (e.g. | 109 | | | HttpActionHandler), the | 110 | | | expects property | 111 | | | provides a description | 112 | | | of the expected input. | 113 | returns | Type Value [I-D.snell- | For action handlers | 114 | | activitystreams] | with a distinct output, | 115 | | | the returns property | 116 | | | provides a description | 117 | | | of the expected output. | 118 +-----------+-----------------------------+-------------------------+ 120 3. HTTP Action Handler 122 +-------------+-------------------------+---------------------------+ 123 | Property | Value | Description | 124 +-------------+-------------------------+---------------------------+ 125 | url | Link Value | Required. | 126 | method | HTTP Method String | Optional. Defaults to | 127 | | (e.g. "GET", "POST", | "GET" | 128 | | "PUT", etc) | | 129 | objectType | "HttpActionHandler" | | 130 | target | "DEFAULT", "NONE", | Optional. Specifies the | 131 | | "NEW", "CURRENT", or | intended target of the | 132 | | other token value | HTTP action. This | 133 | | | determines whether the | 134 | | | action results in a new | 135 | | | navigation context (e.g. | 136 | | | new browser window) or | 137 | | | whether the action is | 138 | | | "hidden". Defaults to | 139 | | | "DEFAULT". | 140 +-------------+-------------------------+---------------------------+ 141 Example: 143 { 144 "objectType": "note", 145 ..., 146 "actions": { 147 "view": { 148 "objectType": "HttpActionHandler", 149 "url": "http://example.org/foo", 150 "method": "GET" 151 } 152 } 153 } 155 Equivalent: 157 { 158 "objectType": "note", 159 ..., 160 "actions": { 161 "view": "http://example.org/foo" 162 } 163 } 165 "GET" HttpActionHandler using a URL Template: 167 { 168 "objectType": "note", 169 ..., 170 "actions": { 171 "review": { 172 "objectType": "HttpActionHandler", 173 "url": { 174 "objectType": "UrlTemplate", 175 "template": "http://example.org/note/123{?rating}", 176 "parameters": { 177 "rating": { 178 "id": "http://schema.org/ratingValue", 179 "displayName": "Rating", 180 "bestRating": 5, 181 "worstRating": 1 182 } 183 } 184 }, 185 "method": "GET", 186 "target": "NEW" 187 } 188 } 189 } 191 "GET" HttpActionHandler shortcut using a URL Template: 193 { 194 "objectType": "note", 195 ..., 196 "actions": { 197 "review": { 198 "objectType": "UrlTemplate", 199 "template": "http://example.org/note/123{?rating}", 200 "parameters": { 201 "rating": { 202 "id": "http://schema.org/ratingValue", 203 "displayName": "Rating", 204 "bestRating": 5, 205 "worstRating": 1 206 } 207 } 208 } 209 } 210 } 212 4. Embed Action Handler 214 +--------------+--------------------------+-------------------------+ 215 | Property | Value | Description | 216 +--------------+--------------------------+-------------------------+ 217 | url | Link Value | Required if "content" | 218 | | | is not specified. URL | 219 | | | from which to retrieve | 220 | | | the content for this | 221 | | | embed. | 222 | content | String | Required if "url" is | 223 | | | not specified. Textual | 224 | | | content for this embed. | 225 | mediaType | MIME Media Type | The MIME Media Type of | 226 | | | the embedded content. | 227 | style | Styles Object (Section | Optional CSS Styling | 228 | | 9) | hints to apply to the | 229 | | | element containing the | 230 | | | embedded content. | 231 | preview | Link Value | Optional | 232 | objectType | "EmbedActionHandler" | | 233 | target | "DEFAULT", "INLINE" or | | 234 | | other | | 235 +--------------+--------------------------+-------------------------+ 237 Example: 239 { 240 "objectType": "note", 241 ..., 242 "actions": { 243 "view": { 244 "objectType": "EmbedActionHandler", 245 "content": "
This is some bit of embedded HTML
", 246 "mediaType": "text/html", 247 "style": { 248 "height": "100px", 249 "width": "100px", 250 "box-shadow": "10px 10px 5px #888888" 251 }, 252 "displayName": "Some embedded content", 253 "preview": "http://example.org/preview/123.jpg" 254 } 255 } 256 } 257 Example: 259 { 260 "objectType": "note", 261 ..., 262 "actions": { 263 "view": { 264 "objectType": "EmbedActionHandler", 265 "url": "http://example.org/foo", 266 "mediaType": "text/html" 267 } 268 } 269 } 271 Example: 273 { 274 "objectType": "note", 275 ..., 276 "actions": { 277 "view": { 278 "objectType": "EmbedActionHandler", 279 "url": "http://example.org/foo.mpg", 280 "mediaType": "video/mpeg" 281 } 282 } 283 } 285 Example: 287 { 288 "objectType": "note", 289 ..., 290 "actions": { 291 "view": { 292 "objectType": "EmbedActionHandler", 293 "content": "This is a pretty useless action handler", 294 "mediaType": "text/plain" 295 } 296 } 297 } 299 Example: 301 { 302 "actions": { 303 "view": { 304 "objectType": "EmbedActionHandler", 305 "mediaType": "application/vnd.opensocial.gadget+xml", 306 "url": "http://example.org/gadget-spec.xml", 307 "context": { 308 "foo": 123, 309 "bar": "ABC" 310 } 311 } 312 } 313 } 315 5. Intent Action Handler 317 +------------+-----------------------+-------------+ 318 | Property | Value | Description | 319 +------------+-----------------------+-------------+ 320 | url | Link Value | Optiona | 321 | objectType | "IntentActionHandler" | | 322 +------------+-----------------------+-------------+ 324 { 325 "objectType": "note", 326 ..., 327 "actions": { 328 "share": { 329 "objectType": "IntentActionHandler", 330 "displayName": "Share This", 331 "context": { 332 "foo": "ABC", 333 "bar": 123 334 } 335 } 336 } 337 } 339 Targeting a specific application: 341 { 342 "objectType": "note", 343 ..., 344 "actions": { 345 "share": { 346 "objectType": "IntentActionHandler", 347 "displayName": "Share This", 348 "url": "app://com.example.mysharingapp", 349 "context": { 350 "foo": "ABC", 351 "bar": 123 352 } 353 } 354 } 355 } 357 6. HTML Form Objects 359 +------------+-------------------------------+-------------+ 360 | Property | Value | Description | 361 +------------+-------------------------------+-------------+ 362 | mediaType | MIME Media Type | | 363 | parameters | Parameters Object (Section 8) | | 364 +------------+-------------------------------+-------------+ 366 { 367 "objectType": "note", 368 ..., 369 "actions": { 370 "review": { 371 "objectType": "HttpActionHandler", 372 "method": "POST", 373 "url": "http://example.org/foo", 374 "expects": { 375 "objectType": "HtmlForm", 376 "mediaType": "application/x-www-form-urlencoded", 377 "parameters": { 378 "foo": { 379 "displayName": "Foo", 380 "id": "http://example.org/FooProperty", 381 "required": True 382 }, 383 "bar": { 384 "displayName": "Bar", 385 "id": "http://example.org/BarProperty", 386 "required": True, 387 "value": "Provided Value" 388 } 389 } 390 } 391 } 392 } 393 } 395 7. URL Template Objects 397 Objects with the "UrlTemplate" object type represent [RFC6570] URL 398 Templates. 400 +------------+-------------------------------+-------------+ 401 | Property | Value | Description | 402 +------------+-------------------------------+-------------+ 403 | template | URL Template | | 404 | parameters | Parameters Object (Section 8) | | 405 +------------+-------------------------------+-------------+ 407 { 408 "objectType": "note", 409 ..., 410 "actions": { 411 "review": { 412 "objectType": "UrlTemplate", 413 "template": "http://example.org/foo/123{?rating}", 414 "parameters": { 415 "rating": { 416 "displayName": "Rating", 417 "id": "http://example.org/RatingProperty", 418 "required": True 419 } 420 } 421 } 422 } 423 } 425 8. Parameters Object 427 A Parameters Object is used to provide descriptions of the variable 428 inputs of objects such as HTML Forms (Section 6) and URL Templates 429 (Section 7). The object is expressed as a JSON dictionary mapping 430 parameter names to Type Values [I-D.snell-activitystreams] describing 431 the parameters. 433 By default, all parameters defined within the object are assumed to 434 be required. When a parameter is described using an Object, the 435 object MAY contained a boolean "required" member. If "required" is 436 false, use of the parameter is assumed to be optional. 438 Using the Parameters Object in UrlTemplate objects: 440 { 441 "objectType": "UrlTemplate", 442 "template": "http://example.org{/foo,bar}" 443 "parameters": { 444 "foo": "http://example.org/FooProperty", 445 "bar": { 446 "id": "http://example.org/BarProperty", 447 "displayName": "Bar", 448 "required": False 449 } 450 } 451 } 453 Using the Parameters Object in HtmlForm objects: 455 { 456 "objectType": "HtmlForm", 457 "mediaType": "application/x-www-form-urlencoded", 458 "parameters": { 459 "foo": "http://example.org/FooProperty", 460 "bar": { 461 "id": "http://example.org/BarProperty", 462 "displayName": "Bar", 463 "required": False 464 } 465 } 466 } 468 9. Styles Object 470 A Styles Object is used by EmbedActionHandlers to provide CSS style 471 hints for the container within which embedded content is to be 472 displayed. The object is expressed as either a single JSON 473 dictionary object mapping CSS property names to appropriate CSS 474 values, or an array of JSON dictionary objects. An optional "media" 475 member can be included within the dictionary providing a CSS Media 476 Query. 478 Example style hints: 480 { 481 "objectType": "note", 482 ..., 483 "actions": { 484 "view": { 485 "objectType": "EmbedActionHandler", 486 "content": "Some plain text content", 487 "mediaType": "text/plain", 488 "style": { 489 "height": "100px", 490 "width": "100px", 491 "box-shadow": "10px 10px 5px #888888" 492 } 493 } 494 } 495 } 497 Multiple style hints for specific media query targets: 499 { 500 "objectType": "note", 501 ..., 502 "actions": { 503 "view": { 504 "objectType": "EmbedActionHandler", 505 "content": "Some plain text content", 506 "mediaType": "text/plain", 507 "style": [ 508 { 509 "media": "print", 510 "height": "100px", 511 "width": "100px", 512 "box-shadow": "10px 10px 5px #888888" 513 }, 514 { 515 "media": "screen and (orientation: landscape)", 516 "height": "100px", 517 "width": "100px", 518 "box-shadow": "10px 10px 5px #888888" 519 } 520 ] 521 } 522 } 523 } 525 10. Security Considerations 527 TBD 529 11. IANA Considerations 531 TBD 533 12. Normative References 535 [I-D.snell-activitystreams] 536 Snell, J., "JSON Activity Streams 2.0", draft-snell- 537 activitystreams-05 (work in progress), November 2013. 539 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 540 Requirement Levels", BCP 14, RFC 2119, March 1997. 542 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 543 and D. Orchard, "URI Template", RFC 6570, March 2012. 545 Appendix A. Using Action Handlers From Other Vocabularies 547 The Activity Streams 2.0 Actions mechanism is specifically designed 548 to allow Action Handlers from multiple vocabularies. 550 A.1. Schema.org Actions Proposal 552 Based on http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf: 554 { 555 "objectType": "video", 556 ..., 557 "actions": { 558 "watch": [ 559 { 560 "objectType": "http://schema.org/WebPageHandler", 561 "url": "http://movies.example.com/player?id=123" 562 }, 563 { 564 "objectType": "http://schema.org/AndroidHandler", 565 "url": "http://movies.example.com/player?id=123", 566 "package": "com.movies" 567 } 568 ] 569 } 570 } 572 A.2. Google's "Actions in the Inbox" 574 Based on https://developers.google.com/gmail/actions/reference/ 575 review-action: 577 { 578 "objectType": "note", 579 ..., 580 "actions": { 581 "review": { 582 "objectType": "UrlTemplate", 583 "template": "http://example.org/note/123{?rating}", 584 "parameters": { 585 "rating": { 586 "objectType": "http://schema.org/ReviewAction", 587 "review": { 588 "objectType": "http://schema.org/Review", 589 "itemReviewed": { 590 "objectType": "http://schema.org/FoodEstablishment", 591 "name": "Joe's Diner" 592 }, 593 "reviewRating": { 594 "objectType": "http://schema.org/Rating", 595 "bestRating": "5", 596 "worstRating": "1" 597 } 598 }, 599 "handler": { 600 "objectType": "http://schema.org/HttpActionHandler", 601 "url": "http://reviews.com/review?id=123", 602 "requiredProperty": { 603 "objectType": "http://schema.org/Property", 604 "name": "review.reviewRating.ratingValue" 605 }, 606 "method": "http://schema.org/HttpRequestMethod/POST" 607 } 608 } 609 } 610 } 611 } 612 } 614 A.3. Mixing Vocabularies 616 { 617 "objectType": "video", 618 ..., 619 "actions": { 620 "watch": [ 621 { 622 "objectType": "HttpActionHandler", 623 "url": "http://movies.example.com/player?id=123", 624 "target": "NEW" 625 }, 626 { 627 "objectType": "http://schema.org/AndroidHandler", 628 "url": "http://movies.example.com/player?id=123", 629 "package": "com.movies" 630 } 631 ] 632 } 633 } 635 Authors' Addresses 637 James M Snell 638 IBM 640 Email: jasnell@gmail.com 642 Matthew Marum 643 SugarCRM 645 Email: mgmarum@gmail.com