idnits 2.17.1 draft-snell-activitystreams-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 date (July 11, 2013) is 3939 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 1114, 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 July 11, 2013 5 Expires: January 12, 2014 7 JSON Activity Streams 2.0 8 draft-snell-activitystreams-00 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 January 12, 2014. 48 Copyright Notice 50 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 66 1.1. Relationship to JSON Activity Streams 1.0 . . . . . . . . 3 67 1.2. Relationship to JSON-LD 1.0 . . . . . . . . . . . . . . . 3 68 1.3. Syntax Conventions . . . . . . . . . . . . . . . . . . . 4 69 2. Example Activities . . . . . . . . . . . . . . . . . . . . . 4 70 3. Object Model . . . . . . . . . . . . . . . . . . . . . . . . 6 71 3.1. Object . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 3.2. Natural Language Values . . . . . . . . . . . . . . . . . 7 73 3.3. Link Values . . . . . . . . . . . . . . . . . . . . . . . 8 74 3.4. Activity . . . . . . . . . . . . . . . . . . . . . . . . 10 75 3.4.1. Considerations on the use of "priority" . . . . . . . 11 76 3.4.2. Audience Targeting Properties . . . . . . . . . . . . 12 77 3.5. Additional Object Properties . . . . . . . . . . . . . . 14 78 3.6. Collection . . . . . . . . . . . . . . . . . . . . . . . 17 79 3.6.1. Using Collections as Summary Values . . . . . . . . . 19 80 4. The Activity Stream JSON Document . . . . . . . . . . . . . . 20 81 5. Deprecated Activity Streams 1.0 Syntax . . . . . . . . . . . 20 82 6. Comparison of Identifier Values . . . . . . . . . . . . . . . 22 83 7. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 22 84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 85 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 86 9.1. application/activity+xml Media Type . . . . . . . . . . . 23 87 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 88 10.1. Normative References . . . . . . . . . . . . . . . . . . 24 89 10.2. Informational References . . . . . . . . . . . . . . . . 25 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 25 91 Appendix B. Processing as JSON-LD . . . . . . . . . . . . . . . 26 92 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 94 1. Introduction 95 In the most basic sense, an "activity" is a semantic description of 96 either a potential or completed action. In the former case, 97 activities express what can be done with any particular object, while 98 in the latter case, they express what has already been done. 100 It is the goal of this specification to provide a JSON-based syntax 101 that is sufficient to express metadata about activities in a rich, 102 human-friendly, machine-processable and extensible manner. This may 103 include constructing natural-language descriptions or visual 104 representations about the activity, associating actionable 105 information with various types of objects, communicating or recording 106 activity logs, or delegation of potential actions to other 107 applications. 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in [RFC2119]. 113 1.1. Relationship to JSON Activity Streams 1.0 115 The JSON Activity Streams 1.0 [activitystreams-1.0] specification was 116 published in May of 2011 and provided a baseline extensible syntax 117 for the expression of completed activities. This specification 118 builds upon that initial foundation by incorporating lessons learned 119 through extensive implementation, community feedback and related work 120 being performed in other standards development communities. 122 While the syntax defined by this specification diverges somewhat from 123 that defined by JSON Activity Streams 1.0, the verbs, objectTypes, 124 extensions and fundamental model defined by that original 125 specification remain intact. 127 1.2. Relationship to JSON-LD 1.0 129 The JSON-based Serialization for Linked Data (JSON-LD) 130 [W3C.WD-json-ld-20130411] describes a rich syntax for the 131 serialization of semantically-rich metadata using the JSON format. 132 While the updated Activity Streams representation provided by this 133 document is not defined as a "JSON-LD Vocabulary", the syntax is 134 designed to be closely compatible with JSON-LD. 136 There are a few differences between JSON-LD and the serialization 137 syntax described here, specifically: 139 o JSON-LD uses field names with a leading "@" character, such as 140 "@id", "@type" and "@language". In this specification, the 141 leading "@" is omitted. 143 o While JSON-LD allows using relative IRI references in the values 144 of ID properties, this specification limits identifiers to 145 absolute IRIs. 147 o While it is possible to derive a JSON-LD "context" description for 148 the Activity Streams 2.0 JSON syntax one is not normatively 149 provided by this specification. 151 1.3. Syntax Conventions 153 This specification defines a JSON-based [RFC4627] serialization 154 syntax. 156 When serialized, absent properties are represented either by setting 157 the property value to null or by omitting the property declaration 158 altogether at the option of the publisher; these representations are 159 semantically equivalent. If a property has an array value, the 160 absence of any items in that array MUST be represented by omitting 161 the property entirely or by setting the value to null. 163 This specification uses IRIs [RFC3987]. Every URI [RFC3986] is also 164 an IRI, so a URI may be used wherever below an IRI is named. There 165 are two special considerations: (1) when an IRI that is not also a 166 URI is given for dereferencing, it MUST be mapped to a URI using the 167 steps in Section 3.1 of [RFC3987] and (2) when an IRI is serving as 168 an "id" value, it MUST NOT be so mapped. 170 Unless otherwise specified, all properties with date and time values 171 MUST conform to the "date-time" production in [RFC3339], with an 172 uppercase "T" character used to separate date and time, and an 173 uppercase "Z" character in the absence of a numeric time zone offset. 174 All such timestamps SHOULD be represented relative to Coordinated 175 Universal Time (UTC). 177 2. Example Activities 179 Following is a simple example of an activity: 181 { 182 "type": "post", 183 "published": "2011-02-10T15:04:55Z", 184 "actor": { 185 "type": "person", 186 "id": "urn:example:person:martin", 187 "displayName": "Martin Smith", 188 "url": "http://example.org/martin", 189 "image": { 190 "id": "http://example.org/martin/image", 191 "width": 250, 192 "height": 250 193 } 194 }, 195 "object" : { 196 "type": "article", 197 "id": "urn:example:blog:abc123/xyz" 198 "url": "http://example.org/blog/2011/02/entry" 199 }, 200 "target" : { 201 "type": "blog", 202 "id": "urn:example:blog:abc123", 203 "displayName": "Martin's Blog", 204 "url": "http://example.org/blog/" 205 } 206 } 208 A more extensive, single-entry "Activity Stream" follows. In 209 addition to containing a number of required and optional core 210 properties, the example contains the additional, undefined extension 211 properties "foo" and "foo2" for illustrative purposes only. 213 { 214 "items" : [ 215 { 216 "type": "post", 217 "language": "en", 218 "published": "2011-02-10T15:04:55Z", 219 "foo": "some extension property", 220 "generator": "http://example.org/activities-app", 221 "provider": "http://example.org/activity-stream", 222 "title": { 223 "en": "Martin posted a new video to his album.", 224 "ga": "Martin phost le fisean nua a albam." 225 }, 226 "actor": { 227 "type": "person", 228 "id": "urn:example:person:martin", 229 "displayName": "Martin Smith", 230 "url": "http://example.org/martin", 231 "foo2": "some other extension property", 232 "image": { 233 "id": "http://example.org/martin/image", 234 "width": 250, 235 "height": 250 236 } 237 }, 238 "object" : { 239 "type": "photo", 240 "id": "urn:example:album:abc123/my_fluffy_cat", 241 "url": "http://example.org/album/my_fluffy_cat.jpg", 242 "image": { 243 "id": "http://example.org/album/my_fluffy_cat_thumb.jpg", 244 "width": 250, 245 "height": 250 246 } 247 }, 248 "target": { 249 "url": "http://example.org/album/", 250 "type": "photo-album", 251 "id": "urn:example.org:album:abc123", 252 "title": { 253 "en": "Martin's Photo Album", 254 "ga": "Grianghraif Mairtin" 255 }, 256 "image": { 257 "id": "http://example.org/album/thumbnail.jpg", 258 "width": 250, 259 "height": 250 260 } 261 } 262 } 263 ] 264 } 266 3. Object Model 268 3.1. Object 270 The following "core properties" apply to all JSON objects serialized 271 within an Activity Stream document. 273 +----------+-------------+------------------------------------------+ 274 | Property | Value | Description | 275 +----------+-------------+------------------------------------------+ 276 | id | IRI | Provides a permanent, universally unique | 277 | | | identifier for the object in the form of | 278 | | | an absolute IRI [RFC3987]. Objects | 279 | | | SHOULD contain a single "id" property. | 280 | | | If an object does not contain an "id" | 281 | | | property, consumers MAY use the value of | 282 | | | the "url" property as a less-reliable, | 283 | | | non-unique identifier. | 284 | type | IRI | Identifies the type of object. An object | 285 | | | MAY contain a "type" property whose | 286 | | | value matches either the "isegment-nz- | 287 | | | nc" or the "IRI" production in | 288 | | | [RFC3987]. The use of a relative | 289 | | | reference other than a simple name is | 290 | | | not allowed. If no "type" property is | 291 | | | specified, the object has no specific | 292 | | | type. | 293 | language | [RFC5646] | Identifies the language for all human- | 294 | | Language | readable, natural-language metadata | 295 | | Tag | values included in the object. An object | 296 | | | MAY contain a "language" property whose | 297 | | | value MUST be a [RFC5646] Language-Tag. | 298 | name | String | A simple human-readable, plain-text name | 299 | | | for the object. HTML markup MUST NOT be | 300 | | | included. An object MAY contain a | 301 | | | "displayName" property. If the object | 302 | | | does not specify a "type" property, the | 303 | | | object SHOULD specify a "displayName". | 304 | url | Link | A Link (Section 3.3) value describing a | 305 | | | resource that provides a visual | 306 | | | representation of the object. An object | 307 | | | MAY contain a "url" property. | 308 +----------+-------------+------------------------------------------+ 310 3.2. Natural Language Values 312 Natural Language values represent human-readable character sequences 313 in one or more languages. They are expressed as either: (1) a single 314 JSON string or (2) a JSON dictionary mapping [RFC5646] Language-Tags 315 to localized, equivalent translations of the same string value. 317 For instance, the "title" property in all objects is a Natural 318 Language value. 320 A single String value using the default language: 322 { 323 "language": "en", 324 "title": "This is the title" 325 } 327 Multiple, language-specific values: 329 { 330 "title": { 331 "en": "This is the name", 332 "fr": "C'est le titre", 333 "sp": "Este es el titulo" 334 } 335 } 337 Each key in the JSON dictionary MUST be an [RFC5646] Language Tag. 338 The associated values MUST be Strings. 340 3.3. Link Values 342 Link values represent references to other objects and resources. 343 They are expressed as either: (1) a String containing an absolute or 344 relative IRI, (2) an Object (Section 3.1), or (3) a JSON Array 345 containing a mixture of IRIs or Objects (Section 3.1). Link values 346 are closely related to the conceptual model of Links as established 347 in [RFC5988], but have a serialization that is compatible with the 348 JSON-serialization for Linked Data. 350 For instance, as defined in previously, all objects (Section 3.1) can 351 contain an "image" property whose value describes a graphical 352 representation of the containing object. This property will 353 typically be used to provide the URL to a JPEG, GIF or PNG type 354 resource that can be displayed to the user. Any given object might 355 have multiple such visual representations -- multiple screenshots, 356 for instance, or the same image at different resolutions. Based on 357 the JSON-LD approach, there are essentially three ways of describing 358 these references. 360 To reference a single image without any additional metadata, the link 361 value can be expressed as a simple JSON string containing an absolute 362 or relative IRI: 364 { 365 "type": "application", 366 "id": "http://example.org/application/123", 367 "displayName": "My Application", 368 "image": "http://example.org/application/123.png" 369 } 371 Alternatively, if additional metadata is required, the link can be 372 expressed as an object that uses the id or url property: 374 { 375 "type": "application", 376 "id": "http://example.org/application/123", 377 "displayName": "My Application", 378 "image": { 379 "id": "http://example.org/application/123.png", 380 "mediaType": "image/png", 381 "height": 320, 382 "width": 320 383 } 384 } 386 If more than one link value is to be expressed, A JSON Array with a 387 mix of string and object elements can be used: 389 { 390 "type": "application", 391 "id": "http://example.org/application/123", 392 "displayName": "My Application", 393 "image": [ 394 "http://example.org/application/abc.gif", 395 { 396 "id": "http://example.org/application/123.png", 397 "mediaType": "image/png", 398 "height": 320, 399 "width": 320 400 } 401 ] 402 } 404 Individual items contained in such an array value are independent of 405 the others and no significance is given to the order of items in the 406 array. 408 RFC 5988 defines that all Links have a "link relation" that describes 409 the contextual purpose of the link. Within an Activity Streams 410 document, in the absence of a specific "rel" property within the link 411 itself, the name of the property whose value is a link serves as the 412 "link relation". Any legal link relation value, as defined by RFC 413 5988, can be used as a property with a link value in any Activity 414 Streams object, except where the link relation might conflict with 415 any other property defined by this specification. 417 When an object (Section 3.1) is used to represent a Link value, the 418 following additional properties MAY be used: 420 +---------------+--------------+------------------------------------+ 421 | Property | Value | Description | 422 +---------------+--------------+------------------------------------+ 423 | "rel" | RFC 5988 | The RFC 5988 Link Relation | 424 | | Link | associated with this link value. | 425 | | Relation | If absent, the name of the | 426 | | | property is assumed to specify the | 427 | | | link relation. | 428 | "mediaType" | MIME Media | The MIME media type of the | 429 | | Type | resource being referenced. | 430 +---------------+--------------+------------------------------------+ 432 3.4. Activity 434 Activity objects are specializations of the base Object (Section 3.1) 435 type that provide metadata about potential or completed actions. 437 Within an Activity object, the "type" property is used to identify 438 the type of activity. Formerly, in JSON Activity Streams version 439 1.0, this was represented using the "verb" property. All existing 440 verb definitions used in JSON Activity Streams 1.0 implementations 441 can continue to be used as values of the "type" property and retain 442 their existing semantics. 444 Activity objects extend the core object (Section 3.1) definition with 445 the following additional, optional properties: 447 +-------------+------------+----------------------------------------+ 448 | Property | Value | Description | 449 +-------------+------------+----------------------------------------+ 450 | "actor" | Link | Describes the entity that either | 451 | | (Section | peformed or is expected to perform the | 452 | | 3.3) value | Activity. | 453 | "object" | Link | Describes the primary object of the | 454 | | (Section | activity. For instance, in the | 455 | | 3.3) value | activity, "John saved a movie to his | 456 | | | wishlist", the object of the activity | 457 | | | is "movie". An activity SHOULD contain | 458 | | | an "object" property. If the "object" | 459 | | | property is not contained, the primary | 460 | | | object of the activity MAY be implied | 461 | | | by context. | 462 | "target" | Link | Describes the target of the activity. | 463 | | (Section | The precise meaning of the activity's | 464 | | 3.3) value | target is dependent on the activities | 465 | | | "verb", but will often be the object | 466 | | | the English preposition "to". For | 467 | | | instance, in the activity, "John saved | 468 | | | a movie to his wishlist", the target | 469 | | | of the activity is "wishlist". The | 470 | | | activity target MUST NOT be used to | 471 | | | identity an indirect object that is | 472 | | | not a target of the activity. | 473 | "result" | Link | Describes the result of the activity. | 474 | | (Section | For instance, if a particular action | 475 | | 3.3) value | results in the creation of a new | 476 | | | resource, the "result" property can be | 477 | | | used to describe that new resource. | 478 | "context" | Link | The "context" property allows the | 479 | | (Section | Activity to further include | 480 | | 3.3) value | information about why a particular | 481 | | | action occurred by providing details | 482 | | | about the context within which a | 483 | | | particular action was performed. The | 484 | | | value of the context property is Link | 485 | | | (Section 3.3) value. | 486 | "status" | String | A string value indicating the current | 487 | | | status of the activity. The value | 488 | | | MUST be one of: "tentative", | 489 | | | "pending", "completed", or "canceled". | 490 | "priority" | Decimal | An indicator of the relative priority | 491 | | Number | or importance that the creator of an | 492 | | between | Activity object considers the object | 493 | | 0.00 and | to have. Represented as a numeric | 494 | | 1.00 | decimal between 0.00 and 1.00, with | 495 | | | two decimal places of precision. If | 496 | | | the property is omitted, or expicitly | 497 | | | set to null, the assumption is that no | 498 | | | explicit priority or importance can be | 499 | | | assumed. All other values falling | 500 | | | between 0.00 and 1.00 indicate | 501 | | | increasing priority. | 502 +-------------+------------+----------------------------------------+ 504 3.4.1. Considerations on the use of "priority" 506 The presence of the "priority" property does not impose any specific 507 processing or display requirements on the part of any entity 508 consuming the activity. 510 Expressing the value as a range of numeric decimal values is intended 511 to provide the greatest level of flexibility in the expression and 512 consumption of prioritization detail. It is expected that 513 implementors consuming activity objects containing "priority" will 514 utilize and expose the additional information in a number of 515 different ways depending on the unique requirements of each 516 application use case. 518 Many existing systems do not represent priority values as numeric 519 ranges. Such systems might use fixed, labeled brackets such as 520 "low", "normal" and "high" or "urgent". Similar mechanisms can be 521 established, by convention, when using the "priority" property. In 522 typical use, it is RECOMMENDED that implementations wishing to work 523 with such defined categories treat "priority" property values in the 524 range 0.00 to 0.25 as "low" priority; values greater than 0.25 to 525 0.75 as "normal" priority; and values greater than 0.75 to 1.00 as 526 "high" priority. Specific implementations are free to establish 527 alternative conventions for the grouping of priority values with the 528 caveat that such conventions likely will not be understood by all 529 implementations. 531 3.4.2. Audience Targeting Properties 533 Every Activity has both a Primary and Secondary audience. The 534 Primary audience consists of those entities either directly involved 535 in the performance of the activity or who "own" the objects involved. 536 The Secondary audience consists of the collection of entities sharing 537 an interest in the activity but who are not directly involved (e.g. 538 "followers"). 540 For instance, suppose a social network of three individuals: Bob, Joe 541 and Jane. Bob and Joe are each friends with Jane but not friends 542 with one another. Bob has chosen to "follow" activities for which 543 Jane is directly involved. Jane shares a file with Joe. 545 In this example, Jane and Joe are each directly involved in the file 546 sharing activity and together make up the Primary Audience for that 547 event. Bob, having an interest in activities involving Jane, is the 548 Secondary Audience. Knowing this, a system that produces or consumes 549 the activity can intelligently notify each person of the event. 551 While there are means, based on the verb, actor, object and target of 552 the activity, to infer the primary audience for many types of 553 activities, those do not work in every case and do not provide a 554 means of identifying the secondary audience. The "to", "cc", "bto" 555 and "bcc" properties MAY be used within an Activity to explicitly 556 identify the Primary and Secondary audiences. 558 +--------------+--------------------+-------------------------------+ 559 | Property | Value | Description | 560 +--------------+--------------------+-------------------------------+ 561 | "to" | Link (Section 3.3) | Specifies the public primary | 562 | | value | audience. | 563 | "cc" | Link (Section 3.3) | Specifies the public | 564 | | value | secondary audience. | 565 | "bto" | Link (Section 3.3) | Specifies the private primary | 566 | | value | audience. | 567 | "bcc" | Link (Section 3.3) | Specifies the private | 568 | | value | secondary audience. | 569 +--------------+--------------------+-------------------------------+ 571 The prototypical use case for an Activity containing these properties 572 is the publication and redistribution of Activities through an 573 intermediary. That is, an event source generates the activity and 574 publishes it to the intermediary which determines a subset of events 575 to display to specific individual users or groups. Such a 576 determination can be made, in part, by identifying the Primary and 577 Secondary Audiences for each activity. 579 When the event source generates the activity and specifies values for 580 the to and cc fields, the intermediary SHOULD redistribute that event 581 with the values of those fields intact, allowing any processor to see 582 who the activity has been targeted to. This is precisely the same 583 model used by the to and cc fields in email systems. 585 There are situations, however, in which disclosing the identity of 586 specific members of the audience may be inappropriate. For instance, 587 a user may not wish to let other users know that they are interested 588 in various topics, individuals or types of events. To support this 589 option, an event source generating an activity MAY use the "bto" and 590 "bcc" properties to list entities to whom the activity should be 591 privately targeted. When an intermediary receives an activity 592 containing these properties, it MUST remove those values prior to 593 redistributing the activity. The intent is that systems MUST 594 consider entities listed within the "bto" and "bcc" properties as 595 part of the Primary and Second audience but MUST NOT disclose that 596 fact to any other party. 598 Audience targeting information included within an Activity only 599 describes the intent of the activity creator. With clear exception 600 given to the appropriate handling of "bto" and "bcc", this 601 specification leaves it up to implementations to determine how the 602 audience targeting information is used. 604 3.5. Additional Object Properties 606 The following "additional properties" MAY be used with any JSON 607 Object serialized within an Activity Stream document. 609 +---------------+--------------+------------------------------------+ 610 | Property | Value | Description | 611 +---------------+--------------+------------------------------------+ 612 | "alias" | IRI | Provides a contextually meaningful | 613 | | | alternative label for the object | 614 | | | in addition to the "id". For | 615 | | | instance, within some systems, | 616 | | | groups can be identified both by a | 617 | | | unique global ID and a more | 618 | | | "human-friendly" label such as | 619 | | | "@friends" or "@network". The | 620 | | | value of the "alias" property MUST | 621 | | | match either the "isegment-nz-nc" | 622 | | | or the "IRI" production in | 623 | | | [RFC3987]. The use of a relative | 624 | | | reference other than a simple name | 625 | | | is not allowed. | 626 | "attachments" | Link | A Link (Section 3.3) value | 627 | | (Section | referencing one or more objects | 628 | | 3.3) value | associated with the containing | 629 | | | object. These are similiar in | 630 | | | concept to files attached to an | 631 | | | email message. | 632 | "author" | Link | A Link (Section 3.3) value | 633 | | (Section | referencing one or more entity | 634 | | 3.3) value | that created or authored the | 635 | | | object. | 636 | "content" | Natural | A Natural-language description of | 637 | | Language | the object encoded as a single | 638 | | value | JSON String containing HTML | 639 | | (Section | markup. Visual elements such as | 640 | | 3.2) | thumbnail images MAY be included. | 641 | "duplicates" | Link | A Link (Section 3.3)value | 642 | | (Section | referencing one or more objects | 643 | | 3.3) value | that are semantically equivalent | 644 | | | to this object or duplicate this | 645 | | | objects content. An object SHOULD | 646 | | | contain a "duplicates" property | 647 | | | when there are known objects, | 648 | | | possibly in a different system, | 649 | | | that are semantically equivalent | 650 | | | or duplicate the content. | 651 | "icon" | Link | A Link (Section 3.3) value | 652 | | (Section | referencing one or more visual, | 653 | | 3.3) value | graphic representations of the | 654 | | | object, intended for human | 655 | | | consumption. The visual element | 656 | | | SHOULD have an aspect ratio of one | 657 | | | (horizontal) to one (vertical) and | 658 | | | SHOULD be suitable for | 659 | | | presentation at a small size. | 660 | "image" | Link | A Link (Section 3.3) value | 661 | | (Section | referencing one or more visual, | 662 | | 3.3) value | graphic represenations of the | 663 | | | object. Unlike the "icon" | 664 | | | property, there are no aspect | 665 | | | ratio or display restrictions. | 666 | "location" | Link | A Link (Section 3.3) value | 667 | | (Section | describing one or more physical or | 668 | | 3.3) value | virtual locations associated with | 669 | | | which the object. | 670 | "published" | [RFC3339] | The date and time at which the | 671 | | date-time | object was published. | 672 | "generator" | Link | A Link (Section 3.3) value | 673 | | (Section | referencing the application that | 674 | | 3.3) value | generated the object. | 675 | "provider" | Link | A Link (Section 3.3) value | 676 | | (Section | referencing the application that | 677 | | 3.3) value | published the object. Note that | 678 | | | this is not necessarily the same | 679 | | | entity that generated the object. | 680 | "source" | Link | A Link (Section 3.3) value | 681 | | (Section | referencing the original source of | 682 | | 3.3) value | this object. The source property | 683 | | | is closely related to the | 684 | | | generator and provider properties | 685 | | | but serves the distinct purpose of | 686 | | | identifying where the object was | 687 | | | originally published as opposed to | 688 | | | identifying the applications that | 689 | | | generated or published it. | 690 | "summary" | Natural | A Natural-language summarization | 691 | | Language | of the object encoded as a single | 692 | | value | JSON String containing HTML | 693 | | (Section | markup. Visual elements such as | 694 | | 3.2) | thumbnail images can be included. | 695 | "updated" | [RFC3339] | The date and time at which a | 696 | | date-time | previously published object has | 697 | | | been modified. | 698 | "startTime" | [RFC3339] | A date-time describing the actual | 699 | | date-time | or expected starting time of the | 700 | | | object. When used within an | 701 | | | Activity object, for instance, the | 702 | | | "startTime" specifies the moment | 703 | | | the activity began or is scheduled | 704 | | | to begin. | 705 | "endTime" | [RFC3339] | A date-time describing the actual | 706 | | date-time | or expected ending time of the | 707 | | | object. When used within an | 708 | | | Activity object, for instance, the | 709 | | | "endTime" specifies the moment the | 710 | | | activity concluded or is scheduled | 711 | | | to conclude. | 712 | "rating" | Decimal | A quality rating expressed as a | 713 | | Number | number between 1.0 and 5.0 | 714 | | between 1.0 | (inclusive) with one decimal place | 715 | | and 5.0 | of precision. | 716 | "tags" | Link | A Link (Section 3.3) value | 717 | | (Section | referencing one or more resources | 718 | | 3.3) value | that are loosely associated with | 719 | | | the containing object. The "tags" | 720 | | | and "attachments" properties | 721 | | | differ from one another in that | 722 | | | the "tags" property asserts | 723 | | | "association by reference" while | 724 | | | "attachments" asserts "association | 725 | | | by enclosure". | 726 | "title" | Natural | A Natural-language title of the | 727 | | Language | object encoded as a single JSON | 728 | | (Section | String containing HTML markup. | 729 | | 3.2) value | | 730 | "duration" | Integer | When the object describes a time- | 731 | | | based resource, such as audio or | 732 | | | video, the "duration" property | 733 | | | indicates the approximate length | 734 | | | of time in seconds. | 735 | "height" | Integer | When the object describes a visual | 736 | | | resource, such as an image, video | 737 | | | or embeddable HTML page, the | 738 | | | "height" property indicates the | 739 | | | recommended display height in | 740 | | | pixels. | 741 | "width" | Integer | When the object describes a visual | 742 | | | resource, such as an image, video | 743 | | | or embeddable HTML page, the | 744 | | | "width" property indicates the | 745 | | | recommended display width in | 746 | | | pixels. | 747 | "inReplyTo" | Link | A Link (Section 3.3) value | 748 | | (Section | identifying one or more other | 749 | | 3.3) value | objects to which the containing | 750 | | | object can be considered a | 751 | | | response. | 752 +---------------+--------------+------------------------------------+ 754 3.6. Collection 756 Collection objects are a specialization of the base Object 757 (Section 3.1) that contain a listing of other objects (Section 3.1) 758 The Collection object is used primarily as the root of an Activity 759 Streams document as described in Section 4, but can be used as the 760 value of object properties. 762 Collections have both a logical model and a physical serialization. 763 While the logical view of a collection might contain a large number 764 of objects, any single serialized representation might include only a 765 subset of those objects, with specific Link (Section 3.3) values used 766 to reference additional serialized representations that include 767 additional subsets. Such representations are known as "multi-page 768 collections", with each serialized subset representing a single 769 "page". 771 The value of the Collection object's "type" property MUST be 772 "collection" unless the fact that the object is a collection can be 773 determined by context. 775 Collection objects extend the core object (Section 3.1) definition 776 with the following additional properties: 778 +----------------+--------------+-----------------------------------+ 779 | Property | Value | Description | 780 +----------------+--------------+-----------------------------------+ 781 | "totalItems" | Integer | Non-negative integer specifying | 782 | | | the total number of objects | 783 | | | contained by the logical view of | 784 | | | the collection. This number might | 785 | | | not reflect the actual number of | 786 | | | items serialized within the | 787 | | | Collection object instance. | 788 | "items" | Array of | An array containing a listing of | 789 | | Objects | Objects (Section 3.1) of any | 790 | | (Section | type. | 791 | | 3.1) | | 792 | "itemsAfter" | [RFC3339] | A RFC 3339 date-time that | 793 | | date-time | indicates that the collection | 794 | | | contains only items published or | 795 | | | updated strictly after the date | 796 | | | and time specified. | 797 | "itemsBefore" | [RFC3339] | A RFC 3339 date-time that | 798 | | date-time | indicates that the collection | 799 | | | contains only items published or | 800 | | | updated strictly before the date | 801 | | | and time specified. | 802 | "itemsPerPage" | Integer | A non-negative integer specifying | 803 | | | the maximum number of items that | 804 | | | will be included in the value of | 805 | | | the items array. | 806 | "startIndex" | Integer | A non-negative integer value | 807 | | | identifying the relative position | 808 | | | within the logical view of | 809 | | | collection of the first object | 810 | | | contained in the items property. | 811 | | | For instance, if there are 20 | 812 | | | items that are considered to be | 813 | | | members of a collection, but only | 814 | | | the last 10 of those items are | 815 | | | included in the items property, | 816 | | | the value of startIndex would be | 817 | | | 10. | 818 | "first" | Link | A Link (Section 3.3) value | 819 | | (Section | referencing the furthest | 820 | | 3.3) value | preceeding page of a multi-page | 821 | | | collection. | 822 | "last" | Link | A Link (Section 3.3) value | 823 | | (Section | referencing the furthest | 824 | | 3.3) value | following page of a multi-page | 825 | | | collection. | 826 | "prev" | Link | A Link (Section 3.3) value | 827 | | (Section | referencing the immediately | 828 | | 3.3) value | preceding page of the multi-page | 829 | | | collection. Note that the | 830 | | | property name previous can be | 831 | | | used as an equivalent | 832 | | | alternative; however | 833 | | | implementations SHOULD use prev | 834 | | | and MUST NOT use both prev AND | 835 | | | previous within the same | 836 | | | collection. | 837 | "next" | Link | A Link (Section 3.3) value | 838 | | (Section | referencing the immediately | 839 | | 3.3) value | following page of the multi-page | 840 | | | collection. | 841 | "current" | Link | A Link (Section 3.3) value | 842 | | (Section | referencing the page containing | 843 | | 3.3) value | the items that have been updated | 844 | | | or published most recently. | 845 | "self" | Link | A Link (Section 3.3) value | 846 | | (Section | referencing this page. | 847 | | 3.3) value | | 848 +----------------+--------------+-----------------------------------+ 850 3.6.1. Using Collections as Summary Values 852 It is a common practice to use Collection objects to provide summary 853 information on the number of specific types of events that have 854 occurred with respect to any given object. For instance, a "note" 855 object may have been "shared" or "liked" a number of times by 856 different individuals. In such cases, the Collection object is used 857 as a property value with the "totalItems" field used to indicate the 858 total number of occurrences, the "items" property used to provide 859 details for a subset of the most recent occurrences, and the "id" 860 property used to reference a separate Activity Streams document 861 providing additional information. 863 This specification defines the following properties that MAY be used 864 within any object (Section 3.1) as "summary values": 866 +--------------+----------------+-----------------------------------+ 867 | Property | Value | Description | 868 +--------------+----------------+-----------------------------------+ 869 | "replies" | Collection | Provides information about the | 870 | | (Section 3.6) | set of objects that can be | 871 | | | considered to be replies to the | 872 | | | containing object. | 873 +--------------+----------------+-----------------------------------+ 875 In the following example, the "replies" property is used to indicate 876 that a note has 10 responses, and provides information on the most 877 recently received response: 879 { 880 "type": "note", 881 "id": "urn:example:note:1", 882 "displayName": "Note", 883 "title": "A Note about things", 884 "content": "blah blah blah", 885 "replies": { 886 "id": "http://example.org/note/1/comments.json", 887 "mediaType": "application/activity+json", 888 "totalItems": 10, 889 "items": [ 890 { 891 "type": "note", 892 "id": "urn:example:note:1:A", 893 "content": "That's profound, man." 894 } 895 ] 896 } 897 } 899 4. The Activity Stream JSON Document 901 The above defined JSON serialization can be used to represent 902 activities, objects and media links in any context. This section 903 defines one particular use of the above formats to publish a JSON 904 document representing a stream of activities. 906 Publishers using this format MUST produce a valid JSON document whose 907 root value is a Collection (Section 3.6). 909 The MIME media type of this document MUST be "application/ 910 activity+json". 912 5. Deprecated Activity Streams 1.0 Syntax 914 The JSON syntax defined by this specification differs somewhat from 915 that defined in the original JSON Activity Streams 1.0 916 [activitystreams-1.0] specification in ways that are not backwards 917 compatible. Implementations can choose to continue supporting the 918 JSON Activity Streams 1.0 syntax but SHOULD consider it to be 919 deprecated. This means that while implementations MAY continue to 920 consume the 1.0 syntax, they SHOULD NOT output the 1.0 syntax unless 921 specifically interacting with older non-2.0 compliant 922 implementations. 924 Specifically: 926 1. Implementations MUST use the "application/stream+json" MIME media 927 type when producing a JSON serialization of an Activity Object 928 conforming to the 1.0 syntax, and "application/activity+json" 929 when producing a serialization conforming to the 2.0 syntax. 931 2. Implementations that process serializations of an Activity Object 932 identified using either the "application/stream+json" or more 933 generic "application/json" MIME media type MUST follow the syntax 934 and processing rules set by [activitystreams-1.0]. The 2.0 935 syntax and processing rules apply only when handling 936 serializations using the "application/activity+json" media type. 938 3. This document combines the 1.0 "verb" and "objectType" concepts 939 into a single type system. For backwards compatibility, 940 implementations MUST treat the "verb" and "objectType" properties 941 as aliases of the new "type" property. In situations where an 942 object contains both "verb" and "objectType" properties, the 943 "verb" will take precedence when mapping to the new "type" 944 property. 946 4. This document redefines the "title", "content" and "summary" 947 properties as Natural Language Values (Section 3.2), which means 948 their values can be expressed as either a String or a JSON-LD 949 Language Map. In the 1.0 syntax, these are expressed solely as 950 String values. Because the 1.0 values are a valid subset allowed 951 by this specification, implementations are not required to take 952 any specific action to continue supporting those values. 954 5. This document redefines a large number of common properties 955 defined originally as Objects in 1.0 as Link values 956 (Section 3.3). This means the property values can be expressed 957 as either an IRI String, an Object, or an Array of IRI Strings 958 and Objects. Because the 1.0 values are a valid subset allowed 959 by this specification, implementations are not required to take 960 any specific action to continue supporting those values. 962 6. This specification replaces the "upstreamDuplicates" and 963 "downstreamDuplicates" properties defined in the 1.0 syntax with 964 a singular "duplicates" property with a Link value (Section 3.3). 965 The "upstreamDuplicates" and "downstreamDuplicates" property 966 values in 1.0 are defined as Arrays of strings. Implementations 967 MUST consider the union of these two values as an alias for the 968 "duplicates" property. 970 By following these requirements, all JSON Activity Streams 1.0 971 serializations can be processed successfully by 2.0 implementations. 973 6. Comparison of Identifier Values 975 The values of multiple Object (Section 3.1) and Link (Section 3.3) 976 value's "id" properties can be compared to determine if the objects 977 represent duplicate content. Processors MUST compare these values on 978 a character-by-character, case-sensitive basis. Comparison 979 operations MUST be based solely on the IRI character strings and MUST 980 NOT rely on dereferencing the IRIs or URIs mapped from them. 982 As a consequence, two IRIs that resolve to the same resource but are 983 not character-for-character identical will be considered different 984 for the purposes of identifier comparison. In such cases, the 985 "duplicates" property can be used to expressly relate such objects to 986 one another. 988 7. Extensibility 990 Processors that encounter unfamiliar properties within any Activity 991 Streams object MUST NOT stop processing or signal an error and MUST 992 continue processing the items as if those properties were not 993 present. 995 8. Security Considerations 997 Publishers or Consumers implementing Activity Streams as a stream of 998 public data may also want to consider the potential for unsolicited 999 commercial or malicious content and should take preventative measures 1000 to recognize such content and either identify it or not include it in 1001 their implementations. 1003 Publishers should take reasonable measures to ensure potentially 1004 malicious user input such as cross-site scripting attacks are not 1005 included in the Activity Streams data they publish. 1007 Consumers that re-emit ingested content to end-users MUST take 1008 reasonable measures if emitting ingested content to make sure 1009 potentially malicious ingested input is not re-emitted. 1011 Consumers that re-emit ingested content for crawling by search 1012 engines should take reasonable measures to limit any use of their 1013 site as a Search Engine Optimization loophole. This may include 1014 converting un-trusted hyperlinks to text or including a 1015 rel="nofollow" attribute. 1017 Consumers should be aware of the potential for spoofing attacks where 1018 the attacker publishes activities or objects with falsified property 1019 values with the intent of injecting malicious content, hiding or 1020 corrupting legitimate content, or misleading users. 1022 Activity Streams are JSON Documents and are subject to the same 1023 security considerations described in [RFC4627]. 1025 Activity Streams implementations handle URIs. See Section 7 of 1026 [RFC3986]. 1028 Activity Streams implementations handle IRIs. See Section 8 of 1029 [RFC3987]. 1031 9. IANA Considerations 1033 9.1. application/activity+xml Media Type 1035 This specification registers the application/activity+json MIME Media 1036 Type: 1038 Type name: application 1040 Subtype name: activity+json 1042 Required parameters: None 1044 Optional parameters: "charset" : Specifies the character set 1045 encoding. If not specified, a default of "UTF-8" is assumed. 1047 Encoding considerations: Resources that use the "application/ 1048 activity+json" media type are required to conform to the 1049 "application/json" Media Type and are therefore subject to the 1050 same encoding considerations specified in Section 6 [RFC4627]. 1052 Security considerations: As defined in this specification 1054 Published specification: This specification. 1056 Applications that use this media type: JSON Activity Streams are 1057 implemented by a wide range of existing applications. 1059 Additional information: 1061 Magic number(s): N/A 1063 File extension(s): N/A 1065 Macintosh file type code(s): TEXT 1067 Person & email address to contact for further information: James M 1068 Snell 1069 Intended usage: COMMON 1071 Restrictions on usage: None. 1073 Author: James M Snell 1075 Change controller: IESG 1077 10. References 1079 10.1. Normative References 1081 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1082 Requirement Levels", BCP 14, RFC 2119, March 1997. 1084 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1085 Internet: Timestamps", RFC 3339, July 2002. 1087 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1088 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1089 3986, January 2005. 1091 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1092 Identifiers (IRIs)", RFC 3987, January 2005. 1094 [RFC4627] Crockford, D., "The application/json Media Type for 1095 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1097 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1098 Languages", BCP 47, RFC 5646, September 2009. 1100 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1102 [W3C.WD-json-ld-20130411] 1103 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0", 1104 World Wide Web Consortium LastCall WD-json-ld-20130411, 1105 April 2013, 1106 . 1108 [activitystreams-1.0] 1109 Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, 1110 M., and R. Dolin, "JSON Activity Streams 1.0", May 2011. 1112 10.2. Informational References 1114 [RFC6963] Saint-Andre, P., "A Uniform Resource Name (URN) Namespace 1115 for Examples", BCP 183, RFC 6963, May 2013. 1117 Appendix A. Acknowledgements 1119 The author wishes to thank the Activity Streams community and 1120 implementers for their support, encouragement, and enthusiasm 1121 including but not limited to: Abdul Qabiz, Adina Levin, Adrian Chan, 1122 Adriana Javier, Alan Hoffman, Alex Kessinger, Alexander Ovchinnikov, 1123 Alexander Zhuravlev, Alexandre Loureiro Solleiro, Amy Walgenbach, 1124 Andres Vidal, Angel Robert Marquez, Ari Steinberg, Arjan 1125 Scherpenisse, Arne Roomann-Kurrik, Beau Lebens, Ben Hedrington, Ben 1126 Metcalfe, Ben Werdmuller, Benjamin Goering, Bill de hOra, Bo Xing, 1127 Bob Aman, Bob Wyman, Brett Slatkin, Brian Walsh, Brynn Evans, Charlie 1128 Cauthen, Chris Chabot, Chris Messina, Chris Toomey, Christian 1129 Crumlish, Dan Brickley, Dan Scott, Daniel Chapman, Danny Ayers, Dare 1130 Obasanjo, Darren Bounds, David Cramer, David Nelson, David Recordon, 1131 DeWitt Clinton, Douglas Pearce, Ed Summers, Elias Bizannes, Elisabeth 1132 Norris, Eric Marcoullier, Eric Woods, Evan Prodromou, Gee-Hsien 1133 Chuang, Greg Biggers, Gregory Foster, Henry Saputra, Hillary Madsen, 1134 Howard Liptzin, Hung Tran, Ian Kennedy, Ian Mulvany, Ivan Pulleyn, 1135 Jacob Kim, James Falkner, James Pike, James Walker, Jason Kahn, Jason 1136 Kantz, Jeff Kunins, Jeff Martin, Jian Lin, Johannes Ernst, John 1137 Panzer, Jon Lebkowsky, Jon Paul Davies, Jonathan Coffman, Jonathan 1138 Dugan, Joseph Boyle, Joseph Holsten, Joseph Smarr, Josh Brewer, Jud 1139 Valeski, Julien Chaumond, Julien Genestoux, Jyri Engestroem, Kaliya 1140 Hamlin, Kevin Marks, Laurent Eschenauer, Laurie Voss, Leah Culver, 1141 Libby Miller, Manu Mukerji, Mark Weitzel, Marko Degenkolb, Marshall 1142 Kirkpatrick, Martin Atkins, Martin Svensson, Marty Alchin, Mary 1143 Hoder, Matt Leventi, Matt Wilkinson, Matthias Mueller-Prove, Max 1144 Engel, Max Wegmueller, Melvin Carvalho, Michael Buckbee, Michael 1145 Chan, Michael Richardson, Michael Sullivan, Mike Macgirvin, Mislav 1146 Marohnić, Mo Jangda, Monica Wilkinson, Nate Benes, NeilFred 1147 Picciotto, Nick Howard, Nick Lothian, Nissan Dookeran, Nitya 1148 Narasimhan, Pablo Martin, Padraic Brady, Pat G. Cappalaere, Patrick 1149 Aljord, Peter Ferne, Peter Reiser, Peter Saint-Andre, Phil Wolff, 1150 Philip (flip) Kromer, Richard Cunningham, Richard Zhao, Rick 1151 Severson, Robert Hall, Robert Langbert, Robert Dolin, Robin Cover, 1152 Ryan Boyd, Sam Sethi, Scott Raymond, Scott Seely, Simon Grant, Simon 1153 Wistow, Stephen Garcia, Stephen Sisk, Stephen Paul Weber, Steve Ivy, 1154 Steve Midgley, Steven Livingstone-Perez, Sylvain Carle, Sylvain 1155 Hellegouarch, Tantek Celik, Tatu Saloranta, Tim Moore, Timothy Young, 1156 Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley, 1157 and Zach Shepherd. 1159 Appendix B. Processing as JSON-LD 1161 While the Activity Streams 2.0 syntax is designed to be compatible 1162 with JSON-LD, in order to successfully process an Activity Streams 1163 document as JSON-LD, a "@context" description needs to be provided. 1164 The following example illustrates an Activity Streams document that 1165 can be processed as JSON-LD containing Schema.org defined metadata 1166 elements. 1168 { 1169 "@context": { 1170 "@vocab": "http://activitystrea.ms/spec/2.0/", 1171 "actor": "http://schema.org/Action/performedBy", 1172 "object": "http://schema.org/BuyAction/bought", 1173 "purchase": "http://schema.org/BuyAction", 1174 "person": "http://schema.org/Person", 1175 "book": "http://schema.org/Book" 1176 }, 1177 "type" : "purchase", 1178 "id" : "urn:example:purchase:123/abc", 1179 "title": "John purchased 'A Tale of Two Cities'", 1180 "startTime" : "2013-04-02T12:31Z", 1181 "endTime" : "2013-04-02T12:31Z", 1182 "actor": { 1183 "type": "person", 1184 "displayName": "John Doe" 1185 }, 1186 "status":"completed", 1187 "object": { 1188 "type": "book", 1189 "title": "A Tale of Two Cities" 1190 } 1191 } 1193 Author's Address 1195 James M Snell (editor) 1196 IBM