idnits 2.17.1
draft-snell-activitystreams-04.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 (September 18, 2013) is 3872 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 1293, 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 September 18, 2013
5 Expires: March 22, 2014
7 JSON Activity Streams 2.0
8 draft-snell-activitystreams-04
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 March 22, 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 . . . . . . . . . . . . . . . . . . . . . . . . 3
66 1.1. Relationship to JSON Activity Streams 1.0 . . . . . . . . 3
67 1.2. Relationship to JSON-LD 1.0 . . . . . . . . . . . . . . . 4
68 1.3. Syntax Conventions . . . . . . . . . . . . . . . . . . . 5
69 2. Example Activities . . . . . . . . . . . . . . . . . . . . . 5
70 2.1. Example 1: Minimal Activity . . . . . . . . . . . . . . . 5
71 2.2. Example 2: Basic activity with some additional detail . . 6
72 2.3. Example 3: An extended activity . . . . . . . . . . . . . 6
73 3. Object Model . . . . . . . . . . . . . . . . . . . . . . . . 8
74 3.1. Object . . . . . . . . . . . . . . . . . . . . . . . . . 8
75 3.2. Natural Language Values . . . . . . . . . . . . . . . . . 9
76 3.3. Type Values . . . . . . . . . . . . . . . . . . . . . . . 9
77 3.4. Link Values . . . . . . . . . . . . . . . . . . . . . . . 11
78 3.5. Activity . . . . . . . . . . . . . . . . . . . . . . . . 14
79 3.5.1. Considerations on the use of "priority" . . . . . . . 15
80 3.5.2. Audience Targeting Properties . . . . . . . . . . . . 16
81 3.6. Additional Object Properties . . . . . . . . . . . . . . 18
82 3.6.1. Action Values . . . . . . . . . . . . . . . . . . . . 21
83 3.7. Collection . . . . . . . . . . . . . . . . . . . . . . . 21
84 3.7.1. Using Collections as Summary Values . . . . . . . . . 23
85 4. The Activity Stream JSON Document . . . . . . . . . . . . . . 24
86 5. Deprecated Activity Streams 1.0 Syntax . . . . . . . . . . . 25
87 6. Comparison of Identifier Values . . . . . . . . . . . . . . . 26
88 7. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 26
89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 26
90 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27
91 9.1. application/activity+xml Media Type . . . . . . . . . . . 27
92 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
93 10.1. Normative References . . . . . . . . . . . . . . . . . . 28
94 10.2. Informational References . . . . . . . . . . . . . . . . 29
95 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29
96 Appendix B. Processing as JSON-LD . . . . . . . . . . . . . . . 30
97 Appendix C. Motivational Use Cases . . . . . . . . . . . . . . . 31
98 C.1. Internationalization (i18n) . . . . . . . . . . . . . . . 31
99 C.2. Extensibility (e11y) . . . . . . . . . . . . . . . . . . 33
100 C.3. First Class Links . . . . . . . . . . . . . . . . . . . . 34
101 C.4. Use of External Vocabularies . . . . . . . . . . . . . . 35
102 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 37
104 1. Introduction
106 In the most basic sense, an "activity" is a semantic description of
107 potential or completed actions. In the former case, the activity
108 expresses what can be done with a particular object, while in the
109 latter case, it expresses what has already been done.
111 It is the goal of this specification to provide a JSON-based syntax
112 that is sufficient to express metadata about activities in a rich,
113 human-friendly, machine-processable and extensible manner. This may
114 include constructing natural-language descriptions or visual
115 representations about the activity, associating actionable
116 information with various types of objects, communicating or recording
117 activity logs, or delegation of potential actions to other
118 applications.
120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
122 document are to be interpreted as described in [RFC2119].
124 1.1. Relationship to JSON Activity Streams 1.0
126 The JSON Activity Streams 1.0 [activitystreams-1.0] specification was
127 published in May of 2011 and provided a baseline extensible syntax
128 for the expression of completed activities. This specification
129 builds upon that initial foundation by incorporating lessons learned
130 through extensive implementation, community feedback and related work
131 being performed in other standards development communities.
133 While the syntax defined by this specification diverges somewhat from
134 that defined by JSON Activity Streams 1.0, the verbs, objectTypes,
135 extensions and fundamental model defined by that original
136 specification remain intact.
138 Refer to Section 5 for more detail about the differences between the
139 1.0 and 2.0 syntax and for a listing of specific backwards
140 compatibility requirements.
142 This specification incorporates several existing extensions to the
143 1.0 syntax directly into the 2.0 model. These include portions of
144 the Activity Streams 1.0 Base Schema [base-schema], Audience
145 Targeting [audience], Responses [responses], and Priority [priority]
146 extensions.
148 1.2. Relationship to JSON-LD 1.0
150 The JSON-based Serialization for Linked Data (JSON-LD)
151 [W3C.WD-json-ld-20130411] describes a rich syntax for the
152 serialization of semantically-rich metadata using the JSON format.
153 While the updated Activity Streams representation provided by this
154 document is not defined as a "JSON-LD Vocabulary", the syntax is
155 designed to be closely compatible with JSON-LD.
157 There are a few differences between JSON-LD and the serialization
158 syntax described here, specifically:
160 o JSON-LD uses certain field names with a leading "@" character,
161 such as "@id" and "@language". In this specification, the leading
162 "@" is omitted.
164 o While JSON-LD allows using relative IRI references in the values
165 of "id" properties, this specification limits identifiers to
166 absolute IRIs.
168 o While it is possible to derive a JSON-LD "@context" description
169 for the Activity Streams 2.0 JSON syntax one is not normatively
170 provided by this specification.
172 When processing an Activity Streams document as JSON-LD, the
173 following rules apply:
175 o The "objectType" property MUST be treated as an alias of JSON-LD
176 "@type".
178 o The "id" property MUST be treated as an alias of JSON-LD "@id".
180 o The "language" property MUST be treated as an alias of JSON-LD
181 "@language".
183 o A JSON array used to convey Link (Section 3.4) values MUST be
184 treated as an unordered JSON-LD @set (@container = @set).
186 o The JSON array value for the "items" property defined in
187 Section 3.7 MUST be treated as an ordered JSON-LD @list
188 (@container = @list).
190 o The "displayName", "title", "content" and "summary" properties
191 defined in Section 3.1 and Section 3.6 MUST be treated as JSON-LD
192 Language Maps (@container = @language).
194 1.3. Syntax Conventions
196 This specification defines a JSON-based [RFC4627] serialization
197 syntax.
199 When serialized, absent properties are represented by either (a)
200 setting the property value to null, or (b) by omitting the property
201 declaration altogether at the option of the publisher; these
202 representations are semantically equivalent. If a property has an
203 array value, the absence of any items in that array MUST be
204 represented by omitting the property entirely or by setting the value
205 to null.
207 This specification uses IRIs [RFC3987]. Every URI [RFC3986] is also
208 an IRI, so a URI may be used wherever an IRI is named. There are two
209 special considerations: (1) when an IRI that is not also a URI is
210 given for dereferencing, it MUST be mapped to a URI using the steps
211 in Section 3.1 of [RFC3987] and (2) when an IRI is serving as an "id"
212 value, it MUST NOT be so mapped.
214 Unless otherwise specified, all properties with date and time values
215 MUST conform to the "date-time" production in [RFC3339], with an
216 uppercase "T" character used to separate date and time, and an
217 uppercase "Z" character in the absence of a numeric time zone offset.
218 All such timestamps SHOULD be represented relative to Coordinated
219 Universal Time (UTC).
221 2. Example Activities
223 Following are three examples of activities with varying degrees of
224 detail.
226 2.1. Example 1: Minimal Activity
228 Expresses the statement "'urn:example:person:martin' posted 'http://
229 example.org/foo.jpg'". No additional detail is given.
231 {
232 "verb": "post",
233 "actor": "urn:example:person:martin",
234 "object": "http://example.org/foo.jpg"
235 }
237 2.2. Example 2: Basic activity with some additional detail
239 Expresses the statement "Martin Smith posted an article to the blog
240 'Martin's Blog' at 3:04 PM GMT on February 2, 2011." Some additional
241 details about the article, actor and target blog are given.
243 {
244 "verb": "post",
245 "published": "2011-02-10T15:04:55Z",
246 "language": "en",
247 "actor": {
248 "objectType": "person",
249 "id": "urn:example:person:martin",
250 "displayName": "Martin Smith",
251 "url": "http://example.org/martin",
252 "image": {
253 "url": "http://example.org/martin/image.jpg",
254 "mediaType": "image/jpeg",
255 "width": 250,
256 "height": 250
257 }
258 },
259 "object" : {
260 "objectType": "article",
261 "id": "urn:example:blog:abc123/xyz"
262 "url": "http://example.org/blog/2011/02/entry",
263 "displayName": "Why I love Activity Streams"
264 },
265 "target" : {
266 "objectType": "blog",
267 "id": "urn:example:blog:abc123",
268 "displayName": "Martin's Blog",
269 "url": "http://example.org/blog/"
270 }
271 }
273 2.3. Example 3: An extended activity
275 A more extensive, single-entry "Activity Stream" follows. In
276 addition to containing a number of required and optional core
277 properties, the example contains the additional, undefined extension
278 properties "foo" and "foo2" for illustrative purposes only.
280 {
281 "totalItems": 1,
282 "items" : [
283 {
284 "verb": "post",
285 "language": "en",
286 "published": "2011-02-10T15:04:55Z",
287 "foo": "some extension property",
288 "generator": "http://example.org/activities-app",
289 "provider": "http://example.org/activity-stream",
290 "displayName": {
291 "en": "Martin posted a new video to his album.",
292 "ga": "Martin phost le fisean nua a albam."
293 },
294 "actor": {
295 "objectType": "person",
296 "id": "urn:example:person:martin",
297 "displayName": "Martin Smith",
298 "url": "http://example.org/martin",
299 "foo2": "some other extension property",
300 "image": {
301 "url": "http://example.org/martin/image",
302 "mediaType": "image/jpeg",
303 "width": 250,
304 "height": 250
305 }
306 },
307 "object" : {
308 "objectType": {
309 "id": "http://example.org/Photo",
310 "displayName": "Photo"
311 },
312 "id": "urn:example:album:abc123/my_fluffy_cat",
313 "url": "http://example.org/album/my_fluffy_cat.jpg",
314 "image": {
315 "url": "http://example.org/album/my_fluffy_cat_thumb.jpg",
316 "mediaType": "image/jpeg",
317 "width": 250,
318 "height": 250
319 }
320 },
321 "target": {
322 "objectType": {
323 "id": "http://example.org/PhotoAlbum",
324 "displayName": "Photo-Album"
325 },
326 "id": "urn:example.org:album:abc123",
327 "url": "http://example.org/album/",
328 "displayName": {
329 "en": "Martin's Photo Album",
330 "ga": "Grianghraif Mairtin"
331 },
332 "image": {
333 "url": "http://example.org/album/thumbnail.jpg",
334 "mediaType": "image/jpeg",
335 "width": 250,
336 "height": 250
337 }
338 }
339 }
340 ]
341 }
343 3. Object Model
345 3.1. Object
347 The following "core properties" apply to all JSON objects serialized
348 within an Activity Stream document.
350 +--------------+-------------+--------------------------------------+
351 | Property | Value | Description |
352 +--------------+-------------+--------------------------------------+
353 | id | IRI | Provides a permanent, universally |
354 | | | unique identifier for the object in |
355 | | | the form of an absolute IRI |
356 | | | [RFC3987]. Objects SHOULD contain a |
357 | | | single "id" property. If an object |
358 | | | does not contain an "id" property, |
359 | | | consumers MAY use the value of the |
360 | | | "url" property as a less-reliable, |
361 | | | non-unique identifier. |
362 | objectType | Type value | Identifies the type of object. An |
363 | | (Section | object MAY contain a "objectType" |
364 | | 3.3) | property whose value is a Type value |
365 | | | (Section 3.3). If no "objectType" |
366 | | | property is specified, the object |
367 | | | has no specific type. |
368 | language | [RFC5646] | Establishes the default language |
369 | | Language | assumed for human-readable, natural- |
370 | | Tag | language metadata values included in |
371 | | | the object. An object MAY contain a |
372 | | | "language" property whose value MUST |
373 | | | be a [RFC5646] Language-Tag. |
374 | displayName | Natural | A simple human-readable, plain-text |
375 | | Language | name for the object. HTML markup |
376 | | value | MUST NOT be included. An object MAY |
377 | | (Section | contain a "displayName" property. If |
378 | | 3.2) | the object does not specify a |
379 | | | "objectType" property, the object |
380 | | | SHOULD specify a "displayName". |
381 | url | Link | A Link (Section 3.4) value |
382 | | (Section | describing a resource that provides |
383 | | 3.4) value | a representation of the object. An |
384 | | | object MAY contain a "url" property. |
385 +--------------+-------------+--------------------------------------+
387 3.2. Natural Language Values
389 Natural Language values represent human-readable character sequences
390 in one or more languages. They are expressed as either (1) a single
391 JSON string or (2) a JSON dictionary mapping [RFC5646] Language-Tags
392 to localized, equivalent translations of the same string value.
394 For instance, the "displayName" property in all objects is a Natural
395 Language value.
397 A single String value using the default language:
399 {
400 "language": "en",
401 "displayName": "This is the title"
402 }
404 Multiple, language-specific values:
406 {
407 "displayName": {
408 "en": "This is the title",
409 "fr": "C'est le titre",
410 "sp": "Este es el titulo"
411 }
412 }
414 Each key in the JSON dictionary MUST be an [RFC5646] Language Tag.
415 The associated values MUST be Strings.
417 3.3. Type Values
418 Type values represent references to or descriptions of an abstract
419 type. They are expressed as either: (1) a String conforming to
420 either the "isegment-nz-nc" or "IRI" productions in [RFC3987] or (2)
421 an Object (Section 3.1). When represented as a String, the use of
422 relative references other than a simple name is not allowed. When
423 represented as an Object, the "id" property MUST be specified.
425 Within the Activity Streams 2.0, Type values are used only by the
426 "objectType" and "verb" properties.
428 Object type as a simple name (isegment-nz-nc):
430 {
431 "objectType": "person",
432 "displayName": "John"
433 }
435 Object type as an absolute IRI:
437 {
438 "objectType": "http://example.org/Person",
439 "displayName": "John"
440 }
442 Object type as an object:
444 {
445 "objectType": {
446 "id": "http://example.org/Person",
447 "displayName": "Person"
448 },
449 "displayName": "John"
450 }
452 Because the second and third examples above each specify "http://
453 example.org/Person", the two examples are considered to specify the
454 same type.
456 Verb as a simple name (isegment-nz-nc):
458 {
459 "verb": "post",
460 "actor": "acct:john.doe@example.org",
461 "object": "http://example.org/123"
462 }
464 Verb as an absolute IRI:
466 {
467 "verb": "http://example.com/Upload",
468 "actor": "acct:john.doe@example.org",
469 "object": "http://example.org/123"
470 }
472 Verb as an object:
474 {
475 "verb": {
476 "id": "http://example.com/Upload",
477 "displayName": "Upload"
478 },
479 "actor": "acct:john.doe@example.org",
480 "object": "http://example.org/123"
481 }
483 Allowing verbs and object types to be represented as objects rather
484 than simple names or IRIs is intended to simplify the use of
485 extensions that an implementation might not have encountered
486 previously. The object properties provide additional information and
487 metadata about the new verb or object type.
489 It is important to note that because the "id" property is strictly
490 limited to absolute IRI values, the object representation cannot be
491 used to describe types with simple names.
493 3.4. Link Values
495 Link values represent references to other objects and resources.
496 They are expressed as either: (1) a String containing an absolute or
497 relative IRI, (2) an Object (Section 3.1), or (3) a JSON Array
498 containing a mixture of IRIs or Objects (Section 3.1). Link values
499 are closely related to the conceptual model of Links as established
500 in [RFC5988].
502 For example, as defined previously, all objects (Section 3.1) can
503 contain an "image" property whose value describes a graphical
504 representation of the containing object. This property will
505 typically be used to provide the URL to a JPEG, GIF or PNG type
506 resource that can be displayed to the user. Any given object might
507 have multiple such visual representations -- multiple screenshots,
508 for instance, or the same image at different resolutions. Using Link
509 values, there are essentially three ways of describing such
510 references.
512 To reference a single image without any additional metadata, the link
513 value can be expressed as a simple JSON string containing an absolute
514 or relative IRI:
516 {
517 "objectType": "application",
518 "id": "http://example.org/application/123",
519 "displayName": "My Application",
520 "image": "http://example.org/application/123.png"
521 }
523 Alternatively, if additional metadata is required, the link can be
524 expressed as an object containing the url property.
526 {
527 "objectType": "application",
528 "id": "http://example.org/application/123",
529 "displayName": "My Application",
530 "image": {
531 "url": "http://example.org/application/123.png",
532 "mediaType": "image/png",
533 "height": 320,
534 "width": 320
535 }
536 }
538 If more than one link value is to be expressed, A JSON Array with a
539 mix of string and object elements can be used:
541 {
542 "objectType": "application",
543 "id": "http://example.org/application/123",
544 "displayName": "My Application",
545 "image": [
546 "http://example.org/application/abc.gif",
547 {
548 "url": "http://example.org/application/123.png",
549 "mediaType": "image/png",
550 "height": 320,
551 "width": 320
552 }
553 ]
554 }
556 Individual items contained in such an array are independent of the
557 others and no significance is given to the ordering of those items.
559 RFC 5988 defines that all Links have a "link relation" that describes
560 the contextual purpose of the link. Within an object (Section 3.1),
561 in the absence of a specific "rel" property within the link object
562 itself, the name of the property whose value is a link serves as the
563 "link relation". Any valid link relation value, as defined by RFC
564 5988, can be used as a property with a link value in any Activity
565 Streams object, except where the link relation might conflict with
566 any other property defined by this specification.
568 In the following example, two separate links are provided. The link
569 relation of the first is "image", while the link relation of the
570 second is "preview". Both links, however, can be used as alternative
571 visual representations of the "application" object.
573 {
574 "objectType": "application",
575 "image": [
576 "http://example.org/foo.jpg",
577 {
578 "url": "http://example.org/screens/1.jpg",
579 "rel": "preview",
580 "mediaType": "image/jpeg"
581 }
582 ]
583 }
585 When an object (Section 3.1) is used to represent a Link value, the
586 following additional properties MAY be used:
588 +-------------+--------------+--------------------------------------+
589 | Property | Value | Description |
590 +-------------+--------------+--------------------------------------+
591 | rel | RFC 5988 | The RFC 5988 Link Relation |
592 | | Link | associated with this link value. If |
593 | | Relation | absent, the name of the property is |
594 | | | assumed to specify the link |
595 | | | relation. |
596 | mediaType | MIME Media | The MIME media type of the resource |
597 | | Type | being referenced. |
598 +-------------+--------------+--------------------------------------+
600 3.5. Activity
602 Activity objects are specializations of the base Object (Section 3.1)
603 type that provide metadata about potential or completed actions.
605 Within an Activity object, the "verb" property is used to identify
606 the type of activity. All existing verb definitions used in JSON
607 Activity Streams 1.0 implementations can continue to be used and
608 retain their existing semantics. If the "verb" is not specified, the
609 "objectType" property MAY be used as an alternative means of
610 determining the activity type.
612 Activity objects extend the core object (Section 3.1) definition with
613 the following additional, optional properties:
615 +-----------+------------+------------------------------------------+
616 | Property | Value | Description |
617 +-----------+------------+------------------------------------------+
618 | verb | Type value | Identifies the type of activity. An |
619 | | (Section | activity SHOULD contain a "verb" |
620 | | 3.3) | property whose value is a Type value |
621 | | | (Section 3.3). If the "verb" property |
622 | | | is not specified, the activity MUST |
623 | | | contain a "objectType" property. |
624 | actor | Link | Describes one or more entities that |
625 | | (Section | either peformed or are expected to |
626 | | 3.4) value | perform the activity. |
627 | object | Link | Describes the primary object of the |
628 | | (Section | activity. For instance, in the activity, |
629 | | 3.4) value | "John saved a movie to his wishlist", |
630 | | | the object of the activity is "movie". |
631 | | | An activity SHOULD contain an "object" |
632 | | | property. If the "object" property is |
633 | | | not contained, the primary object of the |
634 | | | activity MAY be implied by context. |
635 | target | Link | Describes the target of the activity. |
636 | | (Section | The precise meaning of the activity's |
637 | | 3.4) value | target is dependent on the activities |
638 | | | "verb", but will often be the object the |
639 | | | English preposition "to". For instance, |
640 | | | in the activity, "John saved a movie to |
641 | | | his wishlist", the target of the |
642 | | | activity is "wishlist". The activity |
643 | | | target MUST NOT be used to identity an |
644 | | | indirect object that is not a target of |
645 | | | the activity. |
646 | result | Link | Describes the result of the activity. |
647 | | (Section | For instance, if a particular action |
648 | | 3.4) value | results in the creation of a new |
649 | | | resource, the "result" property can be |
650 | | | used to describe that new resource. |
651 | priority | Decimal | An indicator of the relative priority or |
652 | | Number | importance that the creator of an |
653 | | between | activity considers the it to have. |
654 | | 0.00 and | Represented as a numeric decimal between |
655 | | 1.00 | 0.00 and 1.00, with two decimal places |
656 | | | of precision. If the property is omitted |
657 | | | or set to null, the assumption is that a |
658 | | | default priority can be assumed. The |
659 | | | value 0.00 represents the lowest |
660 | | | possible priority while 1.00 represents |
661 | | | the highest. |
662 +-----------+------------+------------------------------------------+
664 3.5.1. Considerations on the use of "priority"
666 The presence of the "priority" property does not impose any specific
667 processing or display requirements on the part of any entity
668 consuming the activity.
670 Expressing the value as a range of numeric decimal values is intended
671 to provide the greatest level of flexibility in the expression and
672 consumption of prioritization detail. It is expected that
673 implementors consuming activity objects containing "priority" will
674 utilize and expose the additional information in a number of
675 different ways depending on the unique requirements of each
676 application use case.
678 Many existing systems do not represent priority values as numeric
679 ranges. Such systems might use fixed, labeled brackets such as
680 "low", "normal" and "high" or "urgent". Similar mechanisms can be
681 established, by convention, when using the "priority" property. In
682 typical use, it is RECOMMENDED that implementations wishing to work
683 with such defined categories treat "priority" property values in the
684 range 0.00 to 0.25 as "low" priority; values greater than 0.25 to
685 0.75 as "normal" priority; and values greater than 0.75 to 1.00 as
686 "high" priority. Specific implementations are free to establish
687 alternative conventions for the grouping of priority values with the
688 caveat that such conventions likely will not be understood by all
689 implementations.
691 3.5.2. Audience Targeting Properties
693 Every Activity has both a Primary and Secondary audience. The
694 Primary audience consists of those entities either directly involved
695 in the performance of the activity or who "own" the objects involved.
696 The Secondary audience consists of the collection of entities sharing
697 an interest in the activity but who are not directly involved (e.g.
698 "followers").
700 For instance, suppose a social network of three individuals: Bob, Joe
701 and Jane. Bob and Joe are each friends with Jane but not friends
702 with one another. Bob has chosen to "follow" activities for which
703 Jane is directly involved. Jane shares a file with Joe.
705 In this example, Jane and Joe are each directly involved in the file
706 sharing activity and together make up the Primary Audience for that
707 event. Bob, having an interest in activities involving Jane, is the
708 Secondary Audience. Knowing this, a system that produces or consumes
709 the activity can intelligently notify each person of the event.
711 While there are means, based on the verb, actor, object and target of
712 the activity, to infer the primary audience for many types of
713 activities, those do not work in every case and do not provide a
714 means of identifying the secondary audience. The "to", "cc", "bto"
715 and "bcc" properties MAY be used within an Activity to explicitly
716 identify the Primary and Secondary audiences.
718 +--------------+--------------------+-------------------------------+
719 | Property | Value | Description |
720 +--------------+--------------------+-------------------------------+
721 | to | Link (Section 3.4) | Specifies the public primary |
722 | | value | audience. |
723 | cc | Link (Section 3.4) | Specifies the public |
724 | | value | secondary audience. |
725 | bto | Link (Section 3.4) | Specifies the private primary |
726 | | value | audience. |
727 | bcc | Link (Section 3.4) | Specifies the private |
728 | | value | secondary audience. |
729 +--------------+--------------------+-------------------------------+
731 The prototypical use case for an Activity containing these properties
732 is the publication and redistribution of Activities through an
733 intermediary. That is, an event source generates the activity and
734 publishes it to the intermediary which determines a subset of events
735 to display to specific individual users or groups. Such a
736 determination can be made, in part, by identifying the Primary and
737 Secondary Audiences for each activity.
739 When the event source generates the activity and specifies values for
740 the to and cc fields, the intermediary SHOULD redistribute that event
741 with the values of those fields intact, allowing any processor to see
742 who the activity has been targeted to. This is precisely the same
743 model used by the to and cc fields in email systems.
745 There are situations, however, in which disclosing the identity of
746 specific members of the audience may be inappropriate. For instance,
747 a user may not wish to let other users know that they are interested
748 in various topics, individuals or types of events. To support this
749 option, an event source generating an activity MAY use the "bto" and
750 "bcc" properties to list entities to whom the activity should be
751 privately targeted. When an intermediary receives an activity
752 containing these properties, it MUST remove those values prior to
753 redistributing the activity. The intent is that systems MUST
754 consider entities listed within the "bto" and "bcc" properties as
755 part of the Primary and Second audience but MUST NOT disclose that
756 fact to any other party.
758 Audience targeting information included within an Activity only
759 describes the intent of the activity creator. With clear exception
760 given to the appropriate handling of "bto" and "bcc", this
761 specification leaves it up to implementations to determine how the
762 audience targeting information is used.
764 3.6. Additional Object Properties
766 The following "additional properties" MAY be used with any JSON
767 Object serialized within an Activity Stream document.
769 +--------------+-------------+--------------------------------------+
770 | Property | Value | Description |
771 +--------------+-------------+--------------------------------------+
772 | alias | IRI | Provides a contextually meaningful |
773 | | | alternative label for the object in |
774 | | | addition to the "id". For instance, |
775 | | | within some systems, groups can be |
776 | | | identified both by a unique global |
777 | | | ID and a more "human-friendly" label |
778 | | | such as "@friends" or "@network". |
779 | | | The value of the "alias" property |
780 | | | MUST match either the "isegment-nz- |
781 | | | nc" or the "IRI" production in |
782 | | | [RFC3987]. The use of a relative |
783 | | | reference other than a simple name |
784 | | | is not allowed. |
785 | attachments | Link | A Link (Section 3.4) value |
786 | | (Section | referencing one or more objects |
787 | | 3.4) value | associated with the containing |
788 | | | object. These are similiar in |
789 | | | concept to files attached to an |
790 | | | email message. |
791 | author | Link | A Link (Section 3.4) value |
792 | | (Section | referencing one or more entity that |
793 | | 3.4) value | created or authored the object. |
794 | content | Natural | A Natural-language description of |
795 | | Language | the object encoded as a single JSON |
796 | | value | String containing HTML markup. |
797 | | (Section | Visual elements such as thumbnail |
798 | | 3.2) | images MAY be included. |
799 | duplicates | Link | A Link (Section 3.4)value |
800 | | (Section | referencing one or more objects that |
801 | | 3.4) value | are semantically equivalent to this |
802 | | | object or duplicate this objects |
803 | | | content. An object SHOULD contain a |
804 | | | "duplicates" property when there are |
805 | | | known objects, possibly in a |
806 | | | different system, that are |
807 | | | semantically equivalent or duplicate |
808 | | | the content. |
809 | icon | Link | A Link (Section 3.4) value |
810 | | (Section | referencing one or more visual, |
811 | | 3.4) value | graphic representations of the |
812 | | | object, intended for human |
813 | | | consumption. The visual element |
814 | | | SHOULD have an aspect ratio of one |
815 | | | (horizontal) to one (vertical) and |
816 | | | SHOULD be suitable for presentation |
817 | | | at a small size. |
818 | image | Link | A Link (Section 3.4) value |
819 | | (Section | referencing one or more visual, |
820 | | 3.4) value | graphic represenations of the |
821 | | | object. Unlike the "icon" property, |
822 | | | there are no aspect ratio or display |
823 | | | restrictions. |
824 | location | Link | A Link (Section 3.4) value |
825 | | (Section | describing one or more physical or |
826 | | 3.4) value | virtual locations associated with |
827 | | | which the object. |
828 | published | [RFC3339] | The date and time at which the |
829 | | date-time | object was published. |
830 | generator | Link | A Link (Section 3.4) value |
831 | | (Section | referencing the application that |
832 | | 3.4) value | generated the object. |
833 | provider | Link | A Link (Section 3.4) value |
834 | | (Section | referencing the application that |
835 | | 3.4) value | published the object. Note that this |
836 | | | is not necessarily the same entity |
837 | | | that generated the object. |
838 | summary | Natural | A Natural-language summarization of |
839 | | Language | the object encoded as a single JSON |
840 | | value | String containing a fragment of HTML |
841 | | (Section | markup. Visual elements such as |
842 | | 3.2) | thumbnail images can be included. |
843 | updated | [RFC3339] | The date and time at which a |
844 | | date-time | previously published object has been |
845 | | | modified. |
846 | startTime | [RFC3339] | A date-time describing the actual or |
847 | | date-time | expected starting time of the |
848 | | | object. When used within an Activity |
849 | | | object, for instance, the |
850 | | | "startTime" specifies the moment the |
851 | | | activity began or is scheduled to |
852 | | | begin. |
853 | endTime | [RFC3339] | A date-time describing the actual or |
854 | | date-time | expected ending time of the object. |
855 | | | When used within an Activity object, |
856 | | | for instance, the "endTime" |
857 | | | specifies the moment the activity |
858 | | | concluded or is scheduled to |
859 | | | conclude. |
860 | rating | Decimal | A quality rating expressed as a |
861 | | Number | number between 1.0 and 5.0 |
862 | | between 1.0 | (inclusive) with one decimal place |
863 | | and 5.0 | of precision. |
864 | tags | Link | A Link (Section 3.4) value |
865 | | (Section | referencing one or more resources |
866 | | 3.4) value | that are loosely associated with the |
867 | | | containing object. The "tags" and |
868 | | | "attachments" properties differ from |
869 | | | one another in that the "tags" |
870 | | | property asserts "association by |
871 | | | reference" while "attachments" |
872 | | | asserts "association by enclosure". |
873 | title | Natural | A Natural-language title for the |
874 | | Language | object expressed as a fragment of |
875 | | (Section | HTML markup. The "title" and |
876 | | 3.2) value | "displayName" properties are closely |
877 | | | related and overlap in function with |
878 | | | the key difference being that |
879 | | | "title" is permitted to contain HTML |
880 | | | markup, while "displayName" is not. |
881 | duration | Integer or | When the object describes a time- |
882 | | [RFC3339] | based resource, such as audio or |
883 | | duration | video, the "duration" property |
884 | | | indicates the approximate duration |
885 | | | of time expressed as an either an |
886 | | | RFC 3339 "duration" (e.g. a |
887 | | | duration of 5 seconds is represented |
888 | | | as "PT5S") or as a non-negative |
889 | | | integer specifying the duration in |
890 | | | seconds. |
891 | height | Integer | When the object describes a visual |
892 | | | resource, such as an image, video or |
893 | | | embeddable HTML page, the "height" |
894 | | | property indicates the recommended |
895 | | | display height in pixels. |
896 | width | Integer | When the object describes a visual |
897 | | | resource, such as an image, video or |
898 | | | embeddable HTML page, the "width" |
899 | | | property indicates the recommended |
900 | | | display width in pixels. |
901 | inReplyTo | Link | A Link (Section 3.4) value |
902 | | (Section | identifying one or more other |
903 | | 3.4) value | objects to which the containing |
904 | | | object can be considered a response. |
905 | actions | Action | An optional Action (Section 3.6.1) |
906 | | (Section | value that describes potential |
907 | | 3.6.1) | activities that can be performed |
908 | | value | with the object. |
909 +--------------+-------------+--------------------------------------+
911 3.6.1. Action Values
913 The "actions" property on an Activity Streams object is used to
914 describe the kinds of activities that can be taken with regards to
915 the object. The value is expressed as a JSON dictionary mapping
916 verbs to Link (Section 3.4) values referencing resources or objects
917 that can be used to carry out those verbs.
919 For instance, a hypothetical object with "video" as the objectType
920 might have "watch", "share" and "embed" as potential actions:
922 {
923 "objectType": "video",
924 "id": "http://example.org/cats.mpg",
925 "actions": {
926 "watch": "movie://example.org/cats.mpg",
927 "share": {
928 "objectType": "service",
929 "displayName": "My Sharing Service",
930 "url": "http://example.net/share"
931 },
932 "embed": [
933 "http://example.org/gadgets/video.xml?v=cats.mpg",
934 {
935 "objectType": "inline-html",
936 "content": ""
937 }
938 ]
939 }
940 }
942 Each key in the Action value MUST be a valid verb identifier
943 conforming to either the "isegment-nz-nc" or "IRI" productions in
944 [RFC3987] and be suitable for use as a value for Activity
945 (Section 3.5) object's "verb" property. The value of each key MUST
946 be a valid Link (Section 3.4) value.
948 3.7. Collection
949 Collection objects are a specialization of the base Object
950 (Section 3.1) that contain a listing of other objects (Section 3.1)
951 The Collection object is used primarily as the root of an Activity
952 Streams document as described in Section 4, but can be used as the
953 value of object properties.
955 Collections have both a logical model and a physical serialization.
956 While the logical view of a collection might contain a large number
957 of objects, any single serialized representation might include only a
958 subset of those objects, with specific Link (Section 3.4) values used
959 to reference additional serialized representations that include
960 additional subsets. Such representations are known as "multi-page
961 collections", with each serialized subset representing a single
962 "page".
964 The value of the Collection object's "objectType" property MUST be
965 "collection" unless the fact that the object is a collection can be
966 determined by context.
968 Collection objects extend the core object (Section 3.1) definition
969 with the following additional properties:
971 +--------------+--------------+-------------------------------------+
972 | Property | Value | Description |
973 +--------------+--------------+-------------------------------------+
974 | totalItems | Integer | Non-negative integer specifying the |
975 | | | total number of objects contained |
976 | | | by the logical view of the |
977 | | | collection. This number might not |
978 | | | reflect the actual number of items |
979 | | | serialized within the Collection |
980 | | | object instance. |
981 | items | Array of | An array containing a listing of |
982 | | Objects | Objects (Section 3.1) of any type. |
983 | | (Section | |
984 | | 3.1) | |
985 | itemsAfter | [RFC3339] | A RFC 3339 date-time that indicates |
986 | | date-time | that the collection contains only |
987 | | | items published or updated strictly |
988 | | | after the date and time specified. |
989 | itemsBefore | [RFC3339] | A RFC 3339 date-time that indicates |
990 | | date-time | that the collection contains only |
991 | | | items published or updated strictly |
992 | | | before the date and time specified. |
993 | itemsPerPage | Integer | A non-negative integer specifying |
994 | | | the maximum number of items that |
995 | | | will be included in the value of |
996 | | | the items array. |
997 | startIndex | Integer | A non-negative integer value |
998 | | | identifying the relative position |
999 | | | within the logical view of |
1000 | | | collection of the first object |
1001 | | | contained in the items property. |
1002 | | | For instance, if there are 20 items |
1003 | | | that are considered to be members |
1004 | | | of a collection, but only the last |
1005 | | | 10 of those items are included in |
1006 | | | the items property, the value of |
1007 | | | startIndex would be 10. |
1008 | first | Link | A Link (Section 3.4) value |
1009 | | (Section | referencing the furthest preceeding |
1010 | | 3.4) value | page of a multi-page collection. |
1011 | last | Link | A Link (Section 3.4) value |
1012 | | (Section | referencing the furthest following |
1013 | | 3.4) value | page of a multi-page collection. |
1014 | prev | Link | A Link (Section 3.4) value |
1015 | | (Section | referencing the immediately |
1016 | | 3.4) value | preceding page of the multi-page |
1017 | | | collection. Note that the property |
1018 | | | name previous can be used as an |
1019 | | | equivalent alternative; however |
1020 | | | implementations SHOULD use prev and |
1021 | | | MUST NOT use both prev AND previous |
1022 | | | within the same collection. |
1023 | next | Link | A Link (Section 3.4) value |
1024 | | (Section | referencing the immediately |
1025 | | 3.4) value | following page of the multi-page |
1026 | | | collection. |
1027 | current | Link | A Link (Section 3.4) value |
1028 | | (Section | referencing the page containing the |
1029 | | 3.4) value | items that have been updated or |
1030 | | | published most recently. |
1031 | self | Link | A Link (Section 3.4) value |
1032 | | (Section | referencing this page. |
1033 | | 3.4) value | |
1034 +--------------+--------------+-------------------------------------+
1036 3.7.1. Using Collections as Summary Values
1038 It is a common practice to use Collection objects to provide summary
1039 information on the number of specific types of events that have
1040 occurred with respect to any given object. For instance, a "note"
1041 object may have been "shared" or "liked" a number of times by
1042 different individuals. In such cases, the Collection object is used
1043 as a property value with the "totalItems" field used to indicate the
1044 total number of occurrences, the "items" property used to provide
1045 details for a subset of the most recent occurrences, and the "id"
1046 property used to reference a separate Activity Streams document
1047 providing additional information.
1049 This specification defines the following properties that MAY be used
1050 within any object (Section 3.1) as "summary values":
1052 +------------+-----------------+------------------------------------+
1053 | Property | Value | Description |
1054 +------------+-----------------+------------------------------------+
1055 | replies | Collection | Provides information about the set |
1056 | | (Section 3.7) | of objects that can be considered |
1057 | | | to be replies to the containing |
1058 | | | object. |
1059 +------------+-----------------+------------------------------------+
1061 In the following example, the "replies" property is used to indicate
1062 that a note has 10 responses, and provides information on the most
1063 recently received response:
1065 {
1066 "objectType": "note",
1067 "id": "urn:example:note:1",
1068 "displayName": "A note about things",
1069 "content": "blah blah blah",
1070 "replies": {
1071 "url": "http://example.org/note/1/comments.json",
1072 "mediaType": "application/activity+json",
1073 "totalItems": 10,
1074 "items": [
1075 {
1076 "objectType": "note",
1077 "id": "urn:example:note:1:A",
1078 "content": "That's profound, man."
1079 }
1080 ]
1081 }
1082 }
1084 4. The Activity Stream JSON Document
1086 The above defined JSON serialization can be used to represent
1087 activities, objects and media links in any context. This section
1088 defines one particular use of the above formats to publish a JSON
1089 document representing an ordered listing of Activity objects.
1091 Publishers using this format MUST produce a valid JSON document whose
1092 root value is a Collection (Section 3.7).
1094 The MIME media type of this document MUST be "application/
1095 activity+json".
1097 5. Deprecated Activity Streams 1.0 Syntax
1099 The JSON syntax defined by this specification differs somewhat from
1100 that defined in the original JSON Activity Streams 1.0
1101 [activitystreams-1.0] specification in ways that are not backwards
1102 compatible. Implementations can choose to continue supporting the
1103 JSON Activity Streams 1.0 syntax but SHOULD consider it to be
1104 deprecated. This means that while implementations MAY continue to
1105 consume the 1.0 syntax, they SHOULD NOT output the 1.0 syntax unless
1106 specifically interacting with older non-2.0 compliant
1107 implementations.
1109 Specifically:
1111 1. Implementations MUST use the "application/stream+json" MIME media
1112 type when producing a JSON serialization of an Activity Object
1113 conforming to the 1.0 syntax, and "application/activity+json"
1114 when producing a serialization conforming to the 2.0 syntax.
1116 2. Implementations that process serializations of an Activity Object
1117 identified using either the "application/stream+json" or the more
1118 generic "application/json" MIME media type MUST follow the syntax
1119 and processing rules set by [activitystreams-1.0]. The 2.0
1120 syntax and processing rules apply only when handling
1121 serializations using the "application/activity+json" media type.
1123 3. This document redefines the "displayName", "title", "content" and
1124 "summary" properties as Natural Language values (Section 3.2),
1125 which means their values can be expressed as either a String or a
1126 JSON-LD Language Map. In the 1.0 syntax, these are expressed
1127 solely as String values. Because the 1.0 values are a valid
1128 subset allowed by this specification, implementations are not
1129 required to take any specific action to continue supporting those
1130 values.
1132 4. This document redefines a large number of common properties
1133 defined originally as Objects in 1.0 as Link values
1134 (Section 3.4). This means the property values can be expressed
1135 as either an IRI String, an Object, or an Array of IRI Strings
1136 and Objects. Because the 1.0 values are a valid subset allowed
1137 by this specification, implementations are not required to take
1138 any specific action to continue supporting those values.
1140 5. This specification replaces the "upstreamDuplicates" and
1141 "downstreamDuplicates" properties defined in the 1.0 syntax with
1142 a singular "duplicates" property with a Link value (Section 3.4).
1143 The "upstreamDuplicates" and "downstreamDuplicates" property
1144 values in 1.0 are defined as Arrays of strings. Implementations
1145 MUST consider the union of these two values as an alias for the
1146 "duplicates" property.
1148 By following these requirements, all JSON Activity Streams 1.0
1149 serializations can be processed successfully by 2.0 implementations.
1151 6. Comparison of Identifier Values
1153 The values of "id" properties can be compared to determine if the
1154 identifiers represent duplicate content. The values MUST be compared
1155 on a character-by-character, case-sensitive basis. Comparisons MUST
1156 be based solely on the character strings themselves and MUST NOT rely
1157 on dereferencing the IRIs or URIs mapped from them.
1159 As a consequence, two IRIs that resolve to the same resource but are
1160 not character-for-character identical will be considered different
1161 for the purposes of identifier comparison. In such cases, the
1162 "duplicates" property can be used to expressly relate such objects to
1163 one another.
1165 7. Extensibility
1167 Processors that encounter unfamiliar properties within any Activity
1168 Streams object MUST NOT stop processing or signal an error and MUST
1169 continue processing the items as if those properties were not
1170 present.
1172 8. Security Considerations
1174 Publishers or Consumers implementing Activity Streams as a stream of
1175 public data may also want to consider the potential for unsolicited
1176 commercial or malicious content and should take preventative measures
1177 to recognize such content and either identify it or not include it in
1178 their implementations.
1180 Publishers should take reasonable measures to ensure potentially
1181 malicious user input such as cross-site scripting attacks are not
1182 included in the Activity Streams data they publish.
1184 Consumers that re-emit ingested content to end-users MUST take
1185 reasonable measures if emitting ingested content to make sure
1186 potentially malicious ingested input is not re-emitted.
1188 Consumers that re-emit ingested content for crawling by search
1189 engines should take reasonable measures to limit any use of their
1190 site as a Search Engine Optimization loophole. This may include
1191 converting un-trusted hyperlinks to text or including a
1192 rel="nofollow" attribute.
1194 Consumers should be aware of the potential for spoofing attacks where
1195 the attacker publishes activities or objects with falsified property
1196 values with the intent of injecting malicious content, hiding or
1197 corrupting legitimate content, or misleading users.
1199 Activity Streams are JSON Documents and are subject to the same
1200 security considerations described in [RFC4627].
1202 Activity Streams implementations handle URIs. See Section 7 of
1203 [RFC3986].
1205 Activity Streams implementations handle IRIs. See Section 8 of
1206 [RFC3987].
1208 9. IANA Considerations
1210 9.1. application/activity+xml Media Type
1212 This specification registers the application/activity+json MIME Media
1213 Type:
1215 Type name: application
1217 Subtype name: activity+json
1219 Required parameters: None
1221 Optional parameters: "charset" : Specifies the character set
1222 encoding. If not specified, a default of "UTF-8" is assumed.
1224 Encoding considerations: Resources that use the "application/
1225 activity+json" media type are required to conform to the
1226 "application/json" Media Type and are therefore subject to the
1227 same encoding considerations specified in Section 6 [RFC4627].
1229 Security considerations: As defined in this specification
1231 Published specification: This specification.
1233 Applications that use this media type: JSON Activity Streams are
1234 implemented by a wide range of existing applications.
1236 Additional information:
1238 Magic number(s): N/A
1240 File extension(s): N/A
1242 Macintosh file type code(s): TEXT
1244 Person & email address to contact for further information: James M
1245 Snell
1247 Intended usage: COMMON
1249 Restrictions on usage: None.
1251 Author: James M Snell
1253 Change controller: IESG
1255 10. References
1257 10.1. Normative References
1259 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1260 Requirement Levels", BCP 14, RFC 2119, March 1997.
1262 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
1263 Internet: Timestamps", RFC 3339, July 2002.
1265 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1266 Resource Identifier (URI): Generic Syntax", STD 66, RFC
1267 3986, January 2005.
1269 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
1270 Identifiers (IRIs)", RFC 3987, January 2005.
1272 [RFC4627] Crockford, D., "The application/json Media Type for
1273 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
1275 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
1276 Languages", BCP 47, RFC 5646, September 2009.
1278 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
1280 [W3C.WD-json-ld-20130411]
1281 Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0",
1282 World Wide Web Consortium LastCall WD-json-ld-20130411,
1283 April 2013,
1284 .
1286 [activitystreams-1.0]
1287 Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson,
1288 M., and R. Dolin, "JSON Activity Streams 1.0", May 2011,
1289 .
1291 10.2. Informational References
1293 [RFC6963] Saint-Andre, P., "A Uniform Resource Name (URN) Namespace
1294 for Examples", BCP 183, RFC 6963, May 2013.
1296 [audience]
1297 Snell, J., "Audience Targeting for JSON Activity Streams",
1298 March 2012,
1299 .
1301 [base-schema]
1302 Activity Streams Workgroup, "Activity Streams - Base
1303 Schema", September 2012, .
1307 [priority]
1308 Snell, J., "Priority Extension for JSON Activity Streams",
1309 June 2012, .
1312 [responses]
1313 Snell, J., "Responses for Activity Streams", March 2012,
1314 .
1316 Appendix A. Acknowledgements
1318 The author wishes to thank the Activity Streams community and
1319 implementers for their support, encouragement, and enthusiasm
1320 including but not limited to: Abdul Qabiz, Adina Levin, Adrian Chan,
1321 Adriana Javier, Alan Hoffman, Alex Kessinger, Alexander Ovchinnikov,
1322 Alexander Zhuravlev, Alexandre Loureiro Solleiro, Amy Walgenbach,
1323 Andres Vidal, Angel Robert Marquez, Ari Steinberg, Arjan
1324 Scherpenisse, Arne Roomann-Kurrik, Beau Lebens, Ben Hedrington, Ben
1325 Metcalfe, Ben Werdmuller, Benjamin Goering, Bill de hOra, Bo Xing,
1326 Bob Aman, Bob Wyman, Brett Slatkin, Brian Walsh, Brynn Evans, Charlie
1327 Cauthen, Chris Chabot, Chris Messina, Chris Toomey, Christian
1328 Crumlish, Dan Brickley, Dan Scott, Daniel Chapman, Danny Ayers, Dare
1329 Obasanjo, Darren Bounds, David Cramer, David Nelson, David Recordon,
1330 DeWitt Clinton, Douglas Pearce, Ed Summers, Elias Bizannes, Elisabeth
1331 Norris, Eric Marcoullier, Eric Woods, Evan Prodromou, Gee-Hsien
1332 Chuang, Greg Biggers, Gregory Foster, Henry Saputra, Hillary Madsen,
1333 Howard Liptzin, Hung Tran, Ian Kennedy, Ian Mulvany, Ivan Pulleyn,
1334 Jacob Kim, James Falkner, James Pike, James Walker, Jason Kahn, Jason
1335 Kantz, Jeff Kunins, Jeff Martin, Jian Lin, Johannes Ernst, John
1336 Panzer, Jon Lebkowsky, Jon Paul Davies, Jonathan Coffman, Jonathan
1337 Dugan, Joseph Boyle, Joseph Holsten, Joseph Smarr, Josh Brewer, Jud
1338 Valeski, Julien Chaumond, Julien Genestoux, Jyri Engestroem, Kaliya
1339 Hamlin, Kevin Marks, Laurent Eschenauer, Laurie Voss, Leah Culver,
1340 Libby Miller, Manu Mukerji, Mark Weitzel, Marko Degenkolb, Marshall
1341 Kirkpatrick, Martin Atkins, Martin Svensson, Marty Alchin, Mary
1342 Hoder, Matt Leventi, Matt Wilkinson, Matthias Mueller-Prove, Max
1343 Engel, Max Wegmueller, Melvin Carvalho, Michael Buckbee, Michael
1344 Chan, Michael Richardson, Michael Sullivan, Mike Macgirvin, Mislav
1345 Marohnić, Mo Jangda, Monica Wilkinson, Nate Benes, NeilFred
1346 Picciotto, Nick Howard, Nick Lothian, Nissan Dookeran, Nitya
1347 Narasimhan, Pablo Martin, Padraic Brady, Pat G. Cappalaere, Patrick
1348 Aljord, Peter Ferne, Peter Reiser, Peter Saint-Andre, Phil Wolff,
1349 Philip (flip) Kromer, Richard Cunningham, Richard Zhao, Rick
1350 Severson, Robert Hall, Robert Langbert, Robert Dolin, Robin Cover,
1351 Ryan Boyd, Sam Sethi, Scott Raymond, Scott Seely, Simon Grant, Simon
1352 Wistow, Stephen Garcia, Stephen Sisk, Stephen Paul Weber, Steve Ivy,
1353 Steve Midgley, Steven Livingstone-Perez, Sylvain Carle, Sylvain
1354 Hellegouarch, Tantek Celik, Tatu Saloranta, Tim Moore, Timothy Young,
1355 Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley,
1356 and Zach Shepherd.
1358 Appendix B. Processing as JSON-LD
1360 While the Activity Streams 2.0 syntax is designed to be compatible
1361 with JSON-LD, in order to successfully process an Activity Streams
1362 document as JSON-LD, a "@context" description needs to be provided.
1363 The following example illustrates an Activity Streams document that
1364 can be processed as JSON-LD containing Schema.org defined metadata
1365 elements.
1367 {
1368 "@context": {
1369 "@vocab": "http://activitystrea.ms/spec/2.0/",
1370 "verb": "@type",
1371 "objectType": "@type",
1372 "id": "@id",
1373 "actor": "http://schema.org/Action/performedBy",
1374 "object": "http://schema.org/BuyAction/bought",
1375 "purchase": "http://schema.org/BuyAction",
1376 "person": "http://schema.org/Person",
1377 "book": "http://schema.org/Book"
1378 },
1379 "verb" : "purchase",
1380 "id" : "urn:example:purchase:123/abc",
1381 "displayName": "John purchased 'A Tale of Two Cities'",
1382 "startTime" : "2013-04-02T12:31Z",
1383 "endTime" : "2013-04-02T12:31Z",
1384 "actor": {
1385 "objectType": "person",
1386 "displayName": "John Doe"
1387 },
1388 "object": {
1389 "objectType": "book",
1390 "displayName": "A Tale of Two Cities"
1391 }
1392 }
1394 Appendix C. Motivational Use Cases
1396 This specification defines a number of syntax changes relative to the
1397 JSON Activity Streams 1.0 specification. The sections that follow
1398 describe some of the general motivations for these changes with
1399 illustrative examples.
1401 C.1. Internationalization (i18n)
1403 The JSON Activity Streams 1.0 syntax has no inherent notion of a
1404 "language context". That is, the core syntax has no internal
1405 mechanism a publisher can use to identify the language used when
1406 constructing the Activity Streams document. Nor are there any
1407 existing mechanisms at the JSON syntax level that an Activity Streams
1408 implementation can inherit. This specification introduces the
1409 "language" property and Natural Language Value concepts to fill this
1410 gap.
1412 Imagine a scenario with a service that receives Activity objects from
1413 users and republishes those to a distributed audience of interested
1414 parties. This service spans international boundaries and the users
1415 speak a multitude of different languages. Within this system, a
1416 native English speaker might subscribe to notifications about
1417 activities posted by a native French speaker.
1419 For instance, let's suppose that our native French speaker posts the
1420 following activity to this system:
1422 POST /activity/feed HTTP/1.1
1423 Content-Type: application/activity+xml
1424 {
1425 "verb": "post",
1426 "language": "fr",
1427 "object": {
1428 "objectType": "article",
1429 "displayName": "Un exemple basique",
1430 ...
1431 }
1432 }
1434 The system receives this activity post and prepares to notify our
1435 native English speaking user. Knowing that this user prefers English
1436 and does not speak a word of French, the system can inspect the
1437 Activity and detect automatically that a translation ought to be
1438 provided. Rather than replacing the original French text, however,
1439 the service can simply add in the English translation along side it.
1441 {
1442 "verb": "post",
1443 "language": "fr",
1444 "actor": {
1445 "id": "urn:example:person:abc",
1446 "displayName": "Jean Valjean"
1447 },
1448 "object": {
1449 "type": "article",
1450 "displayName": {
1451 "fr": "Un exemple basique",
1452 "en": "A basic example"
1453 }
1454 ...
1455 }
1456 }
1458 It is also possible for a Natural Language Value to express
1459 alternative same-language representations of a string that utilize
1460 different writing systems or regions. For instance, it is common for
1461 Japanese translations to provide equivalent ideographic (kanji) and
1462 phonetic (katakana or hiragana) alternatives:
1464 {
1465 "title": {
1466 "ja-Hani": "...",
1467 "ja-Kana": "..."
1468 }
1469 }
1471 C.2. Extensibility (e11y)
1473 Arguably, the two most important extensibility points in the Activity
1474 Streams format are the object type and verb properties.
1475 Implementations are free to come up with their own types and verbs at
1476 any point. While such extensibility is extremely powerful, it comes
1477 with a cost. Namely, implementations that encounter previously
1478 unknown verbs and object types may not have enough to knowledge about
1479 those to do anything significant with them.
1481 For instance, the most common use case for Activity Streams today is
1482 the generation of a human-readable "activity feed" that translates
1483 Activity objects into sentences just as "John uploaded a new photo"
1484 or "Jane checked in at a hotel", etc. Given an extension verb such
1485 as "http://example.org/whatever", an implementation might not have
1486 sufficient information about that verb to generate a readable
1487 sentence describing the activity that occurred.
1489 With Activity Streams 1.0, a number of different approaches have been
1490 tried to address this problem, but all of the solutions essentially
1491 deal with the need to provide additional metadata about extension
1492 verbs and object types so that an implementation can dynamically
1493 learn and adapt. The notion of "type values" is added by this
1494 specification to specifically deal with this issue.
1496 For example, suppose I have an implementation that generates Activity
1497 objects that use a new extension verb "urn:example:verbs:upload".
1498 Knowing that consumers of these objects might not have encountered
1499 this verb before, I want to make it possible for those
1500 implementations to automatically discover metadata about the new
1501 verb. To do so, I can use a type value to provide some basic
1502 information.
1504 {
1505 "verb": {
1506 "id": "urn:example:verbs:upload",
1507 "url": "http://example.org/verbs.json",
1508 "mediaType": "application/ld+json",
1509 "displayName": {
1510 "en": "upload",
1511 "fr": "televersement"
1512 },
1513 "alias": "post"
1514 },
1515 "actor": {
1516 "type": "person",
1517 "displayName": "John"
1518 },
1519 "object": {
1520 "type": "photo",
1521 "displayName": "cats.jpg"
1522 }
1523 }
1525 An implementation receiving this has several choices. It could
1526 choose to ignore everything other than the verb's identifier,
1527 treating it generically as one would have to today using the 1.0
1528 syntax; or, it could inspect the metadata provided and notice that
1529 the extension verb can be treated generally as an alias of "post" or
1530 displayed in English as "upload" and in French as "televersement";
1531 or, it can choose to attempt discovering more information about the
1532 verb by dereferencing the provided URL.
1534 The point is, these options are built into the core syntax, making
1535 extension verbs and object types significantly more usable,
1536 particularly when combined with the new language context features.
1538 C.3. First Class Links
1540 Linking in the 1.0 syntax is largely undefined and inconsistent.
1541 There is a general notion of Media Link objects that are used for
1542 some things like images and videos, along with a "url" property that
1543 in some cases is used to always point to HTML represenations while in
1544 other cases might point to JSON documents or image files, and there
1545 is no reusable concept of a generic link provided for extensions to
1546 leverage which has led to inconsistent implementation. The 2.0
1547 syntax introduced here deals with these issues by introducing a
1548 clear, consistent, reusable first class linking model.
1550 For instance, using the 2.0 syntax, an "image" object type can be
1551 represented simply as:
1553 {
1554 "objectType": "image",
1555 "url": "http://example.org/cats.jpg",
1556 "mediaType": "image/jpeg",
1557 "displayName": "A picture of my cats",
1558 "alternate": {
1559 "url": "http://example.org/gallery?i=cats.jpg",
1560 "mediaType": "text/html"
1561 }
1562 "preview": "http://example.org/thumbnails/cats.jpg"
1563 }
1565 Essentially, any 2.0 object that contains a "url" property can be
1566 interpreted as a link. That "url" property points to a
1567 representation of the object, while the "mediaType" property
1568 identifies the content type of that linked resource. RFC 5988 Link
1569 Relations can be used directly within the 2.0 syntax to provide
1570 additional data -- in this case, an alternative HTML representation
1571 of the image as well as a thumbnail preview.
1573 Another case that the more flexible linking approach allows us to
1574 address is providing multiple links for a single property. For
1575 instance, it is not uncommon for there to be several alternative
1576 versions of an image resource offered at various resolutions to
1577 support multiple types of devices. With the 2.0 syntax, multiple
1578 choices for a single link can be easily provided.
1580 {
1581 "objectType": "application",
1582 "displayName": "My application",
1583 "icon": [
1584 {
1585 "url": "http://example.org/sd/icon.png",
1586 "width": 57,
1587 "height": 57
1588 },
1589 {
1590 "url": "http://example.org/hd/icon.png",
1591 "width": 114,
1592 "height": 114
1593 }
1594 ],
1595 "preview": [
1596 "http://www.example.org/screenshots/1.jpg",
1597 "http://www.example.org/screenshots/2.jpg",
1598 "http://www.example.org/screenshots/3.jpg"
1599 ]
1600 }
1602 C.4. Use of External Vocabularies
1603 Use of an "external vocabulary" within Activity Streams means using
1604 object types, verbs and properties that are not defined by the core
1605 Activity Streams specification. An example would be using concepts
1606 defined within a microdata vocabulary such as that defined by
1607 Schema.org (http://schema.org).
1609 Implementations that wish to use a Activity Streams with such
1610 external vocabularies face the challenge that, often times, identical
1611 or overlapping concepts can be expressed in a multitude of ways
1612 depending on which vocabulary is selected. This can make it
1613 difficult to map abstract data models into a specific JSON
1614 serialization.
1616 For instance, suppose an application uses the Schema.org model to
1617 represent an article, described here: http://schema.org/Article.
1618 Within this model, there are several properties defined that directly
1619 overlap properties defined by the core Activity Streams syntax. Such
1620 properties include "name", "contentLocation", and "articleBody". In
1621 order to encode the abstact model of a Schema.org/Article into the
1622 JSON Activity Streams model, the application needs to determine
1623 precisely how to map the abstract properties to the serialized
1624 format. In Activity Streams 1.0, no guidance was given on how to
1625 achieve such a mapping, within the 2.0 syntax, the JSON Serialization
1626 for Linked Data (JSON-LD) provides a foundation.
1628 Using JSON-LD I can maintain basic Activity Streams 2.0 syntax while
1629 mapping the physical serialization to the abstract model inline.
1631 {
1632 "objectType": "article",
1633 "displayName": "My article about things",
1634 "content": "This is my article",
1635 "@context": {
1636 "objectType": "@type",
1637 "article": "http://schema.org/Article",
1638 "displayName": "http://schema.org/name",
1639 "content": "http://schema.org/Article/articleBody"
1640 }
1641 }
1643 For any non-JSON-LD aware implementation, this can be processed just
1644 as if it were an ordinary Activity Streams object, without any
1645 additional consideration given. For a JSON-Ld aware implementation,
1646 however, the addition of the "@context" property allows the
1647 serialized JSON to be unambiguously mapped to the Schema.org concept
1648 of an "Article". The fact that we can support such a mapping allows
1649 the Activity Streams format to extend to a broader range of scenarios
1650 without requiring alternative, incompatible vocabulary specific
1651 models of "actions" or "activities" to be developed.
1653 Author's Address
1655 James M Snell (editor)
1656 IBM
1658 Email: jasnell@gmail.com