Activity Streams (http://activitystrea.ms) J. Snell, Ed. Internet-Draft IBM Intended status: Standards Track April 19, 2014 Expires: October 21, 2014 JSON Activity Streams 2.0 draft-snell-activitystreams-07 Abstract This specification details a model for representing potential and completed activities using the JSON format. Author's Note This draft is heavily influenced by the original JSON Activity Streams 1.0 specification that was originally co-authored by Martin Atkins, Will Norris, Chris Messina, Monica Wilkinson, Rob Dolin and James Snell. The author is very thankful for their significant contributions and gladly stands on their shoulders. Some portions of the original text of Activity Streams 1.0 are used in this document. The Activity Streams 1.0 and 2.0 specifications are works produced by the Activity Streams Working Group (http://activitystrea.ms/) operating independently of the IETF. Discussion and feedback about this specification is invited and should be directed to the Activity Streams Mailing List (see https://groups.google.com/forum/#!forum/ activity-streams). Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 21, 2014. Snell Expires October 21, 2014 [Page 1] Internet-Draft ActivityStreams April 2014 Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Relationship to JSON Activity Streams 1.0 . . . . . . . . 3 1.2. Relationship to JSON-LD 1.0 . . . . . . . . . . . . . . . 4 1.3. Syntax Conventions . . . . . . . . . . . . . . . . . . . 5 2. Example Activities . . . . . . . . . . . . . . . . . . . . . 5 2.1. Example 1: Minimal Activity . . . . . . . . . . . . . . . 6 2.2. Example 2: Basic activity with some additional detail . . 6 2.3. Example 3: An extended activity . . . . . . . . . . . . . 7 3. Object Model . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Object . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Natural Language Values . . . . . . . . . . . . . . . . . 9 3.3. Type Values . . . . . . . . . . . . . . . . . . . . . . . 10 3.4. Link Values . . . . . . . . . . . . . . . . . . . . . . . 12 3.5. Activity . . . . . . . . . . . . . . . . . . . . . . . . 14 3.5.1. Considerations on the use of "priority" . . . . . . . 16 3.5.2. Audience Targeting Properties . . . . . . . . . . . . 17 3.6. Additional Object Properties . . . . . . . . . . . . . . 18 3.6.1. Action Values . . . . . . . . . . . . . . . . . . . . 21 3.7. Collection . . . . . . . . . . . . . . . . . . . . . . . 22 3.7.1. Using Collections as Summary Values . . . . . . . . . 24 4. The Activity Stream JSON Document . . . . . . . . . . . . . . 25 5. Reserved Object Types and Verbs . . . . . . . . . . . . . . . 26 5.1. Object Types . . . . . . . . . . . . . . . . . . . . . . 26 5.2. Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6. Deprecated Activity Streams 1.0 Syntax . . . . . . . . . . . 26 7. Comparison of Identifier Values . . . . . . . . . . . . . . . 27 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28 8.1. Extension verbs and objectTypes . . . . . . . . . . . . . 28 9. Security Considerations . . . . . . . . . . . . . . . . . . . 29 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 10.1. application/activity+xml Media Type . . . . . . . . . . 30 Snell Expires October 21, 2014 [Page 2] Internet-Draft ActivityStreams April 2014 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 11.1. Normative References . . . . . . . . . . . . . . . . . . 31 11.2. Informational References . . . . . . . . . . . . . . . . 32 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 32 Appendix B. Processing as JSON-LD . . . . . . . . . . . . . . . 33 Appendix C. Activity Statement Linguistic Forms . . . . . . . . 34 C.1. Intransitive Activity . . . . . . . . . . . . . . . . . . 34 C.2. Transitive Activity . . . . . . . . . . . . . . . . . . . 35 C.3. Ditransitive Activity . . . . . . . . . . . . . . . . . . 35 C.4. Expressing tense and aspect . . . . . . . . . . . . . . . 36 C.5. Activity Duration . . . . . . . . . . . . . . . . . . . . 38 Appendix D. Motivational Use Cases . . . . . . . . . . . . . . . 39 D.1. Internationalization (i18n) . . . . . . . . . . . . . . . 39 D.2. Extensibility (e11y) . . . . . . . . . . . . . . . . . . 40 D.2.1. Publishing Extension objectType and verb Libraries . 42 D.3. First Class Links . . . . . . . . . . . . . . . . . . . . 42 D.4. Use of External Vocabularies . . . . . . . . . . . . . . 44 D.5. Embedded Actions . . . . . . . . . . . . . . . . . . . . 45 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 45 1. Introduction In the most basic sense, an "activity" is a semantic description of potential or completed actions. In the former case, the activity expresses what can be done with a particular object, while in the latter case, it expresses what has already been done. It is the goal of this specification to provide a JSON-based syntax that is sufficient to express metadata about activities in a rich, human-friendly, machine-processable and extensible manner. This may include constructing natural-language descriptions or visual representations about the activity, associating actionable information with various types of objects, communicating or recording activity logs, or delegation of potential actions to other applications. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.1. Relationship to JSON Activity Streams 1.0 The JSON Activity Streams 1.0 [activitystreams-1.0] specification was published in May of 2011 and provided a baseline extensible syntax for the expression of completed activities. This specification builds upon that initial foundation by incorporating lessons learned through extensive implementation, community feedback and related work being performed in other standards development communities. Snell Expires October 21, 2014 [Page 3] Internet-Draft ActivityStreams April 2014 While the syntax defined by this specification diverges somewhat from that defined by JSON Activity Streams 1.0, the verbs, objectTypes, extensions and fundamental model defined by that original specification remain intact. Refer to Section 6 for more detail about the differences between the 1.0 and 2.0 syntax and for a listing of specific backwards compatibility requirements. This specification incorporates several existing extensions to the 1.0 syntax directly into the 2.0 model. These include portions of the Activity Streams 1.0 Base Schema [base-schema], Audience Targeting [audience], Responses [responses], and Priority [priority] extensions. 1.2. Relationship to JSON-LD 1.0 The JSON-based Serialization for Linked Data (JSON-LD) [W3C.WD-json-ld-20130411] describes a rich syntax for the serialization of semantically-rich metadata using the JSON format. While the updated Activity Streams representation provided by this document is not defined as a "JSON-LD Vocabulary", the syntax is designed to be closely compatible with JSON-LD. There are a few differences between JSON-LD and the serialization syntax described here, specifically: o JSON-LD uses certain field names with a leading "@" character, such as "@id" and "@language". In this specification, the leading "@" is omitted. o While JSON-LD allows using relative IRI references in the values of "id" properties, this specification limits identifiers to absolute IRIs. o While it is possible to derive a JSON-LD "@context" description for the Activity Streams 2.0 JSON syntax one is not normatively provided by this specification. When processing an Activity Streams document as JSON-LD, the following rules apply: o The "objectType" property MUST be treated as an alias of JSON-LD "@type". o The "id" property MUST be treated as an alias of JSON-LD "@id". Snell Expires October 21, 2014 [Page 4] Internet-Draft ActivityStreams April 2014 o The "language" property MUST be treated as an alias of JSON-LD "@language". o A JSON array used to convey Link (Section 3.4) values MUST be treated as an unordered JSON-LD @set (@container = @set). o The JSON array value for the "items" property defined in Section 3.7 MUST be treated as an ordered JSON-LD @list (@container = @list). o The "displayName", "title", "content" and "summary" properties defined in Section 3.1 and Section 3.6 MUST be treated as JSON-LD Language Maps (@container = @language). 1.3. Syntax Conventions This specification defines a JSON-based [RFC4627] serialization syntax. When serialized, absent properties are represented by either (a) setting the property value to null, or (b) by omitting the property declaration altogether at the option of the publisher; these representations are semantically equivalent. If a property has an array value, the absence of any items in that array MUST be represented by omitting the property entirely or by setting the value to null. This specification uses IRIs [RFC3987]. Every URI [RFC3986] is also an IRI, so a URI may be used wherever an IRI is named. There are two special considerations: (1) when an IRI that is not also a URI is given for dereferencing, it MUST be mapped to a URI using the steps in Section 3.1 of [RFC3987] and (2) when an IRI is serving as an "id" value, it MUST NOT be so mapped. Unless otherwise specified, all properties with date and time values MUST conform to the "date-time" production in [RFC3339], with an uppercase "T" character used to separate date and time, and an uppercase "Z" character in the absence of a numeric time zone offset. All such timestamps SHOULD be represented relative to Coordinated Universal Time (UTC). 2. Example Activities Following are three examples of activities with varying degrees of detail. Snell Expires October 21, 2014 [Page 5] Internet-Draft ActivityStreams April 2014 2.1. Example 1: Minimal Activity Expresses the statement "'urn:example:person:martin' posted 'http:// example.org/foo.jpg'". No additional detail is given. { "verb": "post", "actor": "urn:example:person:martin", "object": "http://example.org/foo.jpg" } 2.2. Example 2: Basic activity with some additional detail Expresses the statement "Martin Smith posted an article to the blog 'Martin's Blog' at 3:04 PM GMT on February 2, 2011." Some additional details about the article, actor and target blog are given. { "verb": "post", "published": "2011-02-10T15:04:55Z", "language": "en", "actor": { "objectType": "person", "id": "urn:example:person:martin", "displayName": "Martin Smith", "url": "http://example.org/martin", "image": { "url": "http://example.org/martin/image.jpg", "mediaType": "image/jpeg", "width": 250, "height": 250 } }, "object" : { "objectType": "article", "id": "urn:example:blog:abc123/xyz" "url": "http://example.org/blog/2011/02/entry", "displayName": "Why I love Activity Streams" }, "target" : { "objectType": "blog", "id": "urn:example:blog:abc123", "displayName": "Martin's Blog", "url": "http://example.org/blog/" } } Snell Expires October 21, 2014 [Page 6] Internet-Draft ActivityStreams April 2014 2.3. Example 3: An extended activity A more extensive, single-entry "Activity Stream" follows. In addition to containing a number of required and optional core properties, the example contains the additional, undefined extension properties "foo" and "foo2" for illustrative purposes only. { "totalItems": 1, "items" : [ { "verb": "post", "language": "en", "published": "2011-02-10T15:04:55Z", "foo": "some extension property", "generator": "http://example.org/activities-app", "provider": "http://example.org/activity-stream", "displayName": { "en": "Martin posted a new video to his album.", "ga": "Martin phost le fisean nua a albam." }, "actor": { "objectType": "person", "id": "urn:example:person:martin", "displayName": "Martin Smith", "url": "http://example.org/martin", "foo2": "some other extension property", "image": { "url": "http://example.org/martin/image", "mediaType": "image/jpeg", "width": 250, "height": 250 } }, "object" : { "objectType": { "id": "http://example.org/Photo", "displayName": "Photo" }, "id": "urn:example:album:abc123/my_fluffy_cat", "url": "http://example.org/album/my_fluffy_cat.jpg", "image": { "url": "http://example.org/album/my_fluffy_cat_thumb.jpg", "mediaType": "image/jpeg", "width": 250, "height": 250 } }, Snell Expires October 21, 2014 [Page 7] Internet-Draft ActivityStreams April 2014 "target": { "objectType": { "id": "http://example.org/PhotoAlbum", "displayName": "Photo-Album" }, "id": "urn:example.org:album:abc123", "url": "http://example.org/album/", "displayName": { "en": "Martin's Photo Album", "ga": "Grianghraif Mairtin" }, "image": { "url": "http://example.org/album/thumbnail.jpg", "mediaType": "image/jpeg", "width": 250, "height": 250 } } } ] } 3. Object Model 3.1. Object The following "core properties" apply to all JSON objects serialized within an Activity Stream document. Snell Expires October 21, 2014 [Page 8] Internet-Draft ActivityStreams April 2014 +-------------+---------------+-------------------------------------+ | Property | Value | Description | +-------------+---------------+-------------------------------------+ | id | IRI | Provides a permanent, universally | | | | unique identifier for the object in | | | | the form of an absolute IRI | | | | [RFC3987]. Objects SHOULD contain | | | | a single "id" property. If an | | | | object does not contain an "id" | | | | property, consumers MAY use the | | | | value of the "url" property as a | | | | less-reliable, non-unique | | | | identifier. | | objectType | Type value | Identifies the type of object. An | | | (Section 3.3) | object MAY contain a "objectType" | | | | property whose value is a Type | | | | value (Section 3.3). If no | | | | "objectType" property is specified, | | | | the object has no specific type. | | language | [RFC5646] | Establishes the default language | | | Language Tag | assumed for human-readable, | | | | natural-language metadata values | | | | included in the object. An object | | | | MAY contain a "language" property | | | | whose value MUST be a [RFC5646] | | | | Language-Tag. | | displayName | Natural | A simple human-readable, plain-text | | | Language | name for the object. HTML markup | | | value | MUST NOT be included. An object MAY | | | (Section 3.2) | contain a "displayName" property. | | | | If the object does not specify a | | | | "objectType" property, the object | | | | SHOULD specify a "displayName". | | url | Link (Section | A Link (Section 3.4) value | | | 3.4) value | describing a resource that provides | | | | a representation of the object. An | | | | object MAY contain a "url" | | | | property. | +-------------+---------------+-------------------------------------+ 3.2. Natural Language Values Natural Language values represent human-readable character sequences in one or more languages. They are expressed as either (1) a single JSON string or (2) a JSON dictionary mapping [RFC5646] Language-Tags to localized, equivalent translations of the same string value. Snell Expires October 21, 2014 [Page 9] Internet-Draft ActivityStreams April 2014 For instance, the "displayName" property in all objects is a Natural Language value. A single String value using the default language: { "language": "en", "displayName": "This is the title" } Multiple, language-specific values: { "displayName": { "en": "This is the title", "fr": "C'est le titre", "sp": "Este es el titulo" } } Each key in the JSON dictionary MUST be an [RFC5646] Language Tag. The associated values MUST be Strings. 3.3. Type Values Type values represent references to or descriptions of an abstract type. They are expressed as either: (1) a String conforming to either the "isegment-nz-nc" or "IRI" productions in [RFC3987] or (2) an Object (Section 3.1). When represented as a String, the use of relative references other than a simple name is not allowed. When represented as an Object, the "id" property MUST be specified. Within the Activity Streams 2.0, Type values are used only by the "objectType" and "verb" properties. Object type as a simple name (isegment-nz-nc): { "objectType": "person", "displayName": "John" } Object type as an absolute IRI: { "objectType": "http://example.org/Person", "displayName": "John" } Snell Expires October 21, 2014 [Page 10] Internet-Draft ActivityStreams April 2014 Object type as an object: { "objectType": { "id": "http://example.org/Person", "displayName": "Person" }, "displayName": "John" } Because the second and third examples above each specify "http:// example.org/Person", the two examples are considered to specify the same type. Verb as a simple name (isegment-nz-nc): { "verb": "post", "actor": "acct:john.doe@example.org", "object": "http://example.org/123" } Verb as an absolute IRI: { "verb": "http://example.com/Upload", "actor": "acct:john.doe@example.org", "object": "http://example.org/123" } Verb as an object: { "verb": { "id": "http://example.com/Upload", "displayName": "Upload" }, "actor": "acct:john.doe@example.org", "object": "http://example.org/123" } Allowing verbs and object types to be represented as objects rather than simple names or IRIs is intended to simplify the use of extensions that an implementation might not have encountered previously. The object properties provide additional information and metadata about the new verb or object type. Snell Expires October 21, 2014 [Page 11] Internet-Draft ActivityStreams April 2014 It is important to note that because the "id" property is strictly limited to absolute IRI values, the object representation cannot be used to describe types with simple names. 3.4. Link Values Link values represent references to other objects and resources. They are expressed as either: (1) a String containing an absolute or relative IRI, (2) an Object (Section 3.1), or (3) a JSON Array containing a mixture of IRIs or Objects (Section 3.1). Link values are closely related to the conceptual model of Links as established in [RFC5988]. For example, as defined previously, all objects (Section 3.1) can contain an "image" property whose value describes a graphical representation of the containing object. This property will typically be used to provide the URL to a JPEG, GIF or PNG type resource that can be displayed to the user. Any given object might have multiple such visual representations -- multiple screenshots, for instance, or the same image at different resolutions. Using Link values, there are essentially three ways of describing such references. To reference a single image without any additional metadata, the link value can be expressed as a simple JSON string containing an absolute or relative IRI: { "objectType": "application", "id": "http://example.org/application/123", "displayName": "My Application", "image": "http://example.org/application/123.png" } Alternatively, if additional metadata is required, the link can be expressed as an object containing the url property. { "objectType": "application", "id": "http://example.org/application/123", "displayName": "My Application", "image": { "url": "http://example.org/application/123.png", "mediaType": "image/png", "height": 320, "width": 320 } } Snell Expires October 21, 2014 [Page 12] Internet-Draft ActivityStreams April 2014 If more than one link value is to be expressed, A JSON Array with a mix of string and object elements can be used: { "objectType": "application", "id": "http://example.org/application/123", "displayName": "My Application", "image": [ "http://example.org/application/abc.gif", { "url": "http://example.org/application/123.png", "mediaType": "image/png", "height": 320, "width": 320 } ] } Individual items contained in such an array are independent of the others and no significance is given to the ordering of those items. RFC 5988 defines that all Links have a "link relation" that describes the contextual purpose of the link. Within an object (Section 3.1), in the absence of a specific "rel" property within the link object itself, the name of the property whose value is a link serves as the "link relation". Any valid link relation value, as defined by RFC 5988, can be used as a property with a link value in any Activity Streams object, except where the link relation might conflict with any other property defined by this specification. In the following example, two separate links are provided. The link relation of the first is "image", while the link relation of the second is "preview". Both links, however, can be used as alternative visual representations of the "application" object. { "objectType": "application", "image": [ "http://example.org/foo.jpg", { "url": "http://example.org/screens/1.jpg", "rel": "preview", "mediaType": "image/jpeg" } ] } Snell Expires October 21, 2014 [Page 13] Internet-Draft ActivityStreams April 2014 When an object (Section 3.1) is used to represent a Link value, the following additional properties MAY be used: +-----------+---------------+---------------------------------------+ | Property | Value | Description | +-----------+---------------+---------------------------------------+ | rel | RFC 5988 Link | The RFC 5988 Link Relation associated | | | Relation | with this link value. If absent, the | | | | name of the property is assumed to | | | | specify the link relation. | | mediaType | MIME Media | The MIME media type of the resource | | | Type | being referenced. | +-----------+---------------+---------------------------------------+ 3.5. Activity Activity objects are specializations of the base Object (Section 3.1) type that provide metadata about potential or completed actions. Within an Activity object, the "verb" property is used to identify the type of activity. All existing verb definitions used in JSON Activity Streams 1.0 implementations can continue to be used and retain their existing semantics. If the "verb" is not specified, the "objectType" property MAY be used as an alternative means of determining the activity type. Activity objects extend the core object (Section 3.1) definition with the following additional, optional properties: +-------------+---------------+-------------------------------------+ | Property | Value | Description | +-------------+---------------+-------------------------------------+ | verb | Type value | Identifies the type of activity. An | | | (Section 3.3) | activity SHOULD contain a "verb" | | | | property whose value is a Type | | | | value (Section 3.3). If the "verb" | | | | property is not specified, the | | | | activity MUST contain a | | | | "objectType" property. | | actor | Link (Section | Describes one or more entities that | | | 3.4) value | either peformed or are expected to | | | | perform the activity. | | object | Link (Section | Describes the direct object of the | | | 3.4) value | activity. For instance, in the | | | | activity, "John saved a movie to | | | | his wishlist", the object of the | | | | activity is "movie". An activity | | | | SHOULD contain an "object" | Snell Expires October 21, 2014 [Page 14] Internet-Draft ActivityStreams April 2014 | | | property. If the "object" property | | | | is not contained, the primary | | | | object of the activity MAY be | | | | implied by context. | | target | Link (Section | Describes the indirect object of | | | 3.4) value | the activity. The precise meaning | | | | of the activity's target is | | | | dependent on the activities "verb", | | | | but will often be the object the | | | | English preposition "to". For | | | | instance, in the activity, "John | | | | saved a movie to his wishlist", the | | | | target of the activity is | | | | "wishlist". The activity target | | | | MUST NOT be used to identify an | | | | indirect object that is not a | | | | target of the activity. | | result | Link (Section | Describes the result of the | | | 3.4) value | activity. For instance, if a | | | | particular action results in the | | | | creation of a new resource, the | | | | "result" property can be used to | | | | describe that new resource. | | instrument | Link (Section | An optional Link Value that | | | 3.4) value | describes one or more objects used | | | | to perform the action. For | | | | instance, in the activity, "Sally | | | | played music with a piano", the | | | | instrument of the activity is the | | | | "piano". | | participant | Link (Section | An optional Link Value that | | | 3.4) value | describes one or more additional | | | | actors that have or will indirectly | | | | participate in the activity. For | | | | instance, in the Activity, "Sally | | | | went to the movies with Joe", Sally | | | | is the primary "actor" while Joe is | | | | a "participant". | | priority | Decimal | An indicator of the relative | | | Number | priority or importance that the | | | between 0.00 | creator of an activity considers | | | and 1.00 | the it to have. Represented as a | | | | numeric decimal between 0.00 and | | | | 1.00, with two decimal places of | | | | precision. If the property is | | | | omitted or set to null, the | | | | assumption is that a default | | | | priority can be assumed. The value | Snell Expires October 21, 2014 [Page 15] Internet-Draft ActivityStreams April 2014 | | | 0.00 represents the lowest possible | | | | priority while 1.00 represents the | | | | highest. | | status | One of | An optional, explicit indicator of | | | "active", | the current status of the Activity. | | | "canceled", | "active" indicates that the | | | "completed", | activity is ongoing; "canceled" | | | "pending", | indicates that the activity has | | | "tentative", | been aborted; "completed" indicates | | | or "voided" | that the activity concluded; | | | | "pending" indicates that the | | | | activity is expected to begin; | | | | "tentative" indicates that the | | | | activity has been proposed; and | | | | "voided" indicates that the | | | | activity statement has been | | | | retracted or should be considered | | | | invalid. | +-------------+---------------+-------------------------------------+ 3.5.1. Considerations on the use of "priority" The presence of the "priority" property does not impose any specific processing or display requirements on the part of any entity consuming the activity. Expressing the value as a range of numeric decimal values is intended to provide the greatest level of flexibility in the expression and consumption of prioritization detail. It is expected that implementors consuming activity objects containing "priority" will utilize and expose the additional information in a number of different ways depending on the unique requirements of each application use case. Many existing systems do not represent priority values as numeric ranges. Such systems might use fixed, labeled brackets such as "low", "normal" and "high" or "urgent". Similar mechanisms can be established, by convention, when using the "priority" property. In typical use, it is RECOMMENDED that implementations wishing to work with such defined categories treat "priority" property values in the range 0.00 to 0.25 as "low" priority; values greater than 0.25 to 0.75 as "normal" priority; and values greater than 0.75 to 1.00 as "high" priority. Specific implementations are free to establish alternative conventions for the grouping of priority values with the caveat that such conventions likely will not be understood by all implementations. Snell Expires October 21, 2014 [Page 16] Internet-Draft ActivityStreams April 2014 3.5.2. Audience Targeting Properties Every Activity has both a Primary and Secondary audience. The Primary audience consists of those entities either directly involved in the performance of the activity or who "own" the objects involved. The Secondary audience consists of the collection of entities sharing an interest in the activity but who are not directly involved (e.g. "followers"). For instance, suppose a social network of three individuals: Bob, Joe and Jane. Bob and Joe are each friends with Jane but not friends with one another. Bob has chosen to "follow" activities for which Jane is directly involved. Jane shares a file with Joe. In this example, Jane and Joe are each directly involved in the file sharing activity and together make up the Primary Audience for that event. Bob, having an interest in activities involving Jane, is the Secondary Audience. Knowing this, a system that produces or consumes the activity can intelligently notify each person of the event. While there are means, based on the verb, actor, object and target of the activity, to infer the primary audience for many types of activities, those do not work in every case and do not provide a means of identifying the secondary audience. The "to", "cc", "bto" and "bcc" properties MAY be used within an Activity to explicitly identify the Primary and Secondary audiences. +-----------+--------------------+----------------------------------+ | Property | Value | Description | +-----------+--------------------+----------------------------------+ | to | Link (Section 3.4) | Specifies the public primary | | | value | audience. | | cc | Link (Section 3.4) | Specifies the public secondary | | | value | audience. | | bto | Link (Section 3.4) | Specifies the private primary | | | value | audience. | | bcc | Link (Section 3.4) | Specifies the private secondary | | | value | audience. | +-----------+--------------------+----------------------------------+ The prototypical use case for an Activity containing these properties is the publication and redistribution of Activities through an intermediary. That is, an event source generates the activity and publishes it to the intermediary which determines a subset of events to display to specific individual users or groups. Such a determination can be made, in part, by identifying the Primary and Secondary Audiences for each activity. Snell Expires October 21, 2014 [Page 17] Internet-Draft ActivityStreams April 2014 When the event source generates the activity and specifies values for the to and cc fields, the intermediary SHOULD redistribute that event with the values of those fields intact, allowing any processor to see who the activity has been targeted to. This is precisely the same model used by the to and cc fields in email systems. There are situations, however, in which disclosing the identity of specific members of the audience may be inappropriate. For instance, a user may not wish to let other users know that they are interested in various topics, individuals or types of events. To support this option, an event source generating an activity MAY use the "bto" and "bcc" properties to list entities to whom the activity should be privately targeted. When an intermediary receives an activity containing these properties, it MUST remove those values prior to redistributing the activity. The intent is that systems MUST consider entities listed within the "bto" and "bcc" properties as part of the Primary and Second audience but MUST NOT disclose that fact to any other party. Audience targeting information included within an Activity only describes the intent of the activity creator. With clear exception given to the appropriate handling of "bto" and "bcc", this specification leaves it up to implementations to determine how the audience targeting information is used. 3.6. Additional Object Properties The following "additional properties" MAY be used with any JSON Object serialized within an Activity Stream document. +-------------+-----------------+-----------------------------------+ | Property | Value | Description | +-------------+-----------------+-----------------------------------+ | alias | IRI | Provides a contextually | | | | meaningful alternative label for | | | | the object in addition to the | | | | "id". For instance, within some | | | | systems, groups can be identified | | | | both by a unique global ID and a | | | | more "human-friendly" label such | | | | as "@friends" or "@network". The | | | | value of the "alias" property | | | | MUST match either the "isegment- | | | | nz-nc" or the "IRI" production in | | | | [RFC3987]. The use of a relative | | | | reference other than a simple | | | | name is not allowed. | | attachments | Link (Section | A Link (Section 3.4) value | Snell Expires October 21, 2014 [Page 18] Internet-Draft ActivityStreams April 2014 | | 3.4) value | referencing one or more objects | | | | associated with the containing | | | | object. These are similiar in | | | | concept to files attached to an | | | | email message. | | author | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing one or more entity | | | | that created or authored the | | | | object. | | content | Natural | A Natural-language description of | | | Language value | the object encoded as a single | | | (Section 3.2) | JSON String containing HTML | | | | markup. Visual elements such as | | | | thumbnail images MAY be included. | | duplicates | Link (Section | A Link (Section 3.4)value | | | 3.4) value | referencing one or more objects | | | | that are semantically equivalent | | | | to this object or duplicate this | | | | objects content. An object SHOULD | | | | contain a "duplicates" property | | | | when there are known objects, | | | | possibly in a different system, | | | | that are semantically equivalent | | | | or duplicate the content. | | icon | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing one or more visual, | | | | graphic representations of the | | | | object, intended for human | | | | consumption. The visual element | | | | SHOULD have an aspect ratio of | | | | one (horizontal) to one | | | | (vertical) and SHOULD be suitable | | | | for presentation at a small size. | | image | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing one or more visual, | | | | graphic represenations of the | | | | object. Unlike the "icon" | | | | property, there are no aspect | | | | ratio or display restrictions. | | location | Link (Section | A Link (Section 3.4) value | | | 3.4) value | describing one or more physical | | | | or virtual locations associated | | | | with which the object. | | published | [RFC3339] date- | The date and time at which the | | | time | object was published. | | generator | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing the application that | | | | generated the object. | Snell Expires October 21, 2014 [Page 19] Internet-Draft ActivityStreams April 2014 | provider | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing the application that | | | | published the object. Note that | | | | this is not necessarily the same | | | | entity that generated the object. | | summary | Natural | A Natural-language summarization | | | Language value | of the object encoded as a single | | | (Section 3.2) | JSON String containing a fragment | | | | of HTML markup. Visual elements | | | | such as thumbnail images can be | | | | included. | | updated | [RFC3339] date- | The date and time at which a | | | time | previously published object has | | | | been modified. | | startTime | [RFC3339] date- | A date-time describing the actual | | | time | or expected starting time of the | | | | object. When used within an | | | | Activity object, for instance, | | | | the "startTime" specifies the | | | | moment the activity began or is | | | | scheduled to begin. | | endTime | [RFC3339] date- | A date-time describing the actual | | | time | or expected ending time of the | | | | object. When used within an | | | | Activity object, for instance, | | | | the "endTime" specifies the | | | | moment the activity concluded or | | | | is scheduled to conclude. | | rating | Decimal Number | A quality rating expressed as a | | | between 1.0 and | number between 1.0 and 5.0 | | | 5.0 | (inclusive) with one decimal | | | | place of precision. | | tags | Link (Section | A Link (Section 3.4) value | | | 3.4) value | referencing one or more resources | | | | that are loosely associated with | | | | the containing object. The | | | | "tags" and "attachments" | | | | properties differ from one | | | | another in that the "tags" | | | | property asserts "association by | | | | reference" while "attachments" | | | | asserts "association by | | | | enclosure". | | title | Natural | A Natural-language title for the | | | Language | object expressed as a fragment of | | | (Section 3.2) | HTML markup. The "title" and | | | value | "displayName" properties are | | | | closely related and overlap in | Snell Expires October 21, 2014 [Page 20] Internet-Draft ActivityStreams April 2014 | | | function with the key difference | | | | being that "title" is permitted | | | | to contain HTML markup, while | | | | "displayName" is not. | | duration | Integer or | When the object describes a time- | | | [RFC3339] | based resource, such as audio or | | | duration | video, the "duration" property | | | | indicates the approximate | | | | duration of time expressed as an | | | | either an RFC 3339 "duration" | | | | (e.g. a duration of 5 seconds is | | | | represented as "PT5S") or as a | | | | non-negative integer specifying | | | | the duration in seconds. | | height | Integer | When the object describes a | | | | visual resource, such as an | | | | image, video or embeddable HTML | | | | page, the "height" property | | | | indicates the recommended display | | | | height in pixels. | | width | Integer | When the object describes a | | | | visual resource, such as an | | | | image, video or embeddable HTML | | | | page, the "width" property | | | | indicates the recommended display | | | | width in pixels. | | inReplyTo | Link (Section | A Link (Section 3.4) value | | | 3.4) value | identifying one or more other | | | | objects to which the containing | | | | object can be considered a | | | | response. | | actions | Action (Section | An optional Action (Section | | | 3.6.1) value | 3.6.1) value that describes | | | | potential activities that can be | | | | performed with the object. | | scope | Link (Section | A Link (Section 3.4) value | | | 3.4) value | identifying one or more resources | | | | that define the total population | | | | of entities for which the object | | | | is considered to be relevant. | +-------------+-----------------+-----------------------------------+ 3.6.1. Action Values The "actions" property on an Activity Streams object is used to describe the kinds of activities that can be taken with regards to the object. The value is expressed as a JSON dictionary mapping Snell Expires October 21, 2014 [Page 21] Internet-Draft ActivityStreams April 2014 verbs to Link (Section 3.4) values referencing resources or objects that can be used to carry out those verbs. For instance, a hypothetical object with "video" as the objectType might have "watch", "share" and "embed" as potential actions: { "objectType": "video", "id": "http://example.org/cats.mpg", "actions": { "watch": "movie://example.org/cats.mpg", "share": { "objectType": "service", "displayName": "My Sharing Service", "url": "http://example.net/share" }, "embed": [ "http://example.org/gadgets/video.xml?v=cats.mpg", { "objectType": "inline-html", "content": "