idnits 2.17.1 draft-snell-activitystreams-09.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 date (May 27, 2014) is 3621 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: 'RFC6963' is defined on line 1524, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 2 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, Ed. 3 Internet-Draft IBM 4 Intended status: Standards Track May 27, 2014 5 Expires: November 28, 2014 7 JSON Activity Streams 2.0 8 draft-snell-activitystreams-09 10 Abstract 12 This specification details a model for representing potential and 13 completed activities using the JSON format. 15 Author's Note 17 This draft is heavily influenced by the original JSON Activity 18 Streams 1.0 specification that was originally co-authored by Martin 19 Atkins, Will Norris, Chris Messina, Monica Wilkinson, Rob Dolin and 20 James Snell. The author is very thankful for their significant 21 contributions and gladly stands on their shoulders. Some portions of 22 the original text of Activity Streams 1.0 are used in this document. 24 The Activity Streams 1.0 and 2.0 specifications are works produced by 25 the Activity Streams Working Group (http://activitystrea.ms/) 26 operating independently of the IETF. Discussion and feedback about 27 this specification is invited and should be directed to the Activity 28 Streams Mailing List (see https://groups.google.com/forum/#!forum/ 29 activity-streams). 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on November 28, 2014. 48 Copyright Notice 50 Copyright (c) 2014 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Relationship to JSON Activity Streams 1.0 . . . . . . . . 3 67 1.2. Syntax Conventions . . . . . . . . . . . . . . . . . . . 4 68 2. Example Activities . . . . . . . . . . . . . . . . . . . . . 5 69 2.1. Example 1: Minimal Activity . . . . . . . . . . . . . . . 5 70 2.2. Example 2: Basic activity with some additional detail . . 5 71 2.3. Example 3: An extended activity . . . . . . . . . . . . . 6 72 3. Object Model . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.1. Object . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 3.2. Natural Language Values . . . . . . . . . . . . . . . . . 9 75 3.3. Type Values . . . . . . . . . . . . . . . . . . . . . . . 10 76 3.4. Link Values . . . . . . . . . . . . . . . . . . . . . . . 12 77 3.5. Activity . . . . . . . . . . . . . . . . . . . . . . . . 14 78 3.5.1. Considerations on the use of "priority" . . . . . . . 16 79 3.5.2. Audience Targeting Properties . . . . . . . . . . . . 17 80 3.6. Additional Object Properties . . . . . . . . . . . . . . 18 81 3.6.1. Action Values . . . . . . . . . . . . . . . . . . . . 22 82 3.7. Collection . . . . . . . . . . . . . . . . . . . . . . . 23 83 3.7.1. Using Collections as Summary Values . . . . . . . . . 25 84 4. The Activity Stream JSON Document . . . . . . . . . . . . . . 26 85 5. Reserved Object Types and Verbs . . . . . . . . . . . . . . . 26 86 5.1. Object Types . . . . . . . . . . . . . . . . . . . . . . 26 87 5.2. Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . 26 88 6. Deprecated Activity Streams 1.0 Syntax . . . . . . . . . . . 27 89 7. Comparison of Identifier Values . . . . . . . . . . . . . . . 28 90 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28 91 8.1. Extension verbs and objectTypes . . . . . . . . . . . . . 28 92 9. Using JSON-LD to Process Activity Streams Documents . . . . . 29 93 9.1. Handling of Compact IRIs . . . . . . . . . . . . . . . . 30 94 10. Security Considerations . . . . . . . . . . . . . . . . . . . 31 95 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 96 11.1. application/activity+json Media Type . . . . . . . . . . 32 97 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 98 12.1. Normative References . . . . . . . . . . . . . . . . . . 33 99 12.2. Informational References . . . . . . . . . . . . . . . . 34 100 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 34 101 Appendix B. Processing as JSON-LD . . . . . . . . . . . . . . . 35 102 Appendix C. Activity Statement Linguistic Forms . . . . . . . . 41 103 C.1. Intransitive Activity . . . . . . . . . . . . . . . . . . 41 104 C.2. Transitive Activity . . . . . . . . . . . . . . . . . . . 42 105 C.3. Ditransitive Activity . . . . . . . . . . . . . . . . . . 42 106 C.4. Expressing tense and aspect . . . . . . . . . . . . . . . 43 107 C.5. Activity Duration . . . . . . . . . . . . . . . . . . . . 45 108 Appendix D. Motivational Use Cases . . . . . . . . . . . . . . . 46 109 D.1. Internationalization (i18n) . . . . . . . . . . . . . . . 46 110 D.2. Extensibility (e11y) . . . . . . . . . . . . . . . . . . 48 111 D.2.1. Publishing Extension objectType and verb Libraries . 49 112 D.3. First Class Links . . . . . . . . . . . . . . . . . . . . 50 113 D.4. Use of External Vocabularies . . . . . . . . . . . . . . 51 114 D.5. Embedded Actions . . . . . . . . . . . . . . . . . . . . 52 115 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 53 117 1. Introduction 119 In the most basic sense, an "activity" is a semantic description of 120 potential or completed actions. In the former case, the activity 121 expresses what can be done with a particular object, while in the 122 latter case, it expresses what has already been done. 124 It is the goal of this specification to provide a JSON-based syntax 125 that is sufficient to express metadata about activities in a rich, 126 human-friendly, machine-processable and extensible manner. This may 127 include constructing natural-language descriptions or visual 128 representations about the activity, associating actionable 129 information with various types of objects, communicating or recording 130 activity logs, or delegation of potential actions to other 131 applications. 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. 137 1.1. Relationship to JSON Activity Streams 1.0 139 The JSON Activity Streams 1.0 [activitystreams-1.0] specification was 140 published in May of 2011 and provided a baseline extensible syntax 141 for the expression of completed activities. This specification 142 builds upon that initial foundation by incorporating lessons learned 143 through extensive implementation, community feedback and related work 144 being performed in other standards development communities. 146 While the syntax defined by this specification diverges somewhat from 147 that defined by JSON Activity Streams 1.0, the verbs, objectTypes, 148 extensions and fundamental model defined by that original 149 specification remain intact. 151 Refer to Section 6 for more detail about the differences between the 152 1.0 and 2.0 syntax and for a listing of specific backwards 153 compatibility requirements. 155 This specification incorporates several existing extensions to the 156 1.0 syntax directly into the 2.0 model. These include portions of 157 the Activity Streams 1.0 Base Schema [base-schema], Audience 158 Targeting [audience], Responses [responses], and Priority [priority] 159 extensions. 161 1.2. Syntax Conventions 163 This specification defines a JSON-based [RFC4627] serialization 164 syntax. 166 When serialized, absent properties are represented by either (a) 167 setting the property value to null, or (b) by omitting the property 168 declaration altogether at the option of the publisher; these 169 representations are semantically equivalent. If a property has an 170 array value, the absence of any items in that array MUST be 171 represented by omitting the property entirely or by setting the value 172 to null. 174 This specification uses IRIs [RFC3987]. Every URI [RFC3986] is also 175 an IRI, so a URI may be used wherever an IRI is named. There are two 176 special considerations: (1) when an IRI that is not also a URI is 177 given for dereferencing, it MUST be mapped to a URI using the steps 178 in Section 3.1 of [RFC3987] and (2) when an IRI is serving as an "id" 179 value, it MUST NOT be so mapped. 181 Unless otherwise specified, all properties with date and time values 182 MUST conform to the "date-time" production in [RFC3339], with an 183 uppercase "T" character used to separate date and time, and an 184 uppercase "Z" character in the absence of a numeric time zone offset. 185 All such timestamps SHOULD be represented relative to Coordinated 186 Universal Time (UTC). 188 2. Example Activities 190 Following are three examples of activities with varying degrees of 191 detail. 193 2.1. Example 1: Minimal Activity 195 Expresses the statement "'urn:example:person:martin' posted 196 'http://example.org/foo.jpg'". No additional detail is given. 198 { 199 "verb": "post", 200 "actor": "urn:example:person:martin", 201 "object": "http://example.org/foo.jpg" 202 } 204 2.2. Example 2: Basic activity with some additional detail 206 Expresses the statement "Martin Smith posted an article to the blog 207 'Martin's Blog' at 3:04 PM GMT on February 2, 2011." Some additional 208 details about the article, actor and target blog are given. 210 { 211 "verb": "post", 212 "published": "2011-02-10T15:04:55Z", 213 "language": "en", 214 "actor": { 215 "objectType": "person", 216 "id": "urn:example:person:martin", 217 "displayName": "Martin Smith", 218 "url": "http://example.org/martin", 219 "image": { 220 "url": "http://example.org/martin/image.jpg", 221 "mediaType": "image/jpeg", 222 "width": 250, 223 "height": 250 224 } 225 }, 226 "object" : { 227 "objectType": "article", 228 "id": "urn:example:blog:abc123/xyz" 229 "url": "http://example.org/blog/2011/02/entry", 230 "displayName": "Why I love Activity Streams" 231 }, 232 "target" : { 233 "objectType": "blog", 234 "id": "urn:example:blog:abc123", 235 "displayName": "Martin's Blog", 236 "url": "http://example.org/blog/" 237 } 238 } 240 2.3. Example 3: An extended activity 242 A more extensive, single-entry "Activity Stream" follows. In 243 addition to containing a number of required and optional core 244 properties, the example contains the additional, undefined extension 245 properties "foo" and "foo2" for illustrative purposes only. 247 { 248 "totalItems": 1, 249 "items" : [ 250 { 251 "verb": "post", 252 "language": "en", 253 "published": "2011-02-10T15:04:55Z", 254 "foo": "some extension property", 255 "generator": "http://example.org/activities-app", 256 "provider": "http://example.org/activity-stream", 257 "displayName": { 258 "en": "Martin posted a new video to his album.", 259 "ga": "Martin phost le fisean nua a albam." 260 }, 261 "actor": { 262 "objectType": "person", 263 "id": "urn:example:person:martin", 264 "displayName": "Martin Smith", 265 "url": "http://example.org/martin", 266 "foo2": "some other extension property", 267 "image": { 268 "url": "http://example.org/martin/image", 269 "mediaType": "image/jpeg", 270 "width": 250, 271 "height": 250 272 } 273 }, 274 "object" : { 275 "objectType": { 276 "id": "http://example.org/Photo", 277 "displayName": "Photo" 278 }, 279 "id": "urn:example:album:abc123/my_fluffy_cat", 280 "url": "http://example.org/album/my_fluffy_cat.jpg", 281 "image": { 282 "url": "http://example.org/album/my_fluffy_cat_thumb.jpg", 283 "mediaType": "image/jpeg", 284 "width": 250, 285 "height": 250 286 } 287 }, 288 "target": { 289 "objectType": { 290 "id": "http://example.org/PhotoAlbum", 291 "displayName": "Photo-Album" 292 }, 293 "id": "urn:example.org:album:abc123", 294 "url": "http://example.org/album/", 295 "displayName": { 296 "en": "Martin's Photo Album", 297 "ga": "Grianghraif Mairtin" 298 }, 299 "image": { 300 "url": "http://example.org/album/thumbnail.jpg", 301 "mediaType": "image/jpeg", 302 "width": 250, 303 "height": 250 304 } 305 } 307 } 308 ] 309 } 311 3. Object Model 313 3.1. Object 315 The following "core properties" apply to all JSON objects serialized 316 within an Activity Stream document. 318 +-------------+---------------+-------------------------------------+ 319 | Property | Value | Description | 320 +-------------+---------------+-------------------------------------+ 321 | id | IRI | Provides a permanent, universally | 322 | | | unique identifier for the object in | 323 | | | the form of an absolute IRI | 324 | | | [RFC3987]. Objects SHOULD contain | 325 | | | a single "id" property. If an | 326 | | | object does not contain an "id" | 327 | | | property, consumers MAY use the | 328 | | | value of the "url" property as a | 329 | | | less-reliable, non-unique | 330 | | | identifier. | 331 | objectType | Type value | Identifies the type of object. An | 332 | | (Section 3.3) | object MAY contain a "objectType" | 333 | | | property whose value is a Type | 334 | | | value (Section 3.3). If no | 335 | | | "objectType" property is specified, | 336 | | | the object has no specific type. | 337 | language | [RFC5646] | Establishes the default language | 338 | | Language Tag | assumed for human-readable, | 339 | | | natural-language metadata values | 340 | | | included in the object. An object | 341 | | | MAY contain a "language" property | 342 | | | whose value MUST be a [RFC5646] | 343 | | | Language-Tag. | 344 | displayName | Natural | A simple human-readable, plain-text | 345 | | Language | name for the object. HTML markup | 346 | | value | MUST NOT be included. An object MAY | 347 | | (Section 3.2) | contain a "displayName" property. | 348 | | | If the object does not specify a | 349 | | | "objectType" property, the object | 350 | | | SHOULD specify a "displayName". | 351 | url | Link (Section | A Link (Section 3.4) value | 352 | | 3.4) value | describing a resource that provides | 353 | | | a representation of the object. An | 354 | | | object MAY contain a "url" | 355 | | | property. | 356 +-------------+---------------+-------------------------------------+ 358 3.2. Natural Language Values 360 Natural Language values represent human-readable character sequences 361 in one or more languages. They are expressed as either (1) a single 362 JSON string or (2) a JSON dictionary mapping [RFC5646] Language-Tags 363 to localized, equivalent translations of the same string value. 365 For instance, the "displayName" property in all objects is a Natural 366 Language value. 368 A single String value using the default language: 370 { 371 "language": "en", 372 "displayName": "This is the title" 373 } 375 Multiple, language-specific values: 377 { 378 "displayName": { 379 "en": "This is the title", 380 "fr": "C'est le titre", 381 "sp": "Este es el titulo" 382 } 383 } 385 Each key in the JSON dictionary MUST be an [RFC5646] Language Tag. 386 The associated values MUST be Strings. 388 3.3. Type Values 390 Type values represent references to or descriptions of an abstract 391 type. They are expressed as either: (1) a String conforming to 392 either the "isegment-nz-nc" or "IRI" productions in [RFC3987] or (2) 393 an Object (Section 3.1). When represented as a String, the use of 394 relative references other than a simple name is not allowed. When 395 represented as an Object, the "id" property MUST be specified. 397 Within the Activity Streams 2.0, Type values are used only by the 398 "objectType" and "verb" properties. 400 Object type as a simple name (isegment-nz-nc): 402 { 403 "objectType": "person", 404 "displayName": "John" 405 } 407 Object type as an absolute IRI: 409 { 410 "objectType": "http://example.org/Person", 411 "displayName": "John" 412 } 414 Object type as an object: 416 { 417 "objectType": { 418 "id": "http://example.org/Person", 419 "displayName": "Person" 420 }, 421 "displayName": "John" 422 } 424 Because the second and third examples above each specify 425 "http://example.org/Person", the two examples are considered to 426 specify the same type. 428 Verb as a simple name (isegment-nz-nc): 430 { 431 "verb": "post", 432 "actor": "acct:john.doe@example.org", 433 "object": "http://example.org/123" 434 } 436 Verb as an absolute IRI: 438 { 439 "verb": "http://example.com/Upload", 440 "actor": "acct:john.doe@example.org", 441 "object": "http://example.org/123" 442 } 444 Verb as an object: 446 { 447 "verb": { 448 "id": "http://example.com/Upload", 449 "displayName": "Upload" 450 }, 451 "actor": "acct:john.doe@example.org", 452 "object": "http://example.org/123" 453 } 455 Allowing verbs and object types to be represented as objects rather 456 than simple names or IRIs is intended to simplify the use of 457 extensions that an implementation might not have encountered 458 previously. The object properties provide additional information and 459 metadata about the new verb or object type. 461 It is important to note that because the "id" property is strictly 462 limited to absolute IRI values, the object representation cannot be 463 used to describe types with simple names. 465 3.4. Link Values 467 Link values represent references to other objects and resources. 468 They are expressed as either: (1) a String containing an absolute or 469 relative IRI, (2) an Object (Section 3.1), or (3) a JSON Array 470 containing a mixture of IRIs or Objects (Section 3.1). Link values 471 are closely related to the conceptual model of Links as established 472 in [RFC5988]. 474 For example, as defined previously, all objects (Section 3.1) can 475 contain an "image" property whose value describes a graphical 476 representation of the containing object. This property will 477 typically be used to provide the URL to a JPEG, GIF or PNG type 478 resource that can be displayed to the user. Any given object might 479 have multiple such visual representations -- multiple screenshots, 480 for instance, or the same image at different resolutions. Using Link 481 values, there are essentially three ways of describing such 482 references. 484 To reference a single image without any additional metadata, the link 485 value can be expressed as a simple JSON string containing an absolute 486 or relative IRI: 488 { 489 "objectType": "application", 490 "id": "http://example.org/application/123", 491 "displayName": "My Application", 492 "image": "http://example.org/application/123.png" 493 } 495 Alternatively, if additional metadata is required, the link can be 496 expressed as an object containing the url property. 498 { 499 "objectType": "application", 500 "id": "http://example.org/application/123", 501 "displayName": "My Application", 502 "image": { 503 "url": "http://example.org/application/123.png", 504 "mediaType": "image/png", 505 "height": 320, 506 "width": 320 507 } 508 } 510 If more than one link value is to be expressed, A JSON Array with a 511 mix of string and object elements can be used: 513 { 514 "objectType": "application", 515 "id": "http://example.org/application/123", 516 "displayName": "My Application", 517 "image": [ 518 "http://example.org/application/abc.gif", 519 { 520 "url": "http://example.org/application/123.png", 521 "mediaType": "image/png", 522 "height": 320, 523 "width": 320 524 } 525 ] 526 } 528 Individual items contained in such an array are independent of the 529 others and no significance is given to the ordering of those items. 531 RFC 5988 defines that all Links have a "link relation" that describes 532 the contextual purpose of the link. Within an object (Section 3.1), 533 in the absence of a specific "rel" property within the link object 534 itself, the name of the property whose value is a link serves as the 535 "link relation". Any valid link relation value, as defined by RFC 536 5988, can be used as a property with a link value in any Activity 537 Streams object, except where the link relation might conflict with 538 any other property defined by this specification. 540 In the following example, two separate links are provided. The link 541 relation of the first is "image", while the link relation of the 542 second is "preview". Both links, however, can be used as alternative 543 visual representations of the "application" object. 545 { 546 "objectType": "application", 547 "image": [ 548 "http://example.org/foo.jpg", 549 { 550 "url": "http://example.org/screens/1.jpg", 551 "rel": "preview", 552 "mediaType": "image/jpeg" 553 } 554 ] 555 } 557 When an object (Section 3.1) is used to represent a Link value, the 558 following additional properties MAY be used: 560 +-----------+---------------+---------------------------------------+ 561 | Property | Value | Description | 562 +-----------+---------------+---------------------------------------+ 563 | rel | RFC 5988 Link | The RFC 5988 Link Relation associated | 564 | | Relation | with this link value. If absent, the | 565 | | | name of the property is assumed to | 566 | | | specify the link relation. | 567 | mediaType | MIME Media | The MIME media type of the resource | 568 | | Type | being referenced. | 569 +-----------+---------------+---------------------------------------+ 571 3.5. Activity 573 Activity objects are specializations of the base Object (Section 3.1) 574 type that provide metadata about potential or completed actions. 576 Within an Activity object, the "verb" property is used to identify 577 the type of activity. All existing verb definitions used in JSON 578 Activity Streams 1.0 implementations can continue to be used and 579 retain their existing semantics. If the "verb" is not specified, the 580 "objectType" property MAY be used as an alternative means of 581 determining the activity type. 583 Activity objects extend the core object (Section 3.1) definition with 584 the following additional, optional properties: 586 +-------------+---------------+-------------------------------------+ 587 | Property | Value | Description | 588 +-------------+---------------+-------------------------------------+ 589 | verb | Type value | Identifies the type of activity. An | 590 | | (Section 3.3) | activity SHOULD contain a "verb" | 591 | | | property whose value is a Type | 592 | | | value (Section 3.3). If the "verb" | 593 | | | property is not specified, the | 594 | | | activity MUST contain a | 595 | | | "objectType" property. | 596 | actor | Link (Section | Describes one or more entities that | 597 | | 3.4) value | either peformed or are expected to | 598 | | | perform the activity. | 599 | object | Link (Section | Describes the direct object of the | 600 | | 3.4) value | activity. For instance, in the | 601 | | | activity, "John saved a movie to | 602 | | | his wishlist", the object of the | 603 | | | activity is "movie". An activity | 604 | | | SHOULD contain an "object" | 605 | | | property. If the "object" property | 606 | | | is not contained, the primary | 607 | | | object of the activity MAY be | 608 | | | implied by context. | 609 | target | Link (Section | Describes the indirect object of | 610 | | 3.4) value | the activity. The precise meaning | 611 | | | of the activity's target is | 612 | | | dependent on the activities "verb", | 613 | | | but will often be the object the | 614 | | | English preposition "to". For | 615 | | | instance, in the activity, "John | 616 | | | saved a movie to his wishlist", the | 617 | | | target of the activity is | 618 | | | "wishlist". The activity target | 619 | | | MUST NOT be used to identify an | 620 | | | indirect object that is not a | 621 | | | target of the activity. | 622 | result | Link (Section | Describes the result of the | 623 | | 3.4) value | activity. For instance, if a | 624 | | | particular action results in the | 625 | | | creation of a new resource, the | 626 | | | "result" property can be used to | 627 | | | describe that new resource. | 628 | instrument | Link (Section | An optional Link Value that | 629 | | 3.4) value | describes one or more objects used | 630 | | | to perform the action. For | 631 | | | instance, in the activity, "Sally | 632 | | | played music with a piano", the | 633 | | | instrument of the activity is the | 634 | | | "piano". | 635 | participant | Link (Section | An optional Link Value that | 636 | | 3.4) value | describes one or more additional | 637 | | | actors that have or will indirectly | 638 | | | participate in the activity. For | 639 | | | instance, in the Activity, "Sally | 640 | | | went to the movies with Joe", Sally | 641 | | | is the primary "actor" while Joe is | 642 | | | a "participant". | 643 | priority | Decimal | An indicator of the relative | 644 | | Number | priority or importance that the | 645 | | between 0.00 | creator of an activity considers | 646 | | and 1.00 | the it to have. Represented as a | 647 | | | numeric decimal between 0.00 and | 648 | | | 1.00, with two decimal places of | 649 | | | precision. If the property is | 650 | | | omitted or set to null, the | 651 | | | assumption is that a default | 652 | | | priority can be assumed. The value | 653 | | | 0.00 represents the lowest possible | 654 | | | priority while 1.00 represents the | 655 | | | highest. | 656 | status | One of | An optional, explicit indicator of | 657 | | "active", | the current status of the Activity. | 658 | | "canceled", | "active" indicates that the | 659 | | "completed", | activity is ongoing; "canceled" | 660 | | "pending", | indicates that the activity has | 661 | | "tentative", | been aborted; "completed" indicates | 662 | | or "voided" | that the activity concluded; | 663 | | | "pending" indicates that the | 664 | | | activity is expected to begin; | 665 | | | "tentative" indicates that the | 666 | | | activity has been proposed; and | 667 | | | "voided" indicates that the | 668 | | | activity statement has been | 669 | | | retracted or should be considered | 670 | | | invalid. | 671 +-------------+---------------+-------------------------------------+ 673 3.5.1. Considerations on the use of "priority" 675 The presence of the "priority" property does not impose any specific 676 processing or display requirements on the part of any entity 677 consuming the activity. 679 Expressing the value as a range of numeric decimal values is intended 680 to provide the greatest level of flexibility in the expression and 681 consumption of prioritization detail. It is expected that 682 implementors consuming activity objects containing "priority" will 683 utilize and expose the additional information in a number of 684 different ways depending on the unique requirements of each 685 application use case. 687 Many existing systems do not represent priority values as numeric 688 ranges. Such systems might use fixed, labeled brackets such as 689 "low", "normal" and "high" or "urgent". Similar mechanisms can be 690 established, by convention, when using the "priority" property. In 691 typical use, it is RECOMMENDED that implementations wishing to work 692 with such defined categories treat "priority" property values in the 693 range 0.00 to 0.25 as "low" priority; values greater than 0.25 to 694 0.75 as "normal" priority; and values greater than 0.75 to 1.00 as 695 "high" priority. Specific implementations are free to establish 696 alternative conventions for the grouping of priority values with the 697 caveat that such conventions likely will not be understood by all 698 implementations. 700 3.5.2. Audience Targeting Properties 702 Every Activity has both a Primary and Secondary audience. The 703 Primary audience consists of those entities either directly involved 704 in the performance of the activity or who "own" the objects involved. 705 The Secondary audience consists of the collection of entities sharing 706 an interest in the activity but who are not directly involved (e.g. 707 "followers"). 709 For instance, suppose a social network of three individuals: Bob, Joe 710 and Jane. Bob and Joe are each friends with Jane but not friends 711 with one another. Bob has chosen to "follow" activities for which 712 Jane is directly involved. Jane shares a file with Joe. 714 In this example, Jane and Joe are each directly involved in the file 715 sharing activity and together make up the Primary Audience for that 716 event. Bob, having an interest in activities involving Jane, is the 717 Secondary Audience. Knowing this, a system that produces or consumes 718 the activity can intelligently notify each person of the event. 720 While there are means, based on the verb, actor, object and target of 721 the activity, to infer the primary audience for many types of 722 activities, those do not work in every case and do not provide a 723 means of identifying the secondary audience. The "to", "cc", "bto" 724 and "bcc" properties MAY be used within an Activity to explicitly 725 identify the Primary and Secondary audiences. 727 +-----------+--------------------+----------------------------------+ 728 | Property | Value | Description | 729 +-----------+--------------------+----------------------------------+ 730 | to | Link (Section 3.4) | Specifies the public primary | 731 | | value | audience. | 732 | cc | Link (Section 3.4) | Specifies the public secondary | 733 | | value | audience. | 734 | bto | Link (Section 3.4) | Specifies the private primary | 735 | | value | audience. | 736 | bcc | Link (Section 3.4) | Specifies the private secondary | 737 | | value | audience. | 738 +-----------+--------------------+----------------------------------+ 740 The prototypical use case for an Activity containing these properties 741 is the publication and redistribution of Activities through an 742 intermediary. That is, an event source generates the activity and 743 publishes it to the intermediary which determines a subset of events 744 to display to specific individual users or groups. Such a 745 determination can be made, in part, by identifying the Primary and 746 Secondary Audiences for each activity. 748 When the event source generates the activity and specifies values for 749 the to and cc fields, the intermediary SHOULD redistribute that event 750 with the values of those fields intact, allowing any processor to see 751 who the activity has been targeted to. This is precisely the same 752 model used by the to and cc fields in email systems. 754 There are situations, however, in which disclosing the identity of 755 specific members of the audience may be inappropriate. For instance, 756 a user may not wish to let other users know that they are interested 757 in various topics, individuals or types of events. To support this 758 option, an event source generating an activity MAY use the "bto" and 759 "bcc" properties to list entities to whom the activity should be 760 privately targeted. When an intermediary receives an activity 761 containing these properties, it MUST remove those values prior to 762 redistributing the activity. The intent is that systems MUST 763 consider entities listed within the "bto" and "bcc" properties as 764 part of the Primary and Second audience but MUST NOT disclose that 765 fact to any other party. 767 Audience targeting information included within an Activity only 768 describes the intent of the activity creator. With clear exception 769 given to the appropriate handling of "bto" and "bcc", this 770 specification leaves it up to implementations to determine how the 771 audience targeting information is used. 773 3.6. Additional Object Properties 775 The following "additional properties" MAY be used with any JSON 776 Object serialized within an Activity Stream document. 778 +-------------+-----------------+-----------------------------------+ 779 | Property | Value | Description | 780 +-------------+-----------------+-----------------------------------+ 781 | alias | IRI | Provides a contextually | 782 | | | meaningful alternative label for | 783 | | | the object in addition to the | 784 | | | "id". For instance, within some | 785 | | | systems, groups can be identified | 786 | | | both by a unique global ID and a | 787 | | | more "human-friendly" label such | 788 | | | as "@friends" or "@network". The | 789 | | | value of the "alias" property | 790 | | | MUST match either the "isegment- | 791 | | | nz-nc" or the "IRI" production in | 792 | | | [RFC3987]. The use of a relative | 793 | | | reference other than a simple | 794 | | | name is not allowed. | 795 | attachments | Link (Section | A Link (Section 3.4) value | 796 | | 3.4) value | referencing one or more objects | 797 | | | associated with the containing | 798 | | | object. These are similiar in | 799 | | | concept to files attached to an | 800 | | | email message. | 801 | author | Link (Section | A Link (Section 3.4) value | 802 | | 3.4) value | referencing one or more entity | 803 | | | that created or authored the | 804 | | | object. | 805 | content | Natural | A Natural-language description of | 806 | | Language value | the object encoded as a single | 807 | | (Section 3.2) | JSON String containing HTML | 808 | | | markup. Visual elements such as | 809 | | | thumbnail images MAY be included. | 810 | duplicates | Link (Section | A Link (Section 3.4)value | 811 | | 3.4) value | referencing one or more objects | 812 | | | that are semantically equivalent | 813 | | | to this object or duplicate this | 814 | | | objects content. An object SHOULD | 815 | | | contain a "duplicates" property | 816 | | | when there are known objects, | 817 | | | possibly in a different system, | 818 | | | that are semantically equivalent | 819 | | | or duplicate the content. | 820 | icon | Link (Section | A Link (Section 3.4) value | 821 | | 3.4) value | referencing one or more visual, | 822 | | | graphic representations of the | 823 | | | object, intended for human | 824 | | | consumption. The visual element | 825 | | | SHOULD have an aspect ratio of | 826 | | | one (horizontal) to one | 827 | | | (vertical) and SHOULD be suitable | 828 | | | for presentation at a small size. | 829 | image | Link (Section | A Link (Section 3.4) value | 830 | | 3.4) value | referencing one or more visual, | 831 | | | graphic represenations of the | 832 | | | object. Unlike the "icon" | 833 | | | property, there are no aspect | 834 | | | ratio or display restrictions. | 835 | location | Link (Section | A Link (Section 3.4) value | 836 | | 3.4) value | describing one or more physical | 837 | | | or virtual locations associated | 838 | | | with which the object. | 839 | published | [RFC3339] date- | The date and time at which the | 840 | | time | object was published. | 841 | generator | Link (Section | A Link (Section 3.4) value | 842 | | 3.4) value | referencing the application that | 843 | | | generated the object. | 844 | provider | Link (Section | A Link (Section 3.4) value | 845 | | 3.4) value | referencing the application that | 846 | | | published the object. Note that | 847 | | | this is not necessarily the same | 848 | | | entity that generated the object. | 849 | summary | Natural | A Natural-language summarization | 850 | | Language value | of the object encoded as a single | 851 | | (Section 3.2) | JSON String containing a fragment | 852 | | | of HTML markup. Visual elements | 853 | | | such as thumbnail images can be | 854 | | | included. | 855 | updated | [RFC3339] date- | The date and time at which a | 856 | | time | previously published object has | 857 | | | been modified. | 858 | startTime | [RFC3339] date- | A date-time describing the actual | 859 | | time | or expected starting time of the | 860 | | | object. When used within an | 861 | | | Activity object, for instance, | 862 | | | the "startTime" specifies the | 863 | | | moment the activity began or is | 864 | | | scheduled to begin. | 865 | endTime | [RFC3339] date- | A date-time describing the actual | 866 | | time | or expected ending time of the | 867 | | | object. When used within an | 868 | | | Activity object, for instance, | 869 | | | the "endTime" specifies the | 870 | | | moment the activity concluded or | 871 | | | is scheduled to conclude. | 872 | validFrom | [RFC3339] date- | A date-time indicating a moment | 873 | | time | at or after which (inclusive) the | 874 | | | object is considered to be valid. | 875 | validAfter | [RFC3339] date- | A date-time indicating a moment | 876 | | time | after which (exclusive) the | 877 | | | object is considered to be valid. | 878 | validUntil | [RFC3339] date- | A date-time indicating a moment | 879 | | time | at or before which (inclusive) | 880 | | | the object is considered to be | 881 | | | valid. Once this moment has | 882 | | | passed, the object is considered | 883 | | | to have expired. | 884 | validBefore | [RFC3339] date- | A date-time indicating a moment | 885 | | time | at or after which the object is | 886 | | | considered to have expired. | 887 | rating | Decimal Number | A quality rating expressed as a | 888 | | between 1.0 and | number between 1.0 and 5.0 | 889 | | 5.0 | (inclusive) with one decimal | 890 | | | place of precision. | 891 | tags | Link (Section | A Link (Section 3.4) value | 892 | | 3.4) value | referencing one or more resources | 893 | | | that are loosely associated with | 894 | | | the containing object. The | 895 | | | "tags" and "attachments" | 896 | | | properties differ from one | 897 | | | another in that the "tags" | 898 | | | property asserts "association by | 899 | | | reference" while "attachments" | 900 | | | asserts "association by | 901 | | | enclosure". | 902 | title | Natural | A Natural-language title for the | 903 | | Language | object expressed as a fragment of | 904 | | (Section 3.2) | HTML markup. The "title" and | 905 | | value | "displayName" properties are | 906 | | | closely related and overlap in | 907 | | | function with the key difference | 908 | | | being that "title" is permitted | 909 | | | to contain HTML markup, while | 910 | | | "displayName" is not. | 911 | duration | Integer or | When the object describes a time- | 912 | | [RFC3339] | based resource, such as audio or | 913 | | duration | video, the "duration" property | 914 | | | indicates the approximate | 915 | | | duration of time expressed as an | 916 | | | either an RFC 3339 "duration" | 917 | | | (e.g. a duration of 5 seconds is | 918 | | | represented as "PT5S") or as a | 919 | | | non-negative integer specifying | 920 | | | the duration in seconds. | 921 | height | Integer | When the object describes a | 922 | | | visual resource, such as an | 923 | | | image, video or embeddable HTML | 924 | | | page, the "height" property | 925 | | | indicates the recommended display | 926 | | | height in pixels. | 927 | width | Integer | When the object describes a | 928 | | | visual resource, such as an | 929 | | | image, video or embeddable HTML | 930 | | | page, the "width" property | 931 | | | indicates the recommended display | 932 | | | width in pixels. | 933 | inReplyTo | Link (Section | A Link (Section 3.4) value | 934 | | 3.4) value | identifying one or more other | 935 | | | objects to which the containing | 936 | | | object can be considered a | 937 | | | response. | 938 | actions | Action (Section | An optional Action (Section | 939 | | 3.6.1) value | 3.6.1) value that describes | 940 | | | potential activities that can be | 941 | | | performed with the object. | 942 | scope | Link (Section | A Link (Section 3.4) value | 943 | | 3.4) value | identifying one or more resources | 944 | | | that define the total population | 945 | | | of entities for which the object | 946 | | | is considered to be relevant. | 947 +-------------+-----------------+-----------------------------------+ 949 3.6.1. Action Values 951 The "actions" property on an Activity Streams object is used to 952 describe the kinds of activities that can be taken with regards to 953 the object. The value is expressed as a JSON dictionary mapping 954 verbs to Link (Section 3.4) values referencing resources or objects 955 that can be used to carry out those verbs. 957 For instance, a hypothetical object with "video" as the objectType 958 might have "watch", "share" and "embed" as potential actions: 960 { 961 "objectType": "video", 962 "id": "http://example.org/cats.mpg", 963 "actions": { 964 "watch": "movie://example.org/cats.mpg", 965 "share": { 966 "objectType": "service", 967 "displayName": "My Sharing Service", 968 "url": "http://example.net/share" 969 }, 970 "embed": [ 971 "http://example.org/gadgets/video.xml?v=cats.mpg", 972 { 973 "objectType": "inline-html", 974 "content": "