idnits 2.17.1 draft-snell-activitystreams-actions-03.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 (January 26, 2014) is 3741 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 1238, 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 (==), 2 comments (--). 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: July 30, 2014 SugarCRM 6 January 26, 2014 8 JSON Activity Streams 2.0 - Action Handlers 9 draft-snell-activitystreams-actions-03 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 July 30, 2014. 43 Copyright Notice 45 Copyright (c) 2014 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. Action Handlers . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. HTTP Action Handler . . . . . . . . . . . . . . . . . . . . . 7 63 4. Embed Action Handler . . . . . . . . . . . . . . . . . . . . 12 64 5. Intent Action Handler . . . . . . . . . . . . . . . . . . . . 15 65 6. Using "service" and "application" objects as action handlers 15 66 7. HTML Form Objects . . . . . . . . . . . . . . . . . . . . . . 16 67 8. Typed Payload Objects . . . . . . . . . . . . . . . . . . . . 17 68 9. URL Template Objects . . . . . . . . . . . . . . . . . . . . 19 69 10. Parameters Object . . . . . . . . . . . . . . . . . . . . . . 20 70 10.1. Parameter Object . . . . . . . . . . . . . . . . . . . . 21 71 10.2. Using UrlTemplate and TypedPayload objects as parameter 72 descriptions . . . . . . . . . . . . . . . . . . . . . . 26 73 11. Authentication Object . . . . . . . . . . . . . . . . . . . . 27 74 12. Styles Object . . . . . . . . . . . . . . . . . . . . . . . . 28 75 13. Security Considerations . . . . . . . . . . . . . . . . . . . 30 76 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 77 15. Normative References . . . . . . . . . . . . . . . . . . . . 30 78 Appendix A. Using Action Handlers From Other Vocabularies . . . 30 79 A.1. Schema.org Actions Proposal . . . . . . . . . . . . . . . 30 80 A.2. Google's "Actions in the Inbox" . . . . . . . . . . . . . 31 81 A.3. Mixing Vocabularies . . . . . . . . . . . . . . . . . . . 32 82 A.4. Example Drawing From Multiple Vocabularies . . . . . . . 33 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 85 1. Overview 87 The Activity Streams 2.0 [I-D.snell-activitystreams] specification 88 introduces the notion of "actions" that can be associated with 89 objects. Using the "actions" property described in Sections 3.6 and 90 3.6.1 of the Activity Streams 2.0 document, the producer of an object 91 can declare a specific set of verbs appropriate for the object and 92 map each of those to one or more objects ("action handlers") or 93 resources capable of "carrying out" the verb. This document expands 94 on that mechanism by defining and describing a core set of action 95 handler object types. 97 2. Action Handlers 99 An action handler is an Activity Streams 2.0 object whose objectType 100 and member properties instruct a consuming application how to carry 101 out the verb the action handler has been associated with. For 102 instance, given the following example: 104 { 105 "objectType": "note", 106 "displayName": "Title of the note", 107 "content": "This is a simple note.", 108 "actions": { 109 "share": { 110 "objectType": "HttpActionHandler", 111 "url": "http://example.org/share" 112 }, 113 "like": { 114 "objectType": "EmbedActionHandler", 115 "mediaType": "text/plain", 116 "content": "Hello World" 117 } 118 } 119 } 121 The "note" object has two declared actions, "share" and "like". Each 122 of those is associated with one action handler object. The "share" 123 action has a action handler of type "HttpActionHandler", while the 124 "like" action has an "EmbedActionHandler". 126 As illustrated in the example, action handlers are represented as 127 Activity Streams 2.0 objects. All such objects share a common set of 128 base member properties as defined in the following table: 130 +---------+--------------------------+---------+--------------------+ 131 | Propert | Value | Require | Description | 132 | y | | d | | 133 +---------+--------------------------+---------+--------------------+ 134 | confirm | Boolean | No | True if the | 135 | | | | consuming | 136 | | | | application ought | 137 | | | | to seek | 138 | | | | confirmation prior | 139 | | | | to using the | 140 | | | | action handler to | 141 | | | | carry out it's | 142 | | | | associated action. | 143 | | | | Defaults to False. | 144 | context | JSON Object | No | Contextual | 145 | | | | information | 146 | | | | associated with | 147 | | | | the action | 148 | | | | handler, | 149 | | | | represented as a | 150 | | | | JSON Object | 151 | | | | without any | 152 | | | | particular | 153 | | | | structure. How the | 154 | | | | context is used is | 155 | | | | dependent entirely | 156 | | | | on the action | 157 | | | | handler definition | 158 | | | | and on how a | 159 | | | | consuming | 160 | | | | application | 161 | | | | chooses to | 162 | | | | implement the | 163 | | | | action handler. | 164 | expects | Link Value [I-D.snell-ac | No | For action | 165 | | tivitystreams] | | handlers with a | 166 | | | | distinct input | 167 | | | | requirement (e.g. | 168 | | | | HttpActionHandler) | 169 | | | | , the expects | 170 | | | | property provides | 171 | | | | a description of | 172 | | | | the expected | 173 | | | | input. The value | 174 | | | | is expressed as | 175 | | | | either a String | 176 | | | | containing a fully | 177 | | | | qualified IRI, an | 178 | | | | Activity Stream | 179 | | | | Object, or an | 180 | | | | Array of IRI's or | 181 | | | | Objects. When | 182 | | | | multiple values | 183 | | | | are provided, they | 184 | | | | MUST be considered | 185 | | | | as mutually | 186 | | | | exclusive | 187 | | | | alternatives. | 188 | returns | Link Value [I-D.snell-ac | No | For action | 189 | | tivitystreams] | | handlers with a | 190 | | | | distinct output, | 191 | | | | the returns | 192 | | | | property provides | 193 | | | | a description of | 194 | | | | the expected | 195 | | | | output. The value | 196 | | | | is expressed as | 197 | | | | either a String | 198 | | | | containing a fully | 199 | | | | qualified IRI, an | 200 | | | | Activity Stream | 201 | | | | Object, or an | 202 | | | | Array of IRI's or | 203 | | | | Objects. When | 204 | | | | multiple values | 205 | | | | are provided, they | 206 | | | | MUST be considered | 207 | | | | as mutually | 208 | | | | exclusive | 209 | | | | alternatives. | 210 | auth | Authentication Value | No | For action | 211 | | (Section 11) | | handlers with | 212 | | | | specific | 213 | | | | authentication | 214 | | | | requirements, the | 215 | | | | "auth" property | 216 | | | | provides | 217 | | | | information about | 218 | | | | the specific | 219 | | | | authentication | 220 | | | | mechanisms | 221 | | | | supported. | 222 | require | Link Value [I-D.snell-ac | No | An optional Link | 223 | s | tivitystreams] | | Value whose | 224 | | | | value(s) describe | 225 | | | | features or | 226 | | | | behaviors an | 227 | | | | implementation | 228 | | | | MUST support in | 229 | | | | order to carry out | 230 | | | | the action. | 231 | | | | Requirements are | 232 | | | | designed to be | 233 | | | | intentionally | 234 | | | | open-ended and | 235 | | | | will vary | 236 | | | | depending on | 237 | | | | specific Action | 238 | | | | Handler type. Any | 239 | | | | implementation | 240 | | | | that does not | 241 | | | | support any | 242 | | | | specified required | 243 | | | | feature MUST | 244 | | | | ignore the Action | 245 | | | | Handler. | 246 | prefers | Link Value [I-D.snell-ac | No | An optional Link | 247 | | tivitystreams] | | Value whose | 248 | | | | value(s) describe | 249 | | | | features or | 250 | | | | behaviors an | 251 | | | | implementation | 252 | | | | SHOULD support in | 253 | | | | order to carry out | 254 | | | | the action. | 255 | | | | Requirements are | 256 | | | | designed to be | 257 | | | | intentionally | 258 | | | | open-ended and | 259 | | | | will vary | 260 | | | | depending on | 261 | | | | specific Action | 262 | | | | Handler type. Any | 263 | | | | implementation | 264 | | | | that does not | 265 | | | | support any | 266 | | | | specified | 267 | | | | preferred feature | 268 | | | | MAY ignore the | 269 | | | | feature. | 270 +---------+--------------------------+---------+--------------------+ 272 This specification defines three specific base types of action 273 handler: 275 o The HTTP Action Handler (Section 3), 277 o The Embed Action Handler (Section 4), and 279 o The Intent Action Handler (Section 5). 281 Implementations are free to use Activity Stream objects of any 282 objectType as an action handler. Consuming applications MAY ignore 283 any object it encounters that use objectTypes that are not recognized 284 or supported as action handlers. Alternatively, the consuming 285 application MAY treat such objects as implied Intent Action Handlers 286 (Section 5). 288 Multiple independent action handlers can be associated with any 289 single verb using a JSON Array. The ordering of objects within such 290 an array is not considered to be significant. 292 For example, in the following, the "share" action has two associated 293 action handlers: 295 { 296 "objectType": "event", 297 "displayName": "Party!", 298 "content": "We're going to party like it's 1999!", 299 "id": "urn:example:events:123", 300 "actions": { 301 "share": [ 302 { 303 "objectType": "HttpActionHandler", 304 "method": "GET", 305 "url": "http://example.org/share-action", 306 "target": "DIALOG", 307 "returns": { 308 "objectType": "TypedPayload", 309 "mediaType": "text/html" 310 } 311 }, 312 { 313 "objectType": "EmbedActionHandler", 314 "mediaType": "text/html", 315 "content": "
...
" 316 } 317 ] 318 } 319 } 321 3. HTTP Action Handler 323 An HTTP Action Handler describes an HTTP request/response flow that 324 is used to carry out an action. It is identified using an objectType 325 value of "HttpActionHandler". 327 +----------+----------------------------+----------+----------------+ 328 | Property | Value | Required | Description | 329 +----------+----------------------------+----------+----------------+ 330 | url | Link Value | Yes | Specifies the | 331 | | | | HTTP or HTTPS | 332 | | | | URL to which | 333 | | | | the HTTP | 334 | | | | request is | 335 | | | | directed. | 336 | method | HTTP Method String (e.g. | No | The HTTP | 337 | | "GET", "POST", "PUT", etc) | | method to use. | 338 | | | | Defaults to | 339 | | | | "GET" | 340 | target | "DEFAULT" - Consumer | No | Specifies the | 341 | | defined default; "NONE" - | | intended | 342 | | No navigation or UI | | target of the | 343 | | context (e.g. a hidden | | HTTP action. | 344 | | HTTP action that does not | | This | 345 | | result in the creation or | | determines | 346 | | use of a browser window); | | whether the | 347 | | "NEW" - A new navigation | | action results | 348 | | or UI context (e.g. show | | in a new | 349 | | the results of the HTTP | | navigation | 350 | | request in a browser | | context (e.g. | 351 | | window or tab.); "CURRENT" | | new browser | 352 | | - Reuse the existing | | window) or | 353 | | navigation or UI context | | whether the | 354 | | (e.g. show the results of | | action is | 355 | | the HTTP request in an | | "hidden". When | 356 | | existing browser window or | | not specified, | 357 | | tab.); {Other token value} | | defaults to | 358 | | - Any other TOKEN value. | | "DEFAULT", | 359 | | Interpretation and support | | meaning that | 360 | | of such extension tokens | | the consuming | 361 | | is dependent on the | | application is | 362 | | consuming application. | | free to | 363 | | Unknown or unsupported | | determine an | 364 | | values MUST be ignored. | | appropriate | 365 | | | | target | 366 | | | | context. | 367 +----------+----------------------------+----------+----------------+ 368 For example: 370 { 371 "objectType": "note", 372 "displayName": "A simple note object", 373 "content": "This is a simple note.", 374 "actions": { 375 "view": { 376 "objectType": "HttpActionHandler", 377 "url": "http://example.org/foo", 378 "method": "GET" 379 } 380 } 381 } 383 As a shortcut, HttpActionHandlers that use the "GET" method and a 384 "DEFAULT" target can be specified using a JSON string containing the 385 absolute URL. For instance: 387 { 388 "objectType": "note", 389 "displayName": "A simple note object", 390 "content": "This is a simple note.", 391 "actions": { 392 "view": "http://example.org/foo" 393 } 394 } 396 In the Activity Streams 2.0 format, the "url" property is defined as 397 a "Link Value", this means that it is possible for the value of the 398 "url" property to be an Activity Stream object that a consuming 399 application can use to resolve the actual target URL. This 400 specification defines a new UrlTemplate (Section 9) objectType 401 specifically intended for such use. 403 The UrlTemplate object can be used within an HTTP Action Handler, for 404 instance, whenever carrying out the HTTP request requires the 405 construction of a new URL that includes variable parameters: 407 { 408 "objectType": "note", 409 "displayName": "A simple note object", 410 "content": "This is a simple note.", 411 "actions": { 412 "review": { 413 "objectType": "HttpActionHandler", 414 "url": { 415 "objectType": "UrlTemplate", 416 "method": "POST", 417 "template": "http://example.org/note/123{?rating}", 418 "parameters": { 419 "rating": { 420 "id": "http://schema.org/ratingValue", 421 "displayName": "Rating", 422 "maximum": 5, 423 "minimum": 1, 424 "format": "uint32" 425 } 426 } 427 }, 428 "method": "GET", 429 "target": "NEW" 430 } 431 } 432 } 434 If the intended HTTP request uses the GET method and DEFAULT target, 435 the UrlTemplate object itself can be used directly as the action 436 handler. 438 "GET" HttpActionHandler shortcut using a URL Template: 440 { 441 "objectType": "note", 442 "displayName": "A simple note object", 443 "content": "This is a simple note.", 444 "actions": { 445 "review": { 446 "objectType": "UrlTemplate", 447 "template": "http://example.org/note/123{?rating}", 448 "parameters": { 449 "rating": { 450 "id": "http://schema.org/ratingValue", 451 "displayName": "Rating", 452 "maximum": 5, 453 "minimum": 1, 454 "format": "uint32" 455 } 456 } 457 } 458 } 459 } 461 If the HTTP request requires an input payload, the HttpActionHandler 462 object can contain an "expects" property. The value of "expects" is 463 an Activity Streams 2.0 "Link Value" represented either as a simple 464 JSON string containing a fully qualified IRI, an Activity Stream 465 object, or an array of IRI's or Objects. This specification defines 466 a new HtmlForm (Section 7) objectType to be used whenever the input 467 of the HTTP request is an HTML Form POST. A new TypedPayload 468 (Section 8) objectType is defined for use whenever the input is an 469 arbitrary MIME media type. 471 For example, the following describes an HTML Form post with a single 472 "foo" parameter submitted using the "application/x-www-form- 473 urlencoded" format: 475 { 476 "objectType": "note", 477 "displayName": "A simple note object", 478 "content": "This is a simple note.", 479 "actions": { 480 "share": { 481 "objectType": "HttpActionHandler", 482 "method": "POST", 483 "url": "http://example.org/foo", 484 "expects": { 485 "objectType": "HtmlForm", 486 "mediaType": "application/x-www-form-urlencoded", 487 "parameters": { 488 "foo": { 489 "id": "http://example.org/foo", 490 "type": "http://www.w3.org/2001/XMLSchema#string", 491 "displayName": "Foo Property" 492 } 493 } 494 } 495 } 496 } 497 } 499 4. Embed Action Handler 501 An Embed Action Handler defines static or dynamic content to be 502 visually rendered to carry out an action. Examples of embeds can 503 include static HTML, images, videos, gadgets and applications. It is 504 identified using an objectType value of "EmbedActionHandler". 506 +-----------+--------------+--------------+-------------------------+ 507 | Property | Value | Required | Description | 508 +-----------+--------------+--------------+-------------------------+ 509 | url | Link Value | Yes if | The URL from which to | 510 | | | "content" is | retrieve the content | 511 | | | not | for this embed. | 512 | | | specified. | | 513 | content | String | Yes if "url" | The character based | 514 | | | is not | "static" content to be | 515 | | | specified. | embeded. The | 516 | | | | "mediaType" parameter | 517 | | | | specifies the MIME | 518 | | | | media type of the | 519 | | | | content. | 520 | mediaType | MIME Media | No (but | The MIME Media Type of | 521 | | Type | strongly | the embedded content. | 522 | | | recommended) | | 523 | style | Styles | No | Visual CSS styling | 524 | | Object | | hints to apply to the | 525 | | (Section 12) | | element containing the | 526 | | | | embedded content. | 527 | preview | Link Value | No | A reference to a | 528 | | | | "preview" | 529 | | | | representation of the | 530 | | | | embedded content. | 531 | | | | Typically, this would a | 532 | | | | URL to a thumbnail or | 533 | | | | screenshot image of the | 534 | | | | content. | 535 | target | "DEFAULT"; | No | | 536 | | "INLINE"; | | | 537 | | {Other token | | | 538 | | value} | | | 539 +-----------+--------------+--------------+-------------------------+ 541 In the following example, the "view" action is associated with an 542 "EmbedActionHandler" containing a static fragment of HTML markup: 544 { 545 "objectType": "note", 546 "displayName": "A simple note object", 547 "content": "This is a simple note.", 548 "actions": { 549 "view": { 550 "objectType": "EmbedActionHandler", 551 "content": "
This is some bit of embedded HTML
", 552 "mediaType": "text/html", 553 "style": { 554 "height": "100px", 555 "width": "100px", 556 "box-shadow": "10px 10px 5px #888888" 557 }, 558 "displayName": "Some embedded content", 559 "preview": "http://example.org/preview/123.jpg" 560 } 561 } 562 } 564 Alternatively, the embedded content can be referenced by URL: 566 { 567 "objectType": "note", 568 "displayName": "A simple note object", 569 "content": "This is a simple note.", 570 "actions": { 571 "view": { 572 "objectType": "EmbedActionHandler", 573 "url": "http://example.org/foo", 574 "mediaType": "text/html" 575 } 576 } 577 } 579 The mediaType parameter specifies the type of content to be embedded. 580 Consuming applications MAY ignore Embed Action Handlers that specify 581 unrecognized or unsupported mediaTypes. 583 Example: 585 { 586 "objectType": "note", 587 "displayName": "A simple note object", 588 "content": "This is a simple note.", 589 "actions": { 590 "view": { 591 "objectType": "EmbedActionHandler", 592 "url": "http://example.org/foo.mpg", 593 "mediaType": "video/mpeg" 594 } 595 } 596 } 598 5. Intent Action Handler 600 An Intent Action Handler provides a generic way for the publisher of 601 an Activity object to tell the consuming application to figure out 602 how to handle the action on it's own. The consumer can, for 603 instance, pass the object off to some other native platform 604 application. It is identified using an objectType value of 605 "IntentActionHandler". 607 For example: 609 { 610 "objectType": "note", 611 "displayName": "A simple note object", 612 "content": "This is a simple note.", 613 "actions": { 614 "share": { 615 "objectType": "IntentActionHandler", 616 "displayName": "Share This", 617 "context": { 618 "foo": "ABC", 619 "bar": 123 620 } 621 } 622 } 623 } 625 6. Using "service" and "application" objects as action handlers 627 The "service" and "application" object are existing objectTypes 628 defined by the Activity Streams 1.0 core schema. While these objects 629 were not originally designed to be used as action handlers, they can 630 be. Specifically, the "service" objectType can be used when the 631 action is to be carried out using some specific third party service 632 interface; the "application" objectType can be used when the action 633 is to be carried out by deferring some some specific native platform 634 application. 636 For example: 638 { 639 "objectType": "note", 640 "displayName": "A simple note object", 641 "content": "This is a simple note.", 642 "actions": { 643 "share": { 644 "objectType": "service", 645 "displayName": "My Sharing Service", 646 "url": "http://share.example.org/api" 647 }, 648 "save": { 649 "objectType": "application", 650 "displayName": "Read this later!", 651 "platform": "android", 652 "id": "123", 653 "url": "http://play.google.com/..." 654 } 655 } 656 } 658 7. HTML Form Objects 660 +----------+-------------+---------+--------------------------------+ 661 | Property | Value | Require | Description | 662 | | | d | | 663 +----------+-------------+---------+--------------------------------+ 664 | mediaTyp | MIME Media | No | Defaults to "application/x | 665 | e | Type | | -www-form-urlencoded" | 666 | paramete | Parameters | No | Defines the HTML form | 667 | rs | Object | | parameters. | 668 | | (Section | | | 669 | | 10) | | | 670 +----------+-------------+---------+--------------------------------+ 671 For example: 673 { 674 "objectType": "note", 675 "displayName": "A simple note object", 676 "content": "This is a simple note.", 677 "actions": { 678 "review": { 679 "objectType": "HttpActionHandler", 680 "method": "POST", 681 "url": "http://example.org/foo", 682 "expects": { 683 "objectType": "HtmlForm", 684 "mediaType": "application/x-www-form-urlencoded", 685 "parameters": { 686 "foo": { 687 "displayName": "Foo", 688 "id": "http://example.org/FooProperty", 689 "type": "http://www.w3.org/2001/XMLSchema#string", 690 "required": True 691 }, 692 "bar": { 693 "displayName": "Bar", 694 "id": "http://example.org/BarProperty", 695 "type": "http://www.w3.org/2001/XMLSchema#", 696 "required": True, 697 "value": "Provided Value" 698 } 699 } 700 } 701 } 702 } 703 } 705 8. Typed Payload Objects 706 +----------+-----------------------------+----------+---------------+ 707 | Property | Value | Required | Description | 708 +----------+-----------------------------+----------+---------------+ 709 | mediaTyp | MIME Media Type | Yes | The MIME | 710 | e | | | Media Type of | 711 | | | | the Payload | 712 | type | Type Value | No | An optional | 713 | | [I-D.snell-activitystreams] | | Type Value | 714 | | | | that | 715 | | | | describes the | 716 | | | | payloads | 717 | | | | semantic | 718 | | | | type. | 719 | schema | Link Value | No | An optional | 720 | | [I-D.snell-activitystreams] | | Link Value | 721 | | | | whose | 722 | | | | value(s) | 723 | | | | describe the | 724 | | | | structure of | 725 | | | | the payload | 726 | | | | data. The | 727 | | | | value is | 728 | | | | represented | 729 | | | | either as a | 730 | | | | String with a | 731 | | | | fully | 732 | | | | qualified | 733 | | | | IRI, an | 734 | | | | Activity | 735 | | | | Stream | 736 | | | | object, or an | 737 | | | | Array of IRIs | 738 | | | | and Objects. | 739 | | | | If multiple | 740 | | | | values are | 741 | | | | provided, | 742 | | | | they are to | 743 | | | | be considered | 744 | | | | mutually | 745 | | | | exclusive | 746 | | | | alternatives. | 747 +----------+-----------------------------+----------+---------------+ 748 For example: 750 { 751 "objectType": "note", 752 "displayName": "A simple note object", 753 "content": "This is a simple note.", 754 "actions": { 755 "review": { 756 "objectType": "HttpActionHandler", 757 "method": "POST", 758 "url": "http://example.org/foo", 759 "expects": { 760 "objectType": "TypedPayload", 761 "mediaType": "text/json", 762 } 763 } 764 } 765 } 767 9. URL Template Objects 769 Objects with the "UrlTemplate" object type represent [RFC6570] URL 770 Templates. 772 +------------+--------------------+----------+----------------------+ 773 | Property | Value | Required | Description | 774 +------------+--------------------+----------+----------------------+ 775 | template | URL Template | Yes | The [RFC6570] URL | 776 | | | | Template | 777 | parameters | Parameters Object | No | Defines the URL | 778 | | (Section 10) | | Template parameters | 779 +------------+--------------------+----------+----------------------+ 780 { 781 "objectType": "note", 782 "displayName": "A simple note object", 783 "content": "This is a simple note.", 784 "actions": { 785 "review": { 786 "objectType": "UrlTemplate", 787 "template": "http://example.org/foo/123{?rating}", 788 "parameters": { 789 "rating": { 790 "displayName": "Rating", 791 "id": "http://example.org/RatingProperty", 792 "required": True 793 } 794 } 795 } 796 } 797 } 799 10. Parameters Object 801 A Parameters Object is used to provide descriptions of the variable 802 inputs of objects such as HTML Forms (Section 7) and URL Templates 803 (Section 9). The object is expressed as a JSON dictionary mapping 804 parameter names to Type Values [I-D.snell-activitystreams] describing 805 the parameters. 807 By default, all parameters defined within the object are assumed to 808 be required. When a parameter is described using an Object, the 809 object MAY contained a boolean "required" member. If "required" is 810 false, use of the parameter is assumed to be optional. 812 Using the Parameters Object in UrlTemplate objects: 814 { 815 "objectType": "UrlTemplate", 816 "template": "http://example.org{/foo,bar}" 817 "parameters": { 818 "foo": "http://example.org/FooProperty", 819 "bar": { 820 "id": "http://example.org/BarProperty", 821 "displayName": "Bar", 822 "required": False 823 } 824 } 825 } 827 Using the Parameters Object in HtmlForm objects: 829 { 830 "objectType": "HtmlForm", 831 "mediaType": "application/x-www-form-urlencoded", 832 "parameters": { 833 "foo": "http://example.org/FooProperty", 834 "bar": { 835 "objectType": "parameter", 836 "id": "http://example.org/BarProperty", 837 "displayName": "Bar", 838 "required": False 839 } 840 } 841 } 843 This specification defines a Parameter objectType (Section 10.1) 844 specifically designed to describe parameters. 846 Implementations that encounter unrecognized or unexpected objectTypes 847 used to describe parameters will likely be unable to successfully 848 comprehend the parameter and may, therefore, be unable to carry out 849 an Action. 851 10.1. Parameter Object 853 The "parameter" objectType is specifically intended for use with the 854 Parameters (Section 10) object. Each Parameter object provides a 855 rich description of a single parameter. 857 +------------+--------------------------+----------+----------------+ 858 | Property | Value | Required | Description | 859 +------------+--------------------------+----------+----------------+ 860 | required | boolean | No | True if the | 861 | | | | parameter is | 862 | | | | required. | 863 | | | | Defaults to | 864 | | | | true. | 865 | repeated | boolean | No | True if the | 866 | | | | parameter can | 867 | | | | be repeated | 868 | | | | zero or more | 869 | | | | times. | 870 | value | (Any) | No | Provides a | 871 | | | | fixed value | 872 | | | | for the | 873 | | | | parameter. | 874 | | | | When | 875 | | | | specified, imp | 876 | | | | lementations | 877 | | | | MUST use the | 878 | | | | specified | 879 | | | | value. | 880 | default | (Any) | No | Provides a | 881 | | | | default value | 882 | | | | for the | 883 | | | | parameter. | 884 | | | | When | 885 | | | | specified, imp | 886 | | | | lementations | 887 | | | | MUST use the | 888 | | | | specified | 889 | | | | value if no | 890 | | | | other value is | 891 | | | | not supplied. | 892 | enum | Array of (Any) | No | Provides a | 893 | | | | fixed array of | 894 | | | | possible | 895 | | | | values for the | 896 | | | | parameter. | 897 | | | | When | 898 | | | | specified, imp | 899 | | | | lementations | 900 | | | | MUST use one | 901 | | | | of the | 902 | | | | specified | 903 | | | | values. | 904 | maximum | (Any) | No | A value that | 905 | | | | is considered | 906 | | | | to be the | 907 | | | | upper bound of | 908 | | | | a range of | 909 | | | | possible | 910 | | | | values. This | 911 | | | | would | 912 | | | | typically be | 913 | | | | used only with | 914 | | | | numeric | 915 | | | | parameters. | 916 | minimum | (Any) | No | A value that | 917 | | | | is considered | 918 | | | | to be the | 919 | | | | lower bound of | 920 | | | | a range of | 921 | | | | possible | 922 | | | | values. This | 923 | | | | would | 924 | | | | typically be | 925 | | | | used only with | 926 | | | | numeric | 927 | | | | parameters. | 928 | step | Non-negative Number | No | Specifies the | 929 | | | | legal numeric | 930 | | | | interval | 931 | | | | between | 932 | | | | acceptable | 933 | | | | values for the | 934 | | | | parameter. The | 935 | | | | step value | 936 | | | | MUST be a | 937 | | | | number and | 938 | | | | MUST conform | 939 | | | | to the given | 940 | | | | format if a | 941 | | | | format is | 942 | | | | specified. For | 943 | | | | instance, if | 944 | | | | format is | 945 | | | | "uint32", then | 946 | | | | step=2 would | 947 | | | | indicate legal | 948 | | | | values of 0, | 949 | | | | 2, 4, 6, and | 950 | | | | so on. The | 951 | | | | step property | 952 | | | | MAY be ignored | 953 | | | | if it's value | 954 | | | | does not | 955 | | | | correspond to | 956 | | | | the expected | 957 | | | | format. | 958 | format | String | No | A string that | 959 | | | | describes the | 960 | | | | format of the | 961 | | | | value. The | 962 | | | | format can be | 963 | | | | one of the | 964 | | | | list of | 965 | | | | standard | 966 | | | | formats listed | 967 | | | | below or any | 968 | | | | other string. | 969 | | | | If an | 970 | | | | implementation | 971 | | | | encounters a | 972 | | | | format string | 973 | | | | it does not | 974 | | | | recognize, the | 975 | | | | format | 976 | | | | property MAY | 977 | | | | be ignored. | 978 | | | | When not | 979 | | | | specified, the | 980 | | | | value format | 981 | | | | is assumed to | 982 | | | | be a sequence | 983 | | | | of UTF-8 | 984 | | | | encoded | 985 | | | | codepoints. | 986 | pattern | String | No | A Regular | 987 | | | | Expression | 988 | | | | that describes | 989 | | | | the structure | 990 | | | | of the value. | 991 | | | | Typically used | 992 | | | | when the value | 993 | | | | is a string. | 994 | placeholde | Natural Language Value [ | No | An optional | 995 | r | I-D.snell-activitystream | | Natural | 996 | | s] | | Language Value | 997 | | | | providing a | 998 | | | | text hint that | 999 | | | | describes the | 1000 | | | | expected value | 1001 | | | | of the | 1002 | | | | parameter. | 1003 +------------+--------------------------+----------+----------------+ 1005 The following common format strings MAY be used as values for the 1006 "format" property: 1008 o "boolean" - Specifies that the value is either a string specifying 1009 "true" or "false", a boolean True or False, or an integer where 0 1010 represents False and any other value represents True. 1012 o "byte" - Specifies that the value is a "URL and filename safe" 1013 Base64-encoded string of bytes as defined by [RFC4648]. 1015 o "hex" - Specifies that the value is a String containing a sequence 1016 of Hex-encoded bytes. 1018 o "date" - Specifies that the value is a "full-date" (YYYY-MM-DD) as 1019 defined by [RFC3339]. 1021 o "date-time" - Specifies that the value is a "date-time" as defined 1022 by [RFC3339]. 1024 o "double" - Specifies that the value is a double-precision 64-bit 1025 IEEE 754 floating point value. 1027 o "duration" - Specifies that the value is a "duration" as defined 1028 by [RFC3339]. 1030 o "float" - Specifies that the value is a single-precision 32-bit 1031 IEEE 754 floating point. 1033 o "int32" - Specifies that the value is a signed, 32-bit integer in 1034 the range -2,147,483,648 to 2,147,483,647 (inclusive). 1036 o "int64" - Specifies that the value is a signed, 64-bit integer in 1037 the range -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 1038 (inclusive). 1040 o "uint32" - Specifies that the value is an unsigned 32-bit integer 1041 in the range 0 to 4,294,967,295 (inclusive). 1043 o "uint64" - Specifies that the value is an unsigned 64-bit integer 1044 in the range 0 to (2^64)-1 (inclusive) 1046 o "lang" - Specifies that the value is a Language Tag as defined by 1047 [RFC5646]. 1049 o "uri" - Specifies that the value is a string containing a URI as 1050 defined by [RFC3986]. 1052 o "iri" - Specifies that the value is a string containing an IRI as 1053 defined by [RFC3987]. 1055 Using the Parameter Object in HtmlForm objects: 1057 { 1058 "objectType": "HtmlForm", 1059 "mediaType": "application/x-www-form-urlencoded", 1060 "parameters": { 1061 "foo": "http://example.org/FooProperty", 1062 "bar": { 1063 "objectType": "parameter", 1064 "id": "http://example.org/BarProperty", 1065 "displayName": "Bar", 1066 "required": False, 1067 "repeated": False, 1068 "format": "uint32", 1069 "defaultValue": 3, 1070 "minimum": 1, 1071 "maximum": 5 1072 } 1073 } 1074 } 1076 10.2. Using UrlTemplate and TypedPayload objects as parameter 1077 descriptions 1079 In certain cases, when the value of a parameter is expected to be 1080 either a URI or IRI, the UrlTemplate objectType (Section 9) MAY be 1081 used as the parameter description. In such cases, the "required", 1082 "repeated", "default" and "placeholder" properties from the Parameter 1083 objectType (Section 10.1) can be used as additional properties within 1084 the UrlTemplate object. 1086 For example: 1088 { 1089 "objectType": "HtmlForm", 1090 "mediaType": "application/x-www-form-urlencoded", 1091 "parameters": { 1092 "foo": "http://example.org/FooProperty", 1093 "bar": { 1094 "objectType": "UrlTemplate", 1095 "id": "http://example.org/BarProperty", 1096 "template": "http://example.org{/foo}", 1097 "parameters": { 1098 "foo": "http://example.org/#string" 1099 }, 1100 "displayName": "Bar", 1101 "required": False, 1102 "repeated": False 1103 } 1104 } 1105 } 1107 Likewise, when the value of a parameter is expected to be an instance 1108 of a specific MIME media type, the TypedPayload objectType 1109 (Section 8) can be used. 1111 { 1112 "objectType": "HtmlForm", 1113 "mediaType": "multipart/form-data", 1114 "parameters": { 1115 "file": { 1116 "objectType": "TypedPayload", 1117 "mediaType": "image/*", 1118 "required": True, 1119 "repeated": True 1120 } 1121 } 1122 } 1124 11. Authentication Object 1126 An Authentication Object is used by Action Handlers that require 1127 specific authentication options to be supported in order to carry out 1128 the Action. The object is expresed as a JSON dictionary mapping 1129 authentication schema labels to JSON dictionaries that provide a 1130 specific description of properties and requirements specific to the 1131 scheme. 1133 Example Authentication details: 1135 { 1136 "objectType": "note", 1137 "displayName": "A simple note object", 1138 "content": "This is a simple note", 1139 "actions": { 1140 "view": { 1141 "objectType": "HttpActionHandler", 1142 "method": "GET", 1143 "url": "http://example.org/notes/1", 1144 "auth": { 1145 "basic": { 1146 "realm": "http://example.org" 1147 }, 1148 "oauth": { 1149 "scopes": [ 1150 "some.oauth.scope", 1151 "another.oauth.scope" 1152 ] 1153 } 1154 } 1155 } 1156 } 1157 } 1159 This specification does not define the authentication schemes or 1160 their associated properties. Unrecognized authentication schemes MAY 1161 be ignored. However, if an implementation fails to recognize any of 1162 the authentication schemes specified by an Action Handler, it might 1163 not be possible to successfully carry out the Action. 1165 12. Styles Object 1167 A Styles Object is used by EmbedActionHandlers to provide CSS style 1168 hints for the container within which embedded content is to be 1169 displayed. The object is expressed as either a single JSON 1170 dictionary object mapping CSS property names to appropriate CSS 1171 values, or an array of JSON dictionary objects. An optional "media" 1172 member can be included within the dictionary providing a CSS Media 1173 Query. 1175 Example style hints: 1177 { 1178 "objectType": "note", 1179 "displayName": "A simple note object", 1180 "content": "This is a simple note.", 1181 "actions": { 1182 "view": { 1183 "objectType": "EmbedActionHandler", 1184 "content": "Some plain text content", 1185 "mediaType": "text/plain", 1186 "style": { 1187 "height": "100px", 1188 "width": "100px", 1189 "box-shadow": "10px 10px 5px #888888" 1190 } 1191 } 1192 } 1193 } 1195 Multiple style hints for specific media query targets: 1197 { 1198 "objectType": "note", 1199 "displayName": "A simple note object", 1200 "content": "This is a simple note.", 1201 "actions": { 1202 "view": { 1203 "objectType": "EmbedActionHandler", 1204 "content": "Some plain text content", 1205 "mediaType": "text/plain", 1206 "style": [ 1207 { 1208 "media": "print", 1209 "height": "100px", 1210 "width": "100px", 1211 "box-shadow": "10px 10px 5px #888888" 1212 }, 1213 { 1214 "media": "screen and (orientation: landscape)", 1215 "height": "100px", 1216 "width": "100px", 1217 "box-shadow": "10px 10px 5px #888888" 1218 } 1219 ] 1220 } 1221 } 1222 } 1224 13. Security Considerations 1226 TBD 1228 14. IANA Considerations 1230 TBD 1232 15. Normative References 1234 [I-D.snell-activitystreams] 1235 Snell, J., "JSON Activity Streams 2.0", draft-snell- 1236 activitystreams-05 (work in progress), November 2013. 1238 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1239 Requirement Levels", BCP 14, RFC 2119, March 1997. 1241 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1242 Internet: Timestamps", RFC 3339, July 2002. 1244 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1245 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1246 3986, January 2005. 1248 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1249 Identifiers (IRIs)", RFC 3987, January 2005. 1251 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1252 Encodings", RFC 4648, October 2006. 1254 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1255 Languages", BCP 47, RFC 5646, September 2009. 1257 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1258 and D. Orchard, "URI Template", RFC 6570, March 2012. 1260 Appendix A. Using Action Handlers From Other Vocabularies 1262 The Activity Streams 2.0 Actions mechanism is specifically designed 1263 to allow Action Handlers from multiple vocabularies. 1265 A.1. Schema.org Actions Proposal 1267 Based on http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf: 1269 { 1270 "objectType": "video", 1271 "displayName": "A simple note object", 1272 "content": "This is a simple note.", 1273 "actions": { 1274 "watch": [ 1275 { 1276 "objectType": "http://schema.org/WebPageHandler", 1277 "url": "http://movies.example.com/player?id=123" 1278 }, 1279 { 1280 "objectType": "http://schema.org/AndroidHandler", 1281 "url": "http://movies.example.com/player?id=123", 1282 "package": "com.movies" 1283 } 1284 ] 1285 } 1286 } 1288 A.2. Google's "Actions in the Inbox" 1290 Based on https://developers.google.com/gmail/actions/reference/ 1291 review-action: 1293 { 1294 "objectType": "note", 1295 "displayName": "A simple note object", 1296 "content": "This is a simple note.", 1297 "actions": { 1298 "review": { 1299 "objectType": "http://schema.org/ReviewAction", 1300 "review": { 1301 "objectType": "http://schema.org/Review", 1302 "itemReviewed": { 1303 "objectType": "http://schema.org/FoodEstablishment", 1304 "name": "Joe's Diner" 1305 }, 1306 "reviewRating": { 1307 "objectType": "http://schema.org/Rating", 1308 "bestRating": "5", 1309 "worstRating": "1" 1310 } 1311 }, 1312 "handler": { 1313 "objectType": "http://schema.org/HttpActionHandler", 1314 "url": "http://reviews.com/review?id=123", 1315 "requiredProperty": { 1316 "objectType": "http://schema.org/Property", 1317 "name": "review.reviewRating.ratingValue" 1318 }, 1319 "method": "http://schema.org/HttpRequestMethod/POST" 1320 } 1321 } 1322 } 1323 } 1325 A.3. Mixing Vocabularies 1326 { 1327 "objectType": "video", 1328 "displayName": "A simple note object", 1329 "content": "This is a simple note.", 1330 "actions": { 1331 "watch": [ 1332 { 1333 "objectType": "HttpActionHandler", 1334 "url": "http://movies.example.com/player?id=123", 1335 "target": "NEW" 1336 }, 1337 { 1338 "objectType": "http://schema.org/AndroidHandler", 1339 "url": "http://movies.example.com/player?id=123", 1340 "package": "com.movies" 1341 } 1342 ] 1343 } 1344 } 1346 A.4. Example Drawing From Multiple Vocabularies 1348 { 1349 "objectType": "video", 1350 "displayName": "A Movie!", 1351 "displayName": "A simple note object", 1352 "content": "This is a simple note.", 1353 "actions": { 1354 "watch": [ 1355 { 1356 "objectType": "EmbedActionHandler", 1357 "displayName": "HD", 1358 "mediaType": "video/mpeg", 1359 "url": "http://cdn.example.org?id=123amp;fmt=HD", 1360 }, 1361 { 1362 "objectType": "EmbedActionHandler", 1363 "displayName": "SD", 1364 "mediaType": "video/mpeg", 1365 "url": "http://cdn.example.org?id=123&fmt=SD", 1366 }, 1367 { 1368 "objectType": "application", 1369 "displayName": "Watch on Netflix", 1370 "url": "http://netflix.com..." 1371 } 1372 ], 1373 "like": { 1374 "objectType": "EmbedActionHandler", 1375 "mediaType": "text/html", 1376 "url": "http://www.facebook.com/plugins/like.php...", 1377 "style": { 1378 "width": "150px", 1379 "height": "50px" 1380 } 1381 }, 1382 "share": [ 1383 { 1384 "objectType": "HttpActionHandler", 1385 "displayName": "Twitter", 1386 "url": "https://twitter.com/share?url=...", 1387 "target": "DIALOG" 1388 }, 1389 { 1390 "objectType": "HttpActionHandler", 1391 "displayName": "Facebook", 1392 "url": "https://www.facebook.com/sharer/sharer.php?u=...", 1393 "target": "DIALOG" 1394 } 1395 ], 1396 "save": [ 1397 { 1398 "objectType": "service", 1399 "id": "http://getpocket.com", 1400 "displayName": "Pocket", 1401 "context": { 1402 "url": "http://example.org/movie?id=123", 1403 "title": "A Movie!", 1404 "tags": "foo, bar, baz" 1405 } 1406 }, 1407 { 1408 "objectType": "service", 1409 "id": "http://instapaper.com", 1410 "displayName": "Instapaper", 1411 "context": { 1412 "url": "http://example.org/movie?id=123", 1413 "title": "A Movie!", 1414 "selection": "An action movie!" 1415 } 1416 } 1417 ], 1418 "review": { 1419 "objectType": "HttpActionHandler", 1420 "displayName": "Rate this movie!", 1421 "url": "http://review.example.org/movie?id=123", 1422 "method": "POST", 1423 "expects": { 1424 "objectType": "HtmlForm", 1425 "mediaType": "application/x-www-form-urlencoded", 1426 "parameters": { 1427 "rating": { 1428 "id": "http://schema.org/ratingValue", 1429 "maximum": 5, 1430 "minimum": 0, 1431 "format": "uint32", 1432 "displayName": "Rating", 1433 "required": true 1434 }, 1435 "comments": { 1436 "id": "http://schema.org/commentText", 1437 "displayName": "Comments", 1438 "required": "false" 1439 } 1440 } 1441 } 1442 } 1443 } 1444 } 1446 Authors' Addresses 1448 James M Snell 1449 IBM 1451 Email: jasnell@gmail.com 1453 Matthew Marum 1454 SugarCRM 1456 Email: mgmarum@gmail.com