OpenSocial Social Data Specification 2.5.1

Domain name examples use RFC2606.

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. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements.

The grammatical rules in this document are to be interpreted as described in RFC2234 (Augmented Backus-Naur Form). The following constructs are introduced in this document to augment RFC2234: Elements enclosed in braces (squiggly brackets) are treated as a single, UNORDERED element. Its contents may occur in any order. Hence: {elem foo} bar would match (elem foo bar) and (foo elem bar). NOTE: Specifying alternatives is quite different from specifying set grouping. Alternatives indicate the matching of exactly one (sub-)rule out of the total grouping. The set mechanism indicates the matching of a string which contains all of the elements within the group; however the elements may occur in any order. A construct "#" is defined, similar to "*", for defining lists of elements. The full form is "<n>#<m>element" indicating at least <n> and at most <m> elements, each separated by one or more commas (",") and OPTIONAL linear white space (LWS). This makes the usual form of lists very easy; a rule such as ( *LWS element *( *LWS "," *LWS element )) can be shown as 1#element Wherever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "(element), , (element) " is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element MUST be present. Default values are 0 and infinity so that "#element" allows any number, including zero; "1#element" requires at least one; and "1#2element" allows one or two. A construct "&" is defined, similar to "#", which uses an ampersand (&) instead of commas, and MUST NOT include linear white space between elements. The grammar described by this specification is word-based. Except where noted otherwise, linear white space (LWS) can be included between any two adjacent words (token or quoted-string), and between adjacent words and separators, without changing the interpretation of a field. At least one delimiter (LWS and/or separators) MUST exist between any two tokens, since they would otherwise be interpreted as a single token.

The following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by CHAR = UPALPHA = LOALPHA = ALPHA = UPALPHA / LOALPHA DIGIT = CTL = CR = LF = SP = HT = <"> = CRLF = CR LF LWS = [CRLF] 1*( SP / HT ) TEXT = COMMA = ]]>

Primary Social Data objects represent objects that are directly addressable through top level API calls, such as osapi, RPC, REST and Pipelining tags.

An OpenSocial Activity represents a short summary or notification of a timestamped event, often with pointers for more information. Activities are rendered with a title and an optional activity body. The title and body may be set directly as strings when calling opensocial.newActivity. However, it is usually beneficial to create activities using Message Templates for the title and body. Users have many activities in their activity streams, and containers may not show every activity that is visible to a user. To help display large numbers of activities, containers summarize a list of activities from a given source to a single entry. You can provide Activity Summaries to customize the text shown when multiple activities are summarized. If no customization is provided, a container may ignore your activities altogether or provide default text such as "Bob changed his status message + 20 other events like this." Activity Summaries always summarize around a specific key in a key/value pair. This is so that the summary can say something concrete (this is clearer in the example below). Other variables have synthetic "Count" variables created with the total number of items summarized. Message ID of the summary is the message ID of the main template + ":" + the data key Example summaries:

<messagebundle> <msg name="LISTEN_TO_THIS_SONG:Artist"> ${Subject.Count} of your friends have suggested listening to songs by ${Artist}! </msg> <msg name="LISTEN_TO_THIS_SONG:Song"> ${Subject.Count} of your friends have suggested listening to ${Song} !</msg> <msg name="LISTEN_TO_THIS_SONG:Subject"> ${Subject.DisplayName} has recommended ${Song.Count} songs to you. </msg> </messagebundle> Field Name Field Type Description appId Object-Id Specifying the application that this activity is associated with. body string Specifying an optional expanded version of an activity. Bodies may only have the following HTML tags: , <a>, . The container may ignore this formatting when rendering the activity. bodyId Object-Id Specifying the body template message ID in the gadget spec. externalId Object-Id An optional ID generated by the posting application. id Object-Id An ID that is permanently associated with this activity. mediaItems Array<MediaItem> Any photos, videos, or images that should be associated with the activity. Higher priority ones are higher in the list. postedTime string Specifying the time at which this activity took place in milliseconds since the epoch. priority number A number between 0 and 1 representing the relative priority of this activity in relation to other activities from the same source. streamFaviconUrl string Specifying the URL for the stream's favicon. streamSourceUrl string Specifying the stream's source URL. streamTitle string Specifing the title of the stream. streamUrl string Specifying the stream's URL. templateParams A map of custom key/value pairs associated with this activity. These are used for evaluation in templates. The data has type Map<String, Object>. The object may be either a String or an opensocial.Person. When passing in a person with key PersonKey, can use the following replacement variables in the template: PersonKey.DisplayName - Display name for the person PersonKey.ProfileUrl. URL of the person's profile PersonKey.Id - The ID of the person PersonKey - Container may replace with DisplayName, but may also optionally link to the user. title string Specifying the primary text of an activity. Titles may only have the following HTML tags: , <a>, . The container may ignore this formatting when rendering the activity. url string Specifying the URL that represents this activity. userId Object-Id ID of the user who this activity is for. A minimal Activity example:

application/json representation: { "id" : "http://example.org/activities/example.org:87ead8dead6beef/self/af3778", "title" : "<a href=\"foo\">some activity</a>", "updated" : "2008-02-20T23:35:37.266Z", "body" : "Some details for some activity", "bodyId" : "383777272", "url" : "http://api.example.org/activity/feeds/.../af3778", "userId" : "example.org:34KJDCSKJN2HHF0DW20394" }

application/xml representation: <activity xmlns="http://ns.opensocial.org/2008/opensocial"> <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id> <title><a href=\"foo\">some activity</a></title> <updated>2008-02-20T23:35:37.266Z</updated> <body>Some details for some activity</body> <bodyId>383777272</bodyId> <url>http://api.example.org/activity/feeds/.../af3778</url> <userId>example.org:34KJDCSKJN2HHF0DW20394</userId> </activity> Activities have extensive Atom hoisting rules to ensure maximum compatibility with standard feed processing code: atom:entry/atom:title aliases "title" atom:entry/atom:summary aliases "body" atom:entry/atom:link@rel="self" aliases "url" atom:entry/atom:icon aliases "faviconUrl" atom:entry/atom:source/atom:title aliases "streamTitle" atom:entry/atom:source/atom:link@rel="self" aliases "streamUrl" atom:entry/atom:generator/atom:uri aliases "appId" atom:entry/atom:author/atom:uri aliases "userId"

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id> <title>some activity</title> <updated>2008-02-20T23:35:37.266Z</updated> <author> <uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri> <name>John Smith</name> </author> <link rel="self" type="application/atom+xml" href="http://api.example.org/activity/feeds/.../af3778" /> <link rel="alternate" type="application/json" href="http://example.org/activities/example.org:87ead8dead6beef/self/af3778" /> <content type="application/xml"> <activity xmlns="http://ns.opensocial.org/2008/opensocial"> <id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id> <title type="html"><a href=\"foo\">some activity</a></title> <updated>2008-02-20T23:35:37.266Z</updated> <body>Some details for some activity</body> <bodyId>383777272</bodyId> <url>http://api.example.org/activity/feeds/.../af3778</url> <userId>example.org:34KJDCSKJN2HHF0DW20394</userId> </activity> </content> </entry> Note: The title field is a string that may only have the following html tags: , , <a>, . The container may ignore this formatting when rendering the activity.

Discussion As a person's actions become increasingly distributed, it is important to achieve a level of interoperability betweent the systems that they interact with. The Activity Streams specification has been incorporated in order to improve interoperability with other systems that may not be based on OpenSocial. This will provide implementors and developers a wide range of options for incorporating social data within their applications. OpenSocial introduces support for the Activity Streams 1.0 specification following the pattern of support for Portable Contacts. The data structures for ActivityObject and ActivityEntry are brought into Social-Data, an new service is introduced in Social-API-Server, and application APIs are defined in Social-Gadget. In the case of Activity Streams, there are several constructs that exist in OpenSocial that will be present in the activity stream information that flows within a container and between external Activity Stream endpoints. Included in the definition of the Activity Stream data structures in this specification are mappings to the existing OpenSocial objects.

In its simplest form, an activity consists of an actor, a verb, an an object, and a target. It tells the story of a person performing an action on or with an object -- "Geraldine posted a photo to her album" or "John shared a video". Field Name Field Type Description actor ActivityObject Describes the entity that performed the activity. An activity MUST contain one actor property whose value is a single ActivityObject. content string Natural-language description of the activity encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An activity MAY contain a content property. generator ActivityObject Describes the application that generated the activity. An activity MAY contain a generator property whose value is a single ActivityObject. OpenSocial note: If an OpenSocial application created the Activity Entry, this value SHOULD be the appId. icon MediaLink Description of a resource providing a visual representation of the object, intended for human consumption. The image SHOULD have an aspect ratio of one (horizontal) to one (vertical) and SHOULD be suitable for presentation at a small size. An activity MAY have an icon property. id string Provides a permanent, universally unique identifier for the activity in the form of an absolute IRI. An activity SHOULD contain a single id property. If an activity does not contain an id property, consumers MAY use the value of the url property as a less-reliable, non-unique identifier. OpenSocial note: The value of id MUST be the IRI form of the Global-Id. object ActivityObject Describes the primary object of the 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 property whose value is a single Object. If the object property is not contained, the primary object of the activity MAY be implied by context. published string The date and time at which the activity was published. An activity MUST contain a published property. provider ActivityObject Describes the application that published the activity. Note that this is not necessarily the same entity that generated the activity. An activity MAY contain a provider property whose value is a single ActivityObject. OpenSocial note: The provider SHOULD be URL of the domain part of the Global-Id plus the OpenSocial service. Example: http://mySocialNetwork.com/activitystreams target ActivityObject Describes the target of 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 identity an indirect object that is not a target of the activity. An activity MAY contain a target property whose value is a single ActivityObject. title string Natural-language title or headline for the activity encoded as a single JSON String containing HTML markup. An activity MAY contain a title property. updated string The date and time at which a previously published activity has been modified. An Activity MAY contain an updated property. url string An IRI identifying a resource providing an HTML representation of the activity. An activity MAY contain a url property. verb string Identifies the action that the activity describes. An activity SHOULD contain a verb property whose value is a JSON String that is non-empty and matches either the "isegment-nz-nc" or the "IRI" production in RFC3339. Note that the use of a relative reference other than a simple name is not allowed. If the verb is not specified, or if the value is null, the verb is assumed to be "post".

OpenSocial adds an additional fields to the data model, for example "actionLinks". Because these are extensions, they are contained in an enclosing namespace, "openSocial". OpenSocial defined extensions to the Activity Streams data model are defined below. Field Name Field Type Description actionLinks Array<ActionLink> An "openSocial" namespaced array of actionLinks associated with this Activity. deliverTo: Array< Global-Id> Many social business systems incorporate the idea that an activity may not be public. By including the "deliverTo:" field, a specific user(s) will receive the activity. The Activity MUST be delivered to the recipients specified in the deliverTo: Array embed Embedded Experience An "openSocial" namespaced Embedded Experience data model associated with this Activity. Discussion Discussion Discussion

A complete ActivityEntry example

application/json representation: { provider: { url: "http://example.org/activity-stream" }, object: { summary: "Photo posted", image: { height: 250, width: 250, url: "http://example.org/album/my_fluffy_cat_thumb.jpg" }, downstreamDuplicates: [ "downstream1", "downstream2" ], url: "http://example.org/album/my_fluffy_cat.jpg", id: "object2", upstreamDuplicates: [ "upstream1", "upstream2" ], attachments: [ { id: "attachment1", objectType: "attachment" }, { id: "attachment2", objectType: "attachment" } ], objectType: "photo" }, actor: { image: { height: 250, width: 250, url: "http://example.org/martin/image" }, url: "http://example.org/john", id: "john.doe", displayName: "John Doe", objectType: "person" }, id: "activity2", title: "John posted a new video to his album.", verb: "post", target: { image: { height: 250, width: 250, url: "http://example.org/album/thumbnail.jpg" }, url: "http://example.org/album/", id: "target2", displayName: "John's Photo Album", objectType: "photo-album" }, generator: { url: "http://example.org/activities-app" }, published: "2011-02-10T15:04:55Z", openSocial: { actionLinks:[{ caption: "Add Friend", target: "http://example.org/friends/jane.doe", httpVerb: "POST" }] } }

application/xml representation: <activityEntry xmlns="http://ns.opensocial.org/2008/opensocial"> <actor> <displayName>John Doe</displayName> <id>john.doe</id> <image> <height>250</height> <url>http://example.org/john/image</url> <width>250</width> </image> <objectType>person</objectType> <url>http://example.org/john</url> </actor> <generator> <url>http://example.org/activities-app</url> </generator> <id>activity2</id> <object> <attachments> <object> <id>attachment1</id> <objectType>attachment</objectType> </object> <object> <id>attachment2</id> <objectType>attachment</objectType> </object> </attachments> <downstreamDuplicate>downstream1</downstreamDuplicate> <downstreamDuplicate>downstream2</downstreamDuplicate> <id>object2</id> <image> <height>250</height> <url>http://example.org/album/my_fluffy_cat_thumb.jpg</url> <width>250</width> </image> <objectType>photo</objectType> <summary>Photo posted</summary> <upstreamDuplicate>upstream1</upstreamDuplicate> <upstreamDuplicate>upstream2</upstreamDuplicate> <url>http://example.org/album/my_fluffy_cat.jpg</url> </object> <provider> <url>http://example.org/activity-stream</url> </provider> <published>2011-02-10T15:04:55Z</published> <target> <displayName>John's Photo Album</displayName> <id>target2</id> <image> <height>250</height> <url>http://example.org/album/thumbnail.jpg</url> <width>250</width> </image> <objectType>photo-album</objectType> <url>http://example.org/album/</url> </target> <title>John posted a new video to his album.</title> <verb>post</verb> </activityEntry>

OpenSocial defines a data store that applications can use to read and write user-specific data. This data store can be read by anyone who can see the gadget, but only the VIEWER's data is writable. The keys that developers specify to index this data must only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-). Since application data is often created based on user inputs, OpenSocial containers perform automatic HTML escaping of all application data. However, developers have the option of turning off this escaping by setting the escapeType parameter on newFetchPersonAppData and getField calls. Because of the potential for abuse, containers MAY implement quotas or rate limits to preserve their disk space. Field Name Field Type Description key string A unique value with respect to the context it is being stored within (typically a person). value string An arbitary string.

The first example is of a collection of key/value pairs for a particular application/user pair:

application/json representation: { "pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" }

application/xml representation: <appData xmlns="http://ns.opensocial.org/2008/opensocial"> <entry> <key>pokes</key> <value>3</value> </entry> <entry> <key>last_poke</key> <value>2008-02-13T18:30:02Z</value> </entry> </appData>

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <content type="application/xml"> <appData xmlns="http://ns.opensocial.org/2008/opensocial"> <pokes>3</pokes> <last_poke>2008-02-13T18:30:02Z</last_poke> </appData> </content> <title/> <updated>2003-12-13T18:30:02Z</updated> <author> <url>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</url> <name>John Smith</name> </author> <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id> </entry>

In this example, a client has requested a collection of data that spans multiple users. The result is a collection which, by default, is given a special default JSON representation as a mapping from users to their data.

application/json representation: { "entry" : { "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" }, "example.org:58UIDCSIOP233FDKK3HD44" : {"pokes" : 2, "last_poke" : "2007-12-16T18:30:02Z" } } }

application/xml representation: <entry> <appData xmlns="http://ns.opensocial.org/2008/opensocial"> <personId>example.org:34KJDCSKJN2HHF0DW20394</personId> <entry> <key>pokes</key> <value>3</value> </entry> <entry> <key>last_poke</key> <value>2008-02-13T18:30:02Z</value> </entry> </appData> <appData xmlns="http://ns.opensocial.org/2008/opensocial"> <personId>example.org:58UIDCSIOP233FDKK3HD44</personId> <entry> <key>pokes</key> <value>2</value> </entry> <entry> <key>last_poke</key> <value>2007-12-16T18:30:02Z</value> </entry> </appData> </entry>

application/atom+xml representation: <feed xmlns="http://www.w3.org/2005/Atom> <id>...</id> <title>...</title> <entry> <content type="text/xml"> <appData> <pokes>3</pokes> <last_poke>"2008-02-13T18:30:02Z"</last_poke> </appData> </content> <title/> <updated>2008-02-13T18:30:02Z</updated> <author><url>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</url></author> <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id> </entry> <entry> <content type="text/xml"> <appData> <pokes>2</pokes> <last_poke>"2007-12-16T18:30:02Z"</last_poke> </appData> </content> <title/> <updated>2007-12-16T18:30:02Z</updated> <author><url>uurn:guid:example.org:58UIDCSIOP233FDKK3HD44</url></author> <id>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</id> </entry> </feed>

OpenSocial Groups are owned by people, and are used to tag or categorize people and their relationships. Each group has a display name, an identifier which is unique within the groups owned by that person, and a URI link. A group may be a private, invitation-only, public or a personal group used to organize friends. Field Name Field Type Description id Group-Id Unique ID for this group Required. title String Title of group Required. description String Description of group Optional. Discussion A Group example:

application/json representation: { "id" : "example.org:34KJDCSKJN2HHF0DW20394/friends", "title" : "Peeps", }

application/xml representation: <group xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394/friends</id> <title>Peeps</title> </group>

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <id>example.org:34KJDCSKJN2HHF0DW20394/friends</id> <title>Friends of John Smith</title> <updated>2008-03-15T10:00:00Z</updated> <author><name>John Smith</name></author> <link rel="alternate" type="application/json" href="http://example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends" /> <link rel="alternate" type="application/atom+xml" href="http://example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends?format=atom" /> <link rel="alternate" type="application/xml" href="http://example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends?format=xml" /> <content type="application/xml"> <group xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394/friends</id> <title>Peeps</title> </group> </entry>

Valid definitions for Message-Field are listed in the table below. Discussion Field Name Field Type Description appUrl string Identifies the application that generated this message. body string The main text of the message. HTML attributes are allowed and are sanitized by the container. bodyId string The main text of the message as a message template. Specifies the message ID to use in the gadget xml. collectionIds Array <string> Identifies the messages collection IDs this message is contained in. id string Unique ID for this message. inReplyTo string Message ID of a parent resource, use for threaded comments/messages. References the semantics of the Atom Threading model defined in rfc4685. URLs should be mapped to Atom <link rel="type" .../> recipients Array <string> Array of person IDs. replies Array <string> Array of message ids indicating responses to this message. References the semantics of the Atom Threading model defined in rfc4685. URLs should be mapped to Atom <link rel="type" .../> senderId string Id of person who sent the message. status string Status of the message. (NEW, READ, DELETED). timeSent Date UTC time message was sent. title string The title of the message. HTML attributes are allowed and are sanitized by the container. titleId string The title of the message as a message template. Specifies the message ID to use in the gadget xml. type string The type of the message. updated Date Last update for this message. urls Plural-Field <string> List of related URLs for this message. Supported URL types include 'alternate', alternate for for this mailbox (text/html being the most common). Discussion A Message example follows. For brevity, details of the 'sender' field, an OpenSocial Person, are omitted.

application/json representation { "id" : "http://example.org/inbox/message/{msgid}", "recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"], "sender" : "{ "id" : ... }", "title" : "You have a new messge from Joe", "titleId" : "541141091700", "body" : "Short message from Joe to some friend\/s", "bodyId" : "5491155811231", "type" : "privateMessage", "status" : "unread", "data" : "..." }

application/xml representation <message xmlns="http://ns.opensocial.org/2008/opensocial"> <id>http://example.org/inbox/message/{msgid}</id> <recipient>example.org:AD38B3886625AAF</recipient> <recipient>example.org:997638BAA6F25AD</recipient> <sender> <person>...</person> </sender> <title>You have a new messge from Joe</title> <titleId>541141091700</titleId> <updated>2008-09-29T23:35:37.266Z</updated> <body>Short message from Joe to some friend\/s</body> <bodyId>5491155811231</bodyId> <type>privateMessage</type> <status>unread</status> <data>...</data> </message>

application/atom+xml representation <entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"> <osapi:recipient>example.org:AD38B3886625AAF</osapi:recipient> <osapi:recipient>example.org:997638BAA6F25AD</osapi:recipient> <sender><person>...</person></sender> <title>You have a new message from Joe</title> <id>http://example.org/inbox/message/{msgid}</id> <link rel="alternate" href="http://app.example.org/inbox/message/{msgid}"/> <content>Short message from Joe to some friend/s</content> <status>UNREAD</status> <data>...</data> </entry> The recipient may also include a type identifier. The osapi:recipient supports two formats: For people: [container]:[identifier] Specifying a group or a person: [container]:[group|person]:[identifier]

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi"> <osapi:recipient>example.org:group:AD38B3886625AAF</osapi:recipient> <osapi:recipient>example.org:person:997638BAA6F25AD</osapi:recipient> <osapi:recipient>example.org:6221226</osapi:recipient> <title>You have an invitation from Joe</title> <id>{msgid}</id> <link rel="alternate" href="http://app.example.org/invites/{msgid}"/> <content>Click <a href="http://app.example.org/invites/{msgid}">here</a> to review your invitation.</content> </entry> The 'sender' field in the message representations is only needed when receiving a message with a GET request. It is not required when POSTING a new message as this information is represented by the {guid}. Using a Person for the sender field allows a gadget to present meaningful information about the message sender without requiring a separate request for this information. The 'data' field is used for information specific to the gadget that is sending or displaying the message. It may be omitted in most messages. An example is a message from a user asking to join a group. In the received message to the group's owner(s), the 'data' field could contain the JSON or XML representation of an OpenSocial Group.

Sample JSON for Message { "recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"], "title" : "You have an invitation from Joe", "body" : "Some content", "type" : "EMAIL" }

Each person returned MUST include the "id" and "name" fields with non-empty values, but all other fields are optional, and it is recognized that not all Service Providers are able to provide data for all the supported fields. The field list below is broad so that there is a standard field name available among Service Providers that do support any of these fields. Discussion There are two special Person objects that can be requested directly: the VIEWER and the OWNER. To understand the distinction, imagine you're checking out a coworker's profile on Orkut. In this case, you are the VIEWER and your coworker is the OWNER. It's also common to view your own profile, in which case you are both the VIEWER and the OWNER, and some applications may choose to handle this case differently. OpenSocial also provides for the case of anonymous viewing, where the gadget will not be able to access the VIEWER's information. Person = "{" "id :" User-ID "," "displayName :" string "," [ #Person-Field ] "}" OpenSocial defines many common attributes associated with a person and is aligned with the Portable Contacts specification. However, only display name and id are required and all others are optional. In practice, support for these fields varies greatly among containers. As OpenSocial continues to be adopted as an enterprise programming model, many of these fields are not appropriate based on the considerations of Human Resource guidelines. Discussion In an attempt to balance the needs of consumer vs corporate focused OpenSocial applications, and increase interoperability, the specification is refining attempting to provide clarity around attributes that are broadly applicable across both the consumer and enterprise domain, and those that are more appropriate for consumer oriented systems. The generally applicable field definitions for Person are listed in the table below. Field Name Field Type Description aboutMe string A general statement about the person. accounts Plural-Field <Account> An online account held by this Person. addresses Plural-Field <Address> A physical mailing address for this Person. alternateNames Plural-Field <Name> List of alternative names. These may include known aliases, maiden-names, nicknames, acceptable alternative forms of the same name (e.g. "James", "Jim", "Jimmy"), etc. appData Plural-Field <AppData> A collection of AppData keys and values. connected Boolean Boolean value indicating whether the user and this Person have established a bi-directionally asserted connection of some kind on the Service Provider's service. The value MUST be either true or false. The value MUST be true if and only if there is at least one value for the relationships field indicating that some type of bi-directional relationship exists, and is thus intended as a summary value for Consumers that aren't interested in the specific nature of that relationship. For traditional address books, in which a user stores information about other contacts without their explicit acknowledgment, or for services in which users choose to "follow" other users without requiring mutual consent, this value will always be false. DiscussionDiscussion contactPreference string Human-readable summarization of the Person's contact preferences. For instance, a person may choose to specify something along the lines of, "Please use instant messaging to contact me prior to calling." dn string This Person's X.500 'Distinguished Name' displayName string Required. The name of this Person, suitable for display to end-users. Each Person returned MUST include a non-empty displayName value. The name SHOULD be the full name of the Person being described if known (e.g. Cassandra Doll or Mrs. Cassandra Lynn Doll, Esq.), but MAY be a username or handle, if that is all that is available (e.g. doll). The value provided SHOULD be the primary textual label by which this Person is normally displayed by the Service Provider when presenting it to end-users. emails Plural-Field <string> E-mail address for this Person. The value SHOULD be canonicalized by the Service Provider, e.g.joseph@plaxo.com instead of joseph@PLAXO.COM. hasApp Boolean Indicating whether the user has application installed. id Object-Id Required. Unique identifier for the Person. ims Plural-Field <string> Instant messaging address for this Person. No official canonicalization rules exist for all instant messaging addresses, but Service Providers SHOULD remove all whitespace and convert the address to lowercase, if this is appropriate for the service this IM address is used for. Instead of the standard Canonical Values for type, this field defines the following Canonical Values to represent currently popular IM services: aim, gtalk, icq, xmpp,msn, skype, qq, and yahoo. location string name Name The broken-out components and fully formatted version of the person's real name. nativeName Name The broken-out components and fully formatted, native-language version of the person's real name. networkPresence Plural-Field <string> Person's current network status. Specified as one of: AWAY, CHAT, DND, OFFLINE, ONLINE OR XA. organizations Plural-Field <Organization> A current or past organizational affiliation of this Person. phoneNumbers Plural-Field <string> Phone number for this Person. No canonical value is assumed here. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values mobile, fax, and pager. photos Plural-Field <string> URL of a photo of this person. The value SHOULD be a canonicalized URL, and MUST point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a web page containing an image. Service Providers MAY return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists. Note that this field SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact. preferredName Name The broken-out components and fully formatted version of the person's preferred name. preferredUsername string The preferred username of this person on sites that ask for a username (e.g. jsmarr or daveman692). This field may be more useful for describing the owner (i.e. the value when /@me/@self is requested) than the user's person, e.g. Consumers MAY wish to use this value to pre-populate a username for this user when signing up for a new service. profileUrl string Person's profile URL, specified as a string. This URL must be fully qualified. Relative URLs will not work in gadgets. published Date The date this Person was first added to the user's address book or friends list (i.e. the creation date of this entry). The value MUST be a valid Date. relationships Plural-Field <string> A string value consisting in one or more relationship types that were established between the user and this person by the Service Provider, which MAY or MAY NOT have been bi-directionally confirmed. Values "friends", "followers" and "following" SHOULD be reserved and have the same meaning as the corresponding GroupId. Note that this field is a parallel set of category labels to the tags field, but tags are asserted by the user without acknowledgment by this Person. DiscussionDiscussion status string Person's status, headline or shoutout. tags Plural-Field <string> A user-defined category label for this person, e.g. "favorite" or "web20". These values SHOULD be case-insensitive, and there SHOULD NOT be multiple tags provided for a given person that differ only in case. Note that this field consists only of a string value. thumbnailUrlc> string Person's photo thumbnail URL, specified as a string. This URL must be fully qualified. Relative URLs will not work in gadgets. updated Date The most recent date the details of this Person were updated (i.e. the modified date of this entry). The value MUST be a valid Date. If this Person has never been modified since its initial creation, the value MUST be the same as the value of published. Note the updatedSince Query Parameter can be used to select only people whose updated value is equal to or more recent than a given Date. This enables Consumers to repeatedly access a user's data and only request newly added or updated contacts since the last access time. urls Plural-Field <string> URL of a web page relating to this Person. The value SHOULD be canonicalized by the Service Provider, e.g.http://josephsmarr.com/about/ instead of JOSEPHSMARR.COM/about/. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values blog and profile. utcOffset Date-UTC-Offset The offset from UTC of this Person's current time zone, as of the time this response was returned. The value MUST conform to the Date-UTC-Offset. Note that this value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset. In addition to the table above, the socially oriented fields definition of the Person include the following. Note that all extended properties are optional and may not be appropriate for use in all applications. Discussion Field Name Field Type Description activities Plural-Field <string> Person's favorite activities. age number The age of this person. Sometimes sites might want to show age without revealing the specific birthday. anniversary Date The wedding anniversary of this person. The value MUST be a valid Date. The year value MAY be set to 0000 when the year is not available. birthday Date The birthday of this person. The value MUST be a valid Date. The year value MAY be set to 0000 when the age of the Person is private or the year is not available. bodyType string Person's body characteristics. books Plural-Field <string> Person's favorite books. cars Plural-Field <string> Person's favorite cars. children Plural-Field <string> Description of the person's children. drinker string Person's drinking status. ethnicity string Person's ethnicity. fashion string Person's thoughts on fashion. food Plural-Field <string> Person's favorite food. gender string The gender of this person. Service Providers SHOULD return one of the following Canonical Values, if appropriate:male, female, or undisclosed, and MAY return a different value if it is not covered by one of these Canonical Values. happiestWhen string Describes when the person is happiest. heroes Plural-Field <string> Person's favorite heroes. humor string Person's thoughts on humor. interests Plural-Field <string> Person's interests, hobbies or passions. jobInterests Plural-Field <string> Person's favorite jobs, or job interests and skills. languagesSpoken Plural-Field <string> List of the languages that the person speaks as ISO 639-1 codes. livingArrangement string Description of the person's living arrangement. lookingFor string Person's statement about who or what they are looking for, or what they are interested in meeting people for. movies Plural-Field <string> Person's favorite movies. music Plural-Field <string> Person's favorite music. nickname string The casual way to address this Person in real life, e.g. "Bob" or "Bobby" instead of "Robert". This field SHOULD NOT be used to represent a user's username (e.g. jsmarr or daveman692); the latter should be represented by the preferredUsername field. note string Notes about this person, with an unspecified meaning or usage (normally notes by the user about this person). This field MAY contain newlines. pets Plural-Field <string> Description of the person's pets orgIdentifier Plural-Field <string> Listing of this person's organizational identifiers (e.g. employee serial number, student number, etc) politicalViews Plural-Field <string> Person's political views. profileSong string URL of a person's profile song. profileVideo string URL of a person's profile video. quotes Plural-Field <string> Person's favorite quotes relationshipStatus string Person's relationship status. religion string Person's relgion or religious views. romance string Person's comments about romance. scaredOf string What the person is scared of. sexualOrientation string Person's sexual orientation. smoker string Person's smoking status. sports Plural-Field <string> Person's favorite sports turnOffs Plural-Field <string> Person's turn offs. turnOns Plural-Field <string> Person's turn ons. tvShows Plural-Field <string> Person's favorite TV shows. A minimal Person example:

application/json representation: { "id" : "example.org:34KJDCSKJN2HHF0DW20394", "displayName" : "Janey", "name" : {"formatted" : "Jane Doe"} }

application/xml representation: <person xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394</id> <displayName>Janey</displayName> <name> <formatted>Jane Doe</formatted> </name> </person>

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <id>example.org:34KJDCSKJN2HHF0DW20394</id> <title>Janey</title> <updated>2008-03-15T10:00:00Z</updated> <author><name>Janey</name></author> <content type="application/xml"> <person xmlns="http://ns.opensocial.org/2008/opensocial"> <id>example.org:34KJDCSKJN2HHF0DW20394</id> <displayName>Janey</displayName> <name> <formatted>Jane Doe</formatted> </name> </person> </content> </entry> Note: The atom:summary element is the appropriate place to put a text or HTML representation of the structured data present in the content element, and the atom:title element is the appropriate place to copy a short descriptive name for the entry, such as name.unstructured. Servers MAY choose to add these or other fields to make their feeds more useful for generic aggregators or tools.

Additional Social Data objects are data objects that are contained within other Social Data object. These do not stand alone, and are not directly accessable by API calls such as osapi, REST, RPC and Pipelining.

Describes an account held by this Person, which MAY be on the Service Provider's service, or MAY be on a different service. Consumers SHOULD NOT assume that this account has been verified by the Service Provider to actually belong to this Person. For each account, the domain is the top-most authoritative domain for this account, e.g. yahoo.com or reader.google.com, and MUST be non-empty. Each account must also contain a non-empty value for either username or userId, and MAY contain both, in which case the two values MUST be for the same account. These accounts can be used to determine if a user on one service is also known to be the same person on a different service, to facilitate connecting to people the user already knows on different services. If Consumers want to turn these accounts into profile URLs, they can use an open-source library like . Field Name Field Type Description domain string The top-most authoritative domain for this account, e.g. "twitter.com". This is the Primary Sub-Field for this field, for the purposes of sorting and filtering. username string An alphanumeric user name, usually chosen by the user, e.g. "jsmarr". userId Object-Id A user ID associated with this account.

An ActionLink encompasses an action that a user may perform against an actionable resource. It defines a caption for the action to perform, a URL to identify the target actionable resource, and the HTTP operation to invoke the resource with. For example, an "Add Friend" button has a caption (namely, "Add Friend") and references the resource that will be invoked when the button is clicked. Field Name Field Type Description caption string Represents a hint that MAY be used by the presentation layer to allow interaction with the user, e.g. a button that invokes an POST. target string URL which represents the target web hook endpoint that can be invoked using the specified HTTP verb. httpVerb string Identifies the HTTP operation to perform against the actionable resource. Should be one of "GET", "PUT", "POST", "DELETE", or other standard HTTP verb. The HTTP verb is optional, and if omitted defaults to "GET".

application/json representation: { caption: "Add Friend", target: "http://example.org/friends/jane.doe", httpVerb: "POST" }

Discussion An object is a thing, real or imaginary, which participates in an activity. It may be the entity performing the activity, or the entity on which the activity was performed. Because Activity Streams are often used in the context of a social platform, OpenSocial adds an additional field to the data model, "deliverTo:". Because these are extensions, they are contained in an enclosing namespace "openSocial". Discussion Field Name Field Type Description attachments Array<ActivityObject> A collection of one or more additional, associated objects, similar to the concept of attached files in an email message. An object MAY have an attachments property whose value is a JSON Array of ActivityObjects. author ActivityObject Describes the entity that created or authored the object. An object MAY contain a single author property whose value is an ActivityObject of any type. Note that the author field identifies the entity that created the object and does not necessarily identify the entity that published the object. For instance, it may be the case that an object created by one person is posted and published to a system by an entirely different entity. OpenSocial note: A common use case is for the "author" to be an OpenSocial. Containers SHOULD use the IRI form of the Global-Id as the value. content string Natural-language description of the object encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An object MAY contain a content property. displayName string A natural-language, human-readable and plain-text name for the object. HTML markup MUST NOT be included. An object MAY contain a displayName property. If the object does not specify an objectType property, the object SHOULD specify a displayName. downstreamDuplicates Array<string> A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's content. An object SHOULD contain a downstreamDuplicates property when there are known objects, possibly in a different system, that duplicate the content in this object. This MAY be used as a hint for consumers to use when resolving duplicates between objects received from different sources. id string Provides a permanent, universally unique identifier for the object in the form of an absolute IRI [RFC3987]. An object 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. image MediaLink Description of a resource providing a visual representation of the object, intended for human consumption. An object MAY contain an image property whose value is a MediaLink. objectType string Identifies the type of object. An object MAY contain an objectType property whose value is a JSON String that is non-empty and matches either the "isegment-nz-nc" or the "IRI" production in [RFC3987]. Note that the use of a relative reference other than a simple name is not allowed. If no objectType property is contained, the object has no specific type. published string The date and time at which the object was published. An object MAY contain a published property. summary string Natural-language summarization of the object encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An activity MAY contain a summary property. updated string The date and time at which a previously published object has been modified. An Object MAY contain an updated property. upstreamDuplicates Array<string> A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's content. An object SHOULD contain an upstreamDuplicates property when a publisher is knowingly duplicating with a new ID the content from another object. This MAY be used as a hint for consumers to use when resolving duplicates between objects received from different sources. url string An IRI [RFC3987] identifying a resource providing an HTML representation of the object. An object MAY contain a url property An example ActivityObject

application/json representation: { summary: "Photo posted", image: { height: 250, width: 250, url: "http://example.org/album/my_fluffy_cat_thumb.jpg" }, downstreamDuplicates: [ "downstream1", "downstream2" ], url: "http://example.org/album/my_fluffy_cat.jpg", id: "object2", upstreamDuplicates: [ "upstream1", "upstream2" ], attachments: [ { id: "attachment1", objectType: "attachment" }, { id: "attachment2", objectType: "attachment" } ], objectType: "photo", opensSocial:{ deliverTo:["1245:MySpace.com"] } } Discussion

application/xml representation: <object> <attachments> <object> <id>attachment1</id> <objectType>attachment</objectType> </object> <object> <id>attachment2</id> <objectType>attachment</objectType> </object> </attachments> <downstreamDuplicate>downstream1</downstreamDuplicate> <downstreamDuplicate>downstream2</downstreamDuplicate> <id>object2</id> <image> <height>250</height> <url>http://example.org/album/my_fluffy_cat_thumb.jpg</url> <width>250</width> </image> <objectType>photo</objectType> <summary>Photo posted</summary> <upstreamDuplicate>upstream1</upstreamDuplicate> <upstreamDuplicate>upstream2</upstreamDuplicate> <url>http://example.org/album/my_fluffy_cat.jpg</url> </object>

The components of a physical mailing address. Service Providers MAY return just the full address as a single string in the formattedsub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields should be combined. Field Name Field Type Description building string The building identifier. Discussion country string The country name component. floor string The floor identifier. Discussion formatted string The full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering. latitude string Expresses the latitude of the location on a map. locality string The city or locality component. longitude string Expresses the longitude of the location on a map. postalCode string The zipcode or postal code component. region string The state or region component. streetAddress string The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines. type string The address type or label. Examples include 'work', 'home'.

Albums support collections of media items (video, image, sound). Field Name Field Type Description description string Description of the album id Object-Id Unique identifier for the album. location Address Location corresponding to the album. mediaItemCount integer Number of items in the album. mediaMimeType Array <string> Array of strings identifying the mime-types of media items in the Album. mediaType Array <string> Array of MediaItem types, types are one of: audio, image, video. owernId Object-Id ID of the owner of the album. thumbnailUrl string URL to a thumbnail cover of the album. title string the title of the album.

application/json representation: { "id" : "44332211", "thumbnailUrl" : "http://pages.example.org/albums/4433221-tn.png", "title" : "Example Album", "description" : "This is an example album, and this text is an example description", "location" : { "latitude": 0, "longitude": 0 }, "ownerId" : "example.org:55443322" }

application/xml representation: <album xmlns="http://ns.opensocial.org/2008/opensocial"> <id>44332211</id> <thumbnailUrl>http://pages.example.org/albums/4433221-tn.png</thumbnailUrl> <title>Example Album</title> <description>This is an example album, and this text is an example description</description> <location> <latitude>0</latitude> <longitude>0</longitude> </location> <ownerId>example.org:55443322</ownerId> </album>

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <content type="application/xml"> <album xmlns="http://ns.opensocial.org/2008/opensocial"> <id>44332211</id> <thumbnailUrl>http://pages.example.org/albums/4433221-tn.png</thumbnailUrl> <title>Example Album</title> <description>This is an example album, and this text is an example description</description> <location> <latitude>0</latitude> <longitude>0</longitude> </location> <ownerId>example.org:55443322</ownerId> </album> </content> <title/> <updated>2003-12-13T18:30:02Z</updated> <author><url>example.org:55443322</url></author> <id>urn:guid:example.org:44332211</id> </entry> For backwards compatibility with the 0.9 REST data format, the "caption" field should be included in the response for an Album and have the same value as the "title" field. Caption is deprecated for 1.0 and will be fully removed from the data format in a future version of the spec.

application/json representation with caption for backwards-compatibility: { "id" : "44332211", "thumbnailUrl" : "http://pages.example.org/albums/4433221-tn.png", "title" : "Example Album", "caption" : "Example Album", "description" : "This is an example album, and this text is an example description", "location" : { "latitude": 0, "longitude": 0 }, "ownerId" : "example.org:55443322" }

The app Id is an Object-Id for the application. There are reserved values for common cases. Discussion App-Id = Object-Id / "@app" The reserved values are defined in the following table: Value Description @app The application currently in use. @all All (or "any") application(s). For example, using @all when requesting activity streams would return the entries that are visible to the user no matter which application generated it. Discussion Discussion Discussion

Each FieldMetadata instance represents a field that MAY be present in a particular entity of the containing object type Field Type Description availability String Description on when this field is available on a particular object. description String The textual description of this field. editable Boolean Flag indicating whether this field is modifiable on create and update operations. name String Name of the key under which this field will be present. required Boolean Flag indicating whether this field is required on create and update operations. since String OpenSocial version in which this object is initially available. type String Object type of this field.

The group Id must only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-), and must uniquely identify the group in a container. Object-Id

OpenSocial defines the following cannonical group identifiers. Group ID Definition @all The inclusive set of information visible to a user. For example, using @all when requesting activity streams would return all of the entries that are visible to the user. @followers A uni-directional relationship that specifies the collection of people (or a single person) that are interested in receiving information, e.g. activity streams, about a specific person. @following A uni-directional relationship that specifies the collection of people that the user is interested in receiving information about. @friends A bi-directional relationship that indicates that both parties have entered into. @self Represents the user who is issuing the request. @summary A container defined collection of fields that serves to provide an abbreviated view of the requested object. For example, simply requesting the information about a user would return their ID and thumbnail. When @summary is requested, the container may provide the public profile. Use of @summary avoids the need to specify a subset of fields.

Increasingly, OpenSocial is being used in enterprise settings. To enable easy retrieval of organization structure information, the specification defines the following values to represent the org chart. Group Id Definition @colleagues All the people that report to the same manager as identified by the User Id. @manager The manager(s) of the person specified by the User Id. Typicially, this will be a single person, however, it may be possible that their be multiple managers of a person. This should not be confused with using the network distance parameter on the query, which may @reports The person or collection of people who are managed by the <userid> of the request.

Represents images, movies, and audio. Field Name Field Type Description album_id Object-Id Album to which the media item belongs. created string Creation datetime associated with the media item - assigned by container in UTC. description string Description of the media item. duration integer For audio/video clips - playtime length in seconds. set to -1/not defined if unknown. file_size long Number of bytes (set to -1/undefined if unknown). id Object-Id Id Associated with the media item. language string Language associated with the media item in ISO 639-3 format. last_updated string Update datetime associated with the media item - assigned by container in UTC. location Address Location corresponding to the media item. mime_type string The MIME type of media, specified as a string. num_comments integer Number of comments on the media item. num_views integer Number of views for the media item. num_votes integer Number of votes received for voting. rating integer Average rating of the media item on a scale of 0-10. start_time string For streaming/live content, datetime when the content is available. tagged_people Array<string> Array of string (IDs) of people tagged in the media item. tags Array<string> Tags associated with this media item. thumbnail_url string URL to a thumbnail image of the media item. title string Describing the media item. type string The type of media, specified as a MediaItem.Type object. url string Specifying the URL where the media can be found.

application/json representation: { "id" : "11223344", "thumbnail_url" : "http://pages.example.org/images/11223344-tn.png", "mime_type" : "image/png", "type" : "image", "url" : "http://pages.example.org/images/11223344.png", "album_id" : "44332211" }

application/xml representation: <MediaItem xmlns="http://ns.opensocial.org/2008/opensocial"> <id>11223344</id> <thumbnail_url>http://pages.example.org/images/11223344-tn.png</thumbnail_url> <mimeType>image/png</mimeType> <type>image</type> <url>http://pages.example.org/images/11223344.png</url> <albumId>44332211</albumId> <MediaItem>

application/atom+xml representation: <entry xmlns="http://www.w3.org/2005/Atom"> <content type="application/xml"> <mediaItem xmlns="http://ns.opensocial.org/2008/opensocial"> <id>11223344</id> <thumbnail_url>http://pages.example.org/images/11223344-tn.png</thumbnail_url> <mimeType>image/png</mimeType> <type>image</type> <url>http://pages.example.org/images/11223344.png</url> <albumId>44332211</albumId> <mediaItem> </content> <title/> <updated>2003-12-13T18:30:02Z</updated> <author><url>example.org:55443322</url></author> <id>urn:guid:example.org:11223344</id> </entry>

Discussion Some types of objects may have an alternative visual representation in the form of an image, video or embedded HTML fragments. A Media Link represents a hyperlink to such resources. Field Name Field Type Description duration integer A hint to the consumer about the length, in seconds, of the media resource identified by the url property. A media link MAY contain a "duration" property when the target resource is a time-based media item such as an audio or video. height integer A hint to the consumer about the height, in pixels, of the media resource identified by the url property. A media link MAY contain a height property when the target resource is a visual media item such as an image, video or embeddable HTML page. url string The IRI of the media resource being linked. A media link MUST have a url property. OpenSocial note: Many OpenSocial containers currently use Media Items as defined by this specification. When a container creates a Media Link that is based on a Media Item, the Media Link URL MUST match the URL of the Media Item. width integer A hint to the consumer about the width, in pixels, of the media resource identified by the url property. A media link MAY contain a width property when the target resource is a visual media item such as an image, video or embeddable HTML page. mediaItemId string Optional. Provides a mapping from an Activity Streams MediaLink to an OpenSocialMediaItem. Identifies the corresponding MediaItem that this MediaLink maps to, if any. This field is namespaced as an "openSocial" extension. An example MediaLink

application/json representation: { "url": "http://www.example.com/johnsalbum/cover.jpg", "width": 400, "height": 300, "duration": 93, "openSocial": { "mediaItemId": "mediaItem123" } }

application/xml representation: <image> <duration>93</duration> <height>300</height> <url>http://www.example.com/johnsalbum/cover.jpg</url> <width>400</width> <openSocial> <mediaItemId>mediaItem123</mediaItemId> </openSocial> </image>

The components of the person's real name. Providers MAY return just the full name as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component fields should be combined. Field Name Field Type Description familyName string he family name of this Person, or "Last Name" in most Western languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr, Esq.). formatted string The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Mr. Joseph Robert Smarr, Esq.). This is the Primary Sub-Field for this field, for the purposes of sorting and filtering. givenName string The given name of this Person, or "First Name" in most Western languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr, Esq.). honorificPrefix string The honorific prefix(es) of this Person, or "Title" in most Western languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr, Esq.). honorificSuffix string The honorifix suffix(es) of this Person, or "Suffix" in most Western languages (e.g. Esq. given the full name Mr. Joseph Robert Smarr, Esq.). middleName string The middle name(s) of this Person (e.g. Robert given the full name Mr. Joseph Robert Smarr, Esq.). pronunciation string A string describing the appropriate natural-language pronunciation of the name. Discussion pronunciationUrl string An IRI to an audio resource illustrating the appropriate natural-language pronunciation of the name. Discussion

Each ObjectMetadata instance represents all of the metadata associated with a particular object type. Field Type Description description String The textual description of this object. fields FieldMetadata[] Description of all possible fields that may appear in this object represented as an Array of FieldMetadata. name String Formal name of this object type. resourceLinks ResourceMetadata[] Description of all possible resource links that may appear in this object. since String OpenSocial version in which this object is initially available.

Describes a current or past organizational affiliation of this contact. Service Providers that support only a single Company Name and Job Title field should represent them with a single organization element with name and title properties, respectively. Field Name Field Type Description address Address The physical address of this organization. department string The department within this organization. description string A textual description of the role this Person played in this organization. This field MAY contain newlines. endDate Date or string The date this Person left this organization or the role specified by title within this organization. This value SHOULD be a valid Date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text. field string The field the Organization is in. location string The physical location of this organization. This is an abbreviated location like "San Francisco". The container could choose to implement either "address" or "location" field, or both. name string The name of the organization (e.g. company, school, or other organization). This field MUST have a non-empty value for each organization returned. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering. salary string The salary the person receieves from the organization startDate Date or string The date this Person joined this organization. This value SHOULD be a valid Date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text. subfield string The subfield the Organization is in. title string The job title or organizational role within this organization. type string The type of organization, with Canonical Values job and school. webpage string A webpage related to the organization.

Describes a generic file or document. Field Name Field Type Description author Person The person who created the file displayName string The natural-language, human-readable and plain-text title of the file. fileUrl string The IRI of the file described by this object id string The unique identifier for the file object published string The optional time the file object was created in the form of an [RFC3339] "date-time" mimeType string The MIME type of the file described by the object. updated string The optional time the file object was last updated in the form of an [RFC3339] "date-time". url string The permanent IRI of the file's HTML representation.

Each PropertyMetadata instance represents a configuration value for this social container. Field Type Description description String A textual description of the property name String The name of the metadta property type String Object type of this property value value Object The current value of this property

The Message-Collection-Id is an Object-Id for the message collection. There are reserved values for common cases. Object-Id The reserved values are defined in the following table: Value Description @inbox The user inbox to access incoming messages @outbox The user outbox where to send outgoing messages

Discussion