Data Spec Opensocial

OpenSocial August 2012
OpenSocial Social Data Specification

2.5.0
opensocial-social-data-specification-2-5-0
Abstract
This document defines all the data objects used in the OpenSocial APIs. Objects
defined here make use of the Core Data [CoreData] objects. The structure of the
data is used by many different APIs:
JavaScript within the gadget is done using osapi APIs, defined in the Social
Gadget Specification [SocialGadget]
REST and RPC access is done using APIs defined in the Social API Server
Spec [SocialServer]

Table of Contents
1. Notation and Conventions
o 1.1 Requirements
o 1.2 Augmented BNF
o 1.3 Basic Rules
2. Primary Social Data
o 2.1 Activity
o 2.2 Activity Streams Support
2.2.1 ActivityEntry
2.2.1.1 OpenSocial Extensions
o 2.3 AppData
2.3.1 An isolated AppData example.
2.3.2 An AppData Collection Example
o 2.4 Group
o 2.5 Message
o 2.6 Person
3. Additional Social Data
o 3.1 Account
o 3.2 ActionLink
o 3.3 ActivityObject
o 3.4 Address
o 3.5 Album
o 3.6 App Id
o 3.7 FieldMetadata
o 3.8 Group Id
o 3.9 MediaItem
o 3.10 MediaLink
o 3.11 Name
o 3.12 ObjectMetadata
o 3.13 Organization
o 3.14 File
o 3.15 PropertyMetadata
4. References
o 4.1 Discussion
o 4.2 References
Author's Address

1. Notation and Conventions
Domain name examples use RFC2606 [RFC2606].
1.1 Requirements
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 [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.
1.2 Augmented BNF
The grammatical rules in this document are to be interpreted as described
in RFC2234 [RFC2234] (Augmented Backus-Naur Form).
The following constructs are introduced in this document to augment RFC2234:
{rule1 rule2}
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.
#rule
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.
&rule
A construct "&" is defined, similar to "#", which uses an ampersand (&) instead
of commas, and MUST NOT include linear white space between elements.
implied *LWS
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.
1.3 Basic Rules
The following rules are used throughout this specification to describe basic parsing
constructs. The US-ASCII coded character set is defined by [RFC20]
OCTET = <any 8-bit sequence of data>
CHAR = <any US-ASCII character (octets 0 - 127)>
UPALPHA = <any US-ASCII uppercase letter "A".."Z">
LOALPHA = <any US-ASCII lowercase letter "a".."z">
ALPHA = UPALPHA / LOALPHA
DIGIT = <any US-ASCII digit "0".."9">
CTL = <any US-ASCII control character (octets 0 - 31) and
DEL (127)>
CR = <US-ASCII CR, carriage return (13)>
LF = <US-ASCII LF, linefeed (10)>
SP = <US-ASCII SP, space (32)>
HT = <US-ASCII HT, horizontal-tab (9)>
<"> = <US-ASCII double-quote mark (34)>
CRLF = CR LF
LWS = [CRLF] 1*( SP / HT )
TEXT = <any OCTET except CTLs, but including LWS>
COMMA = <US-ASCII comma (44)>

2. Primary Social Data
Primary Social Data objects represent objects that are directly addressable
through top level API calls, such as osapi, RPC, REST and Pipelining tags.
2.1 Activity
DeprecatedDeprecated in OpenSocial 2.0. Will be removed in future version; use Activity
Streams instead.
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/af37
78</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">

78</id>
<title>some activity</title>
<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/af
3778" />
<content type="application/xml">
<activity xmlns="http://ns.opensocial.org/2008/opensocial">

78</id>
<title type="html"><a href=\"foo\">some activity</a></title>
<body>Some details for some activity</body>
<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.
2.2 Activity Streams Support
Discussion [Issue-1140]
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.
2.2.1 ActivityEntry
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".
actor ActivityObject Describes the entity that performed the
activity. An activity MUST contain one
actor property whose value is a
singleActivityObject.
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
singleActivityObject. OpenSocial note: If an
OpenSocial application created the Activity
Entry, this value SHOULD be the appId
(Section 3.6).
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".
2.2.1.1 OpenSocial Extensions
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.
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 [Issue-1319]Discussion [Issue-1236]Discussion [Issue-1318]
{
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: "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"
}]
}
}
<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>
</object>
</attachments>
<downstreamDuplicate>downstream1</downstreamDuplicate>
<id>object2</id>
<image>
<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>
<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>
<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>
2.3 AppData
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.
key string A unique value with respect to the context it is
being stored within (typically a person).
value string An arbitary string.
2.3.1 An isolated AppData example.
The first example is of a collection of key/value pairs for a particular
application/user pair:
{
"pokes" : 3,
"last_poke" : "2008-02-13T18:30:02Z"
}
<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>
<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>
2.3.2 An AppData Collection Example
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.
{
"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" }
}
}
<entry>
<personId>example.org:34KJDCSKJN2HHF0DW20394</personId>
<entry>
<key>pokes</key>
<value>3</value>
</entry>
<entry>
<value>2008-02-13T18:30:02Z</value>
</entry>
</appData>
<personId>example.org:58UIDCSIOP233FDKK3HD44</personId>
<entry>
<key>pokes</key>
<value>2</value>
</entry>
<entry>
<value>2007-12-16T18:30:02Z</value>
</entry>
</appData>
</entry>
<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/>

<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/>

<author><url>uurn:guid:example.org:58UIDCSIOP233FDKK3HD44</url></author
>
<id>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</id>
</entry>
</feed>
2.4 Group
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.
A Group example:
{
"id" : "example.org:34KJDCSKJN2HHF0DW20394/friends",
"title" : "Peeps",
}
<group xmlns="http://ns.opensocial.org/2008/opensocial">
<id>example.org:34KJDCSKJN2HHF0DW20394/friends</id>
<title>Peeps</title>
</group>
<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/@fri
ends" />
<link rel="alternate" type="application/atom+xml"
ends?format=atom" />
<link rel="alternate" type="application/xml"
ends?format=xml" />
<group xmlns="http://ns.opensocial.org/2008/opensocial">
<id>example.org:34KJDCSKJN2HHF0DW20394/friends</id>
<title>Peeps</title>
</group>
</entry>
2.5 Message
Valid definitions for Message-Field are listed in the table below.
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, use for
threaded
comments/messages.
Reference the sematics
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.
Reference the sematics
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).
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>
<body>Short message from Joe to some friend\/s</body>
<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:
1. For people: [container]:[identifier]
2. 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"
}
2.6 Person
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 [Issue-1218]
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 [Issue-1132]
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.
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 relationship field,
described below, and is thus
intended as a summary value
indicating that some type of bi-
directional relationship exists, 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.
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
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 relationship type that was
established between the user and
this person by the Service
Provider. Note this field is a
parallel set of category labels to
the tags field, but relationships
MUST have been bi-directionally
confirmed, whereas tags are
asserted by the user without
acknowledgment by this Person.
Note that this field consists only
of a string value.
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.
thumbnailUrl 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 validDate.
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
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 [Issue-1132]
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
The year value MAY be
set to 0000 when the
year is not available.
birthday Date The birthday of this
person. The value
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:
{
"id" : "example.org:34KJDCSKJN2HHF0DW20394",
"displayName" : "Janey",
"name" : {"formatted" : "Jane Doe"}
}
<person xmlns="http://ns.opensocial.org/2008/opensocial">
<id>example.org:34KJDCSKJN2HHF0DW20394</id>
<displayName>Janey</displayName>
<name>
<formatted>Jane Doe</formatted>
</name>
</person>
<id>example.org:34KJDCSKJN2HHF0DW20394</id>
<title>Janey</title>
<updated>2008-03-15T10:00:00Z</updated>
<author><name>Janey</name></author>
<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.

3. Additional Social Data
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.
3.1 Account
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 [Social-Graph-
Node-Mapper].
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.
3.2 ActionLink
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.
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".
{
caption: "Add Friend",
target: "http://example.org/friends/jane.doe",
httpVerb: "POST"
}
3.3 ActivityObject
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 [Issue-1317]
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
anActivityObject 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 aMediaLink.
objectType string Identifies the type of
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
contain a url property
An example ActivityObject
{
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",
},
{
id: "attachment2",
}
],
objectType: "photo",
opensSocial:{
deliverTo:["1245:MySpace.com"]
}
}
<object>
<attachments>
<object>
</object>
<object>
</object>
</attachments>
<id>object2</id>
<image>
<url>http://example.org/album/my_fluffy_cat_thumb.jpg</url>
<width>250</width>
</image>
<objectType>photo</objectType>
<summary>Photo posted</summary>
<url>http://example.org/album/my_fluffy_cat.jpg</url>

</object>
3.4 Address
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.
building string The building
identifier. Discussion [Issue-
1132]
country string The country name
component.
floor string The floor
identifier. Discussion [Issue-
1132]
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'.
3.5 Album
Albums support collections of media items (video, image, sound).
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.
{
"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"
}
<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>
<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/>
<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"
}
3.6 App Id
The app Id is an Object-Id for the application. There are reserved values for
common cases. Discussion [Issue-1140]
App-Id = Object-Id / "@app"
The reserved values are defined in the following table:
Value Description
@app The application currently in use.
Discussion [Issue-1239]Discussion [Issue-1223]
3.7 FieldMetadata
IncubatingLinkIssue 1261: Metadata Service
Each FieldMetadata instance represents a field that MAY be present in a particular
entity of the containing object type
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.
3.8 Group Id
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.
IncubatingLinkIssue 1281: Add @followers/@following/@colleagues/@reports/@manager
Group-Id = Object-Id / "@self" / "@friends" / "@all" / "@followers" /
"@following" / "@colleagues" / "@reports" / "@manager"
3.8.1 Canonical Group Id Values
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.
3.8.1.1 Organization Chart
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.
3.9 MediaItem
Represents images, movies, and audio.
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.
{
"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"
}
<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>
<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/>
<author><url>example.org:55443322</url></author>
<id>urn:guid:example.org:11223344</id>
</entry>
3.10 MediaLink
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.
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
the url property. A
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
the url property. A
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
{
"url": "http://www.example.com/johnsalbum/cover.jpg",
"width": 400,
"height": 300,
"duration": 93,
"openSocial": {
"mediaItemId": "mediaItem123"
}
}
<image>
<duration>93</duration>
<url>http://www.example.com/johnsalbum/cover.jpg</url>
<width>400</width>
<openSocial>
<mediaItemId>mediaItem123</mediaItemId>
</openSocial>
</image>
3.11 Name
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.
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.
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
Esq.).
honorificPrefix string The honorific prefix(es)
of this Person, or "Title"
in most Western
languages (e.g. Mr.
Esq.).
honorificSuffix string The honorifix suffix(es)
of this Person, or
"Suffix" in most Western
languages (e.g. Esq.
Esq.).
middleName string The middle name(s) of
this Person (e.g. Robert
Esq.).
pronunciation string A string describing the
appropriate natural-
language pronunciation
of the
name. Discussion [Issue-
1132]
pronunciationUrl string An IRI to an audio
resource illustrating the
appropriate natural-
language pronunciation
of the
name. Discussion [Issue-
1132]
3.12 ObjectMetadata
Each ObjectMetadata instance represents all of the metadata associated with a
particular object type.
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.
3.13 Organization
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.
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 validDate 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.
3.14 File
IncubatingLinkSimple File Object
Describes a generic file or document.
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.
3.15 PropertyMetadata
Each PropertyMetadata instance represents a configuration value for this social
container.
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

4. References
4.1 Discussion
[Issue-1140] Incorporate ActivityStreams 1.0 into OpenSocial,
<http://code.google.com/p/opensocial-
resources/issues/detail?id=1140>.
[Issue-1132] Proposal to Modify the Social Data Model in OS 2.0,
[Issue-1218] Person required fields inconsistency,
[Issue-1180] Missing datatypes in message section,
[Issue-1223] App-Id & @app definitions missing,
[Issue-1236] Clarify how Activity Streams are extended with Embedded
Experiences, <http://code.google.com/p/opensocial-
[Issue-1319] Add embed as a field in the activityEntry,
[Issue-1318] deliverTo: incorrectly specified on ActivityObject,
[Issue-1317] Change the namespace for activityStrea.ms support from
org.opensocial to openSocial,
[Issue-1239] Broken links in spec for app id / group id,
4.2 References
[RFC2119] Bradner, S., Key words for use in RFCs to Indicate
Requirement Levels, RFC 2119, March 1997.
[RFC2606] Eastlake, D. and A. Panitz, Reserved Top Level DNS
Names, RFC 2606, June 1999.
[RFC2234] Augmented BNF for Syntax Specifications: ABNF,
RFC 2234.
[RFC20] ASCII format for Network Interchange, RFC 20.
[Social-Graph-Node-Mapper] Social Graph Node Mapper,
<http://code.google.com/p/google-
sgnodemapper/>.
[CoreData] OpenSocial Core Data Specification, August 2011,
<./Core-Data.xml>.
[SocialGadget] OpenSocial Social Gadget Specification,
August 2011, <./Social-Gadget.xml>.
[SocialServer] OpenSocial Social API Server Specification,
August 2011, <./Social-API-Server.xml>.

Author's Address
OpenSocial and Gadgets Specification GroupEMail: opensocial-and-gadgets-
spec@googlegroups.com

Data Spec Opensocial

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Data Spec Opensocial

Diunggah oleh

Hak Cipta:

Format Tersedia

OpenSocial August 2012

OpenSocial Social Data Specification

Anda mungkin juga menyukai