OpenSocial RESTful Protocol Specification
v0.9opensocial-and-gadgets-spec@googlegroups.com
General
OpenSocialsocial networkingRESTXMLExtensible Markup LanguageJSONJavaScript Object NotationAtomThe 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. Domain name examples use
RFC2606.This API defines a language and platform neutral protocol for clients to
interact with OpenSocial container servers outside of gadgets on a web page.
As a protocol, it is intended to be reasonably easy to implement in any
language and on any platform. It should also be usable across a range of
clients, from gadgets operating within a web page to servers communicating
to synchronize data about a user.The protocol operates primarily in terms of resources and operations on
them. It is defined on top of the HTTP protocol, and uses the standard HTTP
methods (GET, POST, PUT, DELETE, etc.) to retrieve and change server
state.No single data representation is ideal for every client. This protocol
defines representations for each resource in three widely supported formats,
JSON, XML, and
Atom /
AtomPub, using a set of generic mapping rules.
The mapping rules allow a server to write to a single interface rather than
implementing the protocol three times.OpenSocial container servers are free to define additional
representations but MUST support at least the JSON and Atom formats for all
resources and XML for the people calls. XML MAY be supported for the rest of
the resources.The protocol defines Activity, Person, Group, and AppData resources. Most
operations consist of retrieving (GET), updating (PUT), creating (POST or
PUT), or destroying (DELETE) these resources. It also specifies an optional
partial update feature which avoids sending large resources over the wire to
update just one field.OpenSocial API Background details the underlying concepts used below;
this document assumes familiarity with the OpenSocial model.Each resource has three representations, as JSON, XML, and Atom. All data
must be representable in each format. The XML and JSON formats have a one to
one mapping while the Atom format is defined separately for each type of
object and collection. Throughout this document, examples will only be given
in JSON and Atom. The XML representation can be mapped directly from the
JSON and MUST conform to the XSD in
.Each resource is represented as a hierarchical tree of elements. Ordering
of elements within a parent element may or may not be significant, depending
on the context. Mapping consists of converting between the internal
hierarchy and the JSON/XML or Atom protocol format.The set of allowed fields in each type of data is the same as the set
documented in
.The general rules for mapping between the Atom and JSON formats are as
follows. Each data type may add additional aliasing rules.
The default location for all data in the Atom format is in
atom:entry/atom:content/datatype, where datatype is a root node naming the
type of data delivered: <person>, <group>, <activity>, or
<appdata>.The field names are specified at the end of this document in
camelCase.Strings are represented as strings in both formats.Dates and timestamps are represented as strings using
RFC3339 Timestamps format date-time elements.
These are also known as "XSD Dates". In cases where only a day-of-the-year
is desired, e.g., a birthday, the year SHOULD be specified as 0000.Enums are represented as objects with "displayvalue" (localizable,
customizable string) and "key" (key) fields.Arrays are represented as arrays in the JSON representation and as
repeated fields in the XML representation.Sub-objects are represented as sub-elements in both formats.Fields are placed directly in the root object in the JSON format. In the
Atom format, they are by default placed under atom:content/datatype (e.g.,
atom:content/person for person data). Some fields are 'hoisted' and aliased
to standard Atom fields directly underneath atom:entry. There are three
standard aliases that apply to all data types:
atom:entry/atom:id aliases the "id" field. The JSON format id is the
OpenSocial globally unique ID, which consists of the container domain
(e.g., example.org) followed by a colon and the container's id for that
person. The container specific id can only contain letters (A-Za-z),
numbers (0-9), dots (.), hyphens (-) and underscores (_). For example,
example.org:78gh37261ddfdf. In the Atom format, it is translated into the
required URI data type by prepending "urn:guid:" to the OpenSocial ID
string. These rules are intended to make mapping IDs between the RESTful
API and the JS API straightforward while preserving global uniqueness.atom:entry/atom:updated aliases the JSON field indicating the most
recent update time if available (POSTED_TIME for Activity), or the
generation time if no better information is available.atom:entry/atom:published aliases the JSON field indicating creation
time (POSTED_TIME for Activity).Examples of the primary types of data follow. Each example shows
representations in XML, JSON, and Atom, with the payload data highlighted
for ease of comparison.The structure of the response object returned from a successful request
for the JSON or XML formats is as follows. The root element isresponse,
which is shown explicitly as the root element in XML format, and is the
anonymous root object returned when the format is json (i.e. in JSON, the
response returned is the object value of the response node). The response
node MUST contain the following child nodes, and MAY contain additional
nodes that the Service Provider wishes to add to expose additional data.
Note thatstartIndex, itemsPerPage, and totalResults are based on
.startIndex: the index of the first result returned in this response,
relative to the starting index of all results that would be returned if
no startIndex had been requested. In general, this will be equal to the
value requested by the startIndex, or 0 if no specific startIndex was
requested.itemsPerPage: the number of results returned per page in this
response. In general, this will be equal to the count Query Parameter,
but MAY be less if the Service Provider is unwilling to return as many
results per page as requested, or if there are less than the requested
number of results left to return when starting at the current startIndex.
This field MUST be present if and only if a value for count is specified
in the request.totalResults: the total number of contacts that would be returned if
there were no startIndex or count specified. This value tells the
Consumer how many total results to expect, regardless of the current
pagination being used, but taking into account the current filtering
options in the request.entry: an array of objects, one for each item matching the request, as
defined in
. For consistency of parsing, if the
request could possibly return multiple items (as is normally the case),
this value MUST always be an array of results, even if there happens to
be 0 or 1 matching results. If the request is specifically for a single
contact (e.g. because the request contains Additional Path Information
like /@me/@all/{id} or /@me/@self), then entry MUST be an object
containing the single item returned (i.e. "entry": [ { /* first item */ }
] and "entry": { /* only item */ } respectively).For example:
application/json representation:
{
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 100,
"entry" : [
{...first item...},
{...second item...}
...
]
}
or, for only one item:
{
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 100,
"entry" : {...only item...}
}
xml representation:
<response xmlns="http://ns.opensocial.org/2008/opensocial">
<startIndex> 1 </startIndex>
<itemsPerPage> 10 </itemsPerPage>
<totalResults> 100 </totalResults>
<entry>...first item...</entry>
<entry>...second item...</entry>
...
</response>
or, for only one item:
<response xmlns="http://ns.opensocial.org/2008/opensocial">
<startIndex> 1 </startIndex>
<itemsPerPage> 10 </itemsPerPage>
<totalResults> 100 </totalResults>
<entry>...first item...</entry>
</response>
The atom format uses the JSON to Atom mapping rules described above and
has a different base format than the XML:
application/atom+xml representation:
<feed xmlns="http://www.w3.org/2005/Atom" xmlos:osearch="http://a9.com/-/spec/opensearch/1.1">
<author><uri>urn:guid:example.org:58UIDCSIOP233FDKK3HD44</uri></author>
<link rel="next" href="http://api.example.org/..." />
<osearch:totalResults>100</osearch:totalResults>
<osearch:startIndex>1</osearch:startIndex>
<osearch:itemsPerPage>10</osearch:itemsPerPage>
<entry>...first item...</entry>
<entry>...second item...</entry>
...
</feed>
A Person contains social network data about a single person. The same
record is used for contacts/friends and for profiles. See
for a full list of available fields and their
types. See also the general mapping rules in
.A minimal Person example:
application/json representation:
{
"id" : "example.org:34KJDCSKJN2HHF0DW20394",
"displayName" : "Janey",
"name" : {"formatted" : "Jane Doe"},
"gender" : "female"
}
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>
<gender>female</gender>
</person>
application/atom+xml representation:
<entry xmlns="http://www.w3.org/2005/Atom">
<id>example.org:34KJDCSKJN2HHF0DW20394</id><!-- person.id -->
<title>Janey</title><!-- person.displayName -->
<updated>2008-03-15T10:00:00Z</updated><!-- last profile edit, or datetime.utcnow() -->
<author><name>Janey</name></author><!-- person.displayName -->
<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>
<gender>female</gender>
</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.OpenSocial Groups are owned by people, and are used to tag or categorize
people and their relationships. The RESTful API supports querying for the
available groups for a given user. The groups are returned as a collection.
Each group has a display name, an identifier which is unique within the
groups owned by that person, and a URI link. 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><!-- group.id -->
<title>Friends of John Smith</title><!-- group.title + person.displayName -->
<updated>2008-03-15T10:00:00Z</updated><!-- last significant group change, or datetime.utcnow() -->
<author><name>John Smith</name></author><!-- person.displayName -->
<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>
Groups only appear within Group Collections and are used to
retrieve a list of available groups for a given person.An OpenSocial Activity represents a short summary or notification of a
timestamped event, often with pointers for more information. See
for a full list of available fields and
their types. 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"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>
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><!-- activity.title or activity.titleId -->
<updated>2008-02-20T23:35:37.266Z</updated><!-- postedTime, or datetime.utcnow() -->
<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" /><!-- alternate JSON response -->
<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: <b>, <i>, <a>, <span>. The container may
ignore this formatting when rendering the activity.AppData stores uninterpreted key/value pairs on behalf of an
application. The standard unit of AppData is all of the key/value pairs
stored for a given app on behalf of a given user; however, the API supports
other types of queries (detailed below). To retrieve a subset of fields,
use the fields= selector syntax (detailed below).The data within each field is assumed to be in JSON format and is
otherwise uninterpreted.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>
Albums support collections of media items (video, image, sound).
application/json representation:
{
"id" : "44332211",
"thumbnailUrl" : "http://pages.example.org/albums/4433221-tn.png",
"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"
}
application/xml representation:
<album xmlns="http://ns.opensocial.org/2008/opensocial">
<id>44332211</id>
<thumbnailUrl>http://pages.example.org/albums/4433221-tn.png</thumbnailUrl>
<caption>Example Album</caption>
<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>
<caption>Example Album</caption>
<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>
A minimal media item example:
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>
Content Upload is a generic mechanism to allow for a standard way to
upload content. A common place to apply content upload will be against an
existing Album or MediaItem endpoint. In most scenarios an uploaded
content is associated with creation of an entity. Upload of content
routinely causes the creation of the entity. For example, uploading a
photo causes the container to create a new media item. The application can
then update that MediaItem and set attributes via a second request at some
later time. The requests look like:
Step 1: Upload PhotoStep 2: Update Photo attributes (caption, description, etc.)The two step request process is illustrated below.Step 1: Upload the image in the album.
Request
POST /album/112233?mediaType=IMAGE HTTP/1.1
<usual headers>
Accept-Type: application/xml
Content-Type: image/gif
Content-Length: length
GIF89a....<binary data>
Response
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ossearch="http://a9.com/-/spec/opensearch/1.1/">
<author><uri>urn:guid:example.org:33445577722</uri></author>
<link rel="next" href="http://api.example.org/..." />
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi">
<content type="application/xml">
<mediaitem xmlns="http://ns.opensocial.org/2008/opensocial">
<id>223344</id>
<media_type>IMAGE</media_type>
</mediaitem>
</content>
<title />
<updated>2008-10-24T20:30:40.500Z</updated>
<author />
</entry>
</feed>
Step 2: PUT MediaItem details to MediaItem (id:223344)
Request
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi">
<content type="application/xml">
<mediaitem xmlns="http://ns.opensocial.org/2008/opensocial">
<id>223344</id>
<media_type>IMAGE</media_type>
<url>http://cdn.example.org/223344.gif</url>
<caption>Lena</caption>
</mediaitem>
</content>
<title />
<updated>2008-10-24T20:30:40.500Z</updated>
<author />
</entry>
Response
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ossearch="http://a9.com/-/spec/opensearch/1.1/">
<author><uri>urn:guid:example.org:33445577722</uri></author>
<link rel="next" href="http://api.example.org/..." />
<ossearch:totalResults>100</ossearch:totalResults>
<ossearch:startIndex>1</ossearch:startIndex>
<ossearch:itemsPerPage>10</ossearch:itemsPerPage>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi">
<content type="application/xml">
<mediaitem xmlns="http://ns.opensocial.org/2008/opensocial">
<id>223344</id>
<media_type>IMAGE</media_type>
<url>http://cdn.example.org/223344.gif</url>
<caption>Lena</caption>
</mediaitem>
</content>
<title />
<updated>2008-10-24T20:30:40.500Z</updated>
<author />
</entry>
</feed>
The response indicates that the media item was updated.Step 2: Upload the image in the media item place holder
Request
POST /album/112233/mediaitem/223344 HTTP/1.1
<usual headers>
Accept-Type: application/xml
Content-Type: image/gif
Content-Length: length
GIF89a....<binary data>
Response
<response xmlns="http://ns.opensocial.org/2008/opensocial">
<startIndex> 1 </startIndex>
<itemsPerPage> 1 </itemsPerPage>
<totalResults> 1 </totalResults>
<entry> ... </entry>
</response>
The shortcut upload mechanism is OPTIONAL. This two step process shown
above can be merged into one by a single POST request with the content
type set to the item being uploaded. The POST URL can optionally pass the
attributes. The Accept-type indicates the format of the response expected.
Request
POST /album/112233/mediaitem/?caption=Lena&media_type=IMAGE HTTP/1.1
<usual headers>
Accept-Type: application/json
Content-Type: image/gif
Content-Length: length
GIF89a....<binary data>
Response
{
"startIndex" : 1,
"itemsPerPage" : 1,
"totalResults" : 1,
"entry" : {
"id" : "223344",
"caption" : "Lena",
"media_type" : "IMAGE",
}
}
Containers MUST support the invalidation endpoint even if they do not
perform any caching and MUST provide an entry for it in their XRDS. To
invalidate content a developer's backend notifies the container of the
content it wishes to invalidate by making a 2-legged OAuth call to the
REST/RPC endpoint with one or many keys to be invalidated. The consumer key
in the 2-legged OAuth call is used by the container to identify the calling
application. Keys have the following general form:
<invalidation-key> = url | <opensocial id>
When invalidating opensocial id's containers MUST support
invalidating both fully qualified opensocial ids of the form
"<domain>:<domain relative id>", "<domain>.<domain
relative id>", as well as ids of the form "<domain relative id>".
Keys that refer to URLs MUST include a protocol prefix (e.g. 'http://') so
they can be distinguished from ids. Each request accepts a repeated group
of ids.
application/json representation:
{ invalidationKeys : [ <invalidation-key>, <invalidation-key>, ...] }
application/xml representation:
<invalidationKeys>
<invalidationKey>...</invalidationKey>
<invalidationKey>...</invalidationKey>
</invalidationKeys >
OpenSocial uses standard HTTP methods: GET to retrieve, PUT to update in
place, POST to create new, and DELETE to remove. POST is special; it
operates on collections and creates new activities, persons, or app data
within those collections, and returns the base URI for the created resource
in the Location: header, per AtomPub semantics. Restricted clients, or
clients behind restricted clients, which cannot use PUT or DELETE SHOULD
translate PUT and DELETE to POST operations with an additional
X-HTTP-Method-Override: header:
POST /... HTTP/1.1
...
X-HTTP-Method-Override: PUT
Servers SHOULD respond to POST+X-HTTP-Method-Override as if the
content of the header were the actual operation sent. Note: OpenSocial 0.9
does not support cross-domain JSONP (GET with callback), but servers MAY
offer this as an extension. It is RECOMMENDED that such servers implement
appropriate security and authorization controls.Each RESTful operation has a request context that usually includes
authentication and authorization information. Typically, the context
information includes the requestor id (the user initiating the request) and
app ID (the application, or whatever is acting as the user's agent). It may
include other container-specific information.Containers MUST be an
Service Provider (a web application that
allows access via OAuth). Containers MAY also support other ways to
establish a request context. Containers MUST also support the Consumer
Request OAuth extension, in which the end user has not directly authorized
the operation. Applications SHOULD ensure that the users have given prior
consent, implicitly or explicitly, to the operation or class of operations.
However, containers MAY require an additional prior trust relationship be
established by the app in order to allow use of Consumer Request OAuth.If a Consumer has a user identifier and wishes to indicate that the
operation is being done on behalf of that particular user, it SHOULD provide
the OAuth extension parameter xoauth_requestor_id with the OAuth signed
parameters. Consumers SHOULD only provide this if the user has given prior
consent, implicitly or explicitly, to the operation or class of operations,
as it indicates that the operation is being done on behalf of the user.
Container SPs MUST either honor the parameter or ignore it as if it were not
provided.Thus, a request context usually includes the requesting application (the
OAuth Consumer), and MAY include the requesting user, either implicitly via
an oauth_token or explicitly via xoauth_requestor_id. It may also include
additional information via extensions or other channels (cookies, URI
parameters, client SSL certificates, etc.) A container may also accept
requests with no authentication or authorization (authnz) information at all
for public data. A container may provide a public version (e.g., of a
profile) if no authnz information is provided.Note that the data provided for a given RESTful URI MAY vary per
requestor or app. Thus, the meaning of the resource at a given URI is "the
view of the information available to the current requestor/app combination".
In the case where no information is available due to lack of authorization,
an HTTP 401 Unauthorized response SHOULD be returned to the client. In the
case where at least some view of the information is available, it SHOULD be
returned using a 200 status, with a standard OAuth WWW-Authenticate: header
indicating that additional information may be available when using a
different authnz context.A container declares what collection and features it supports, and
provides templates for discovering them, via a simple discovery document. A
client starts the discovery process at the container's identifier URI (e.g.,
example.org). The full flow is available athttp://xrds-simple.net/core/1.0/;
in a nutshell:
Client GETs {container-url} with Accept: application/xrds+xmlContainer responds with either an X-XRDS-Location: header pointing to
the discovery document, or the document itself.If the client received an X-XRDS-Location: header, follow it to get the
discovery document.Once the client has the XRDS document, they have the complete set of
services supported by that service. All OpenSocial service types declare the
base URI in the XRDS URI element. Each service type declares the root URI
for the service. Service specific parameters are passed to each endpoint
using a fixed URI format. This format is defined by each service. The
discovery document is an XML file in the same format used for OpenID and
OAuth discovery, defined at http://xrds-simple.net/core/1.0/:
<XRDS xmlns="xri://$xrds">
<XRD xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)" version="2.0">
<Type>xri://$xrds*simple</Type>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/people</Type>
<URI>http://api.example.org/people</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/groups</Type>
<URI>http://api.example.org/groups</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/activities</Type>
<URI>http://api.example.org/activities</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org//2008/opensocial/appData</Type>
<URI>http://api.example.org/appData</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/cache/invalidate</Type>
<URI>http://api.example.org/cache/invalidate</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/messages</Type>
<URI>http://api.example.org/messages</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/albums</Type>
<URI>http://api.example.org/albums</URI>
</Service>
<Service>
<Type>http://ns.opensocial.org/2008/opensocial/mediaItems</Type>
<URI>http://api.example.org/mediaItems</URI>
</Service>
</XRD>
</XRDS>
Each Service advertises a service provided by the container. Each
container MUST support the service Types documented below and MAY support
others by advertising them in the discovery document. Each service comprises
a set of resources defined by the given URI Template (or URI, if there is
only a single resource). Clients follow the URIs and instantiate the
templates to find and operate on specific resources. (URI Template syntax is
documented at
http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt.)The set of substitution variables is fixed for each service Type. The
core set of service Types and their substitution variables is documented
below. Extensions to OpenSocial SHOULD document their substitution
variables; note that a reasonable place to put human readable documentation
is at the namespace URI.This section defines the core types that every OpenSocial container MUST
support, their XRDS types, and their semantics. Unless otherwise specified,
all HTTP operations are generally allowed for any URI endpoint; a container
which wishes to specify the allowed operations SHOULD provide an HTTP Allow:
header for each resource listing the allowed operations.Each service type defines an associated partial URI format. The base URI
for each service is found in the URI element associated with the service in
the discovery document. Each service type accepts parameters via the URL
path. Definitions are of the form
{a}/{b}/{c}
Parameters must be filled in using left to right ordering. If a
positional pattern is missing, no parameters to the right of that parameter
may be filled in. For example, if the preceding pattern was used and only
the value of the a parameter was known and set to @me, the complete URL
would be expressed as:
[Discovery URI]/@me
XRDS Type: http://ns.opensocial.org/2008/opensocial/peopleURI structure: {guid}/{selector}/{pid}guid : Container-globally-unique user identifier; identifies owner of
the people data, or @me to indicate the requestor should be used.selector : One of
A user-defined local group name to select a group of contacts (a
collection)@self to select the person record for guid@all to select all the universal set of contacts (a collection)@friends to select the subset of contacts which are friends (a
collection)pid : In the context of a collection selector, picks a single person
record from that collection. The pid value MAY be relative to that
collection.People URI examples:
URI FragmentDescription/people/{guid}/@allCollection of all people connected to user {guid}/people/{guid}/@friendsCollection of all friends of user {guid}; subset of
@all/people/{guid}/{groupid}Collection of all people connected to user {guid} in group
{groupid}/people/{guid}/@all/{pid}Individual person record for a specific person known to
{guid}; shows {guid}'s view of {pid}./people/{guid}/@selfProfile record for user {guid}/people/@me/@selfProfile record for requestor/people/@supportedFieldsReturns all of the fields that the container supports on
people objects as an array in json and a repeated list in atom./people/{guid}/@deletedThis is an OPTIONAL api that will return all of the people
connected to the user {guid} that have been deleted. This should usually
be combined with a updatedSince param.Friends MAY be added by POSTing to the appropriate collection (e.g.,
/people/{guid}/@friends). Containers MAY require a dual opt-in process
before the friend record appears in the collection, and in this case SHOULD
return a 202 Accepted response, indicating that the request is 'in flight'
and may or may not be ultimately successful.If the guid is set to -1, the value for the anonymous user MUST be
returned. The value for the name and nickname fields can either be blank or
set to an appropriate value such as 'Guest', 'Anonymous', etc.All AppData for the person or collection of people returned by a given
query may be fetched by specifying the field "appdata" in the fields query
parameter. If only a subset of AppData fields are desired, they may be
fetched by specifying "appdata.<fieldname>" for each field that needs
to be fetched.Examples:
URI FragmentDescription/people/@me/@self?fields=appdataAll appdata for the requestor./people/@me/@self?fields=appdata.key1,appdata.key2Appdata stored under the keys "key1" and "key2" for the
requestor.XRDS Type: http://ns.opensocial.org/2008/opensocial/groupsURI structure: {guid}guid : Container-globally-unique user identifier; identifies owner of
the people data; can be @me to indicate auth[nz] requestor should be
used.Groups URI examples:
URI FragmentDescription/groups/{guid}Collection of groups associated with user {guid}XRDS Type: http://ns.opensocial.org/2008/opensocial/activitiesURI structure: {guid}/{selector}/{appId}guid : Container-globally-unique user identifier; owner or recipient of
the activity data, or @me to indicate the requestor should be usedselector : One of
A user-defined local group name to select activities from people in the
group (a collection)@self to select the activities for user guid (a collection)@all to select all the universal set of contacts (a collection)@friends to select the activities from friends only (a collection)appId : The app id to select activities for, or @app to indicate the
currently requesting application.Activity URI examples:
URI FragmentDescription/activities/{guid}/@selfCollection of activities generated by given user/activities/{guid}/@self/{appid}Collection of activities generated by an app for a given user/activities/{guid}/@friendsCollection of activities for friends of the given user {guid}/activities/{guid}/@friends/{appid}Collection of activities generated by an app for friends of the given
user {guid}/activities/{guid}/{groupid}Collection of activities for people in group {groupid} belonging to
given user {uid}/activities/{guid}/{groupid}/{appid}Collection of activities generated by an app for people in group
{groupid} belonging to given user {uid}/activities/{guid}/@self/{appid}/{activityid}Individual activity resource; usually discovered from collection/activities/@supportedFieldsReturns all of the fields that the container supports on activity
objects as an array in json and a repeated list in atom.XRDS Type: http://ns.opensocial.org/2008/opensocial/appDataURI structure: {selector}/{appId}selector : One of
A user-defined local group name to select appData from people in the
group (a collection)@self to select the appData for user guid only (a collection)@all to select all the universal set of contacts (a collection)@friends to select the appData from friends of guid only (a
collection)appId : The app id to select activities for, or @app to indicate the
currently requesting application.AppData URI examples:
URI FragmentDescription/appData/{guid}/@self/{appid}All app data for user {guid}, app {appid}/appData/{guid}/@friends/{appid}All app data for friends of user {guid} and app {appid}; read-only
(only GET and HEAD supported)/appData/{guid}/@self/{appid}?fields=highscoreJust the highscore field for user {guid}, app {appid}XRDS Type: http://ns.opensocial.org/2008/opensocial/albumsURI structure: {guid}/{groupId}/{optionalAlbumId}guid: ID of the user or @me to indicate the requestor should be usedgroupId:
@self: albums for the userId (support for this parameter is
optional)@friends: friends of the userId@all: Albums for all of the people in that user's group.@groupId: Albums for all of the people in a specific group.optionalAlbumId: Id of the album. When specified, returns media items
from the album.Album URI examples:
URI FragmentDescriptionGET /albums/@me/@selfReturns a list of albums.POST /albums/@me/@selfCreates a new album.GET /albums/@me/@self/albumIdReturns only the specified album.PUT /albums/@me/@self/albumIdUpdates the specified album.DELETE /albums/@me/@self/albumIdDeletes the specified album.XRDS Type: http://ns.opensocial.org/2008/opensocial/mediaItemsURI structure:
{guid}/{groupId}/{optionalAlbumId}/{optionalMediaItemId}guid: ID of the user or @me to indicate the requestor should be
used.groupId:
@self: Media Items for the userId (support for this parameter is
optional)@friends: friends of the userId@all: Media Items for all of the people in that user's group.@groupId: Media Items for all of the people in a specific group.optionalAlbumId: Id of the album. When specified, returns media items
from the album.optionalMediaItemId: Id of a media item within an album. optionalAlbumId
is required to get to a specific media item.MediaItem URI examples:
URI FragmentDescriptionGET /mediaitems/@me/@self/albumIdReturns the media items in the album.POST /mediaitems/@me/@self/albumIdCreates a new media item.GET /mediaitems/@me/@self/albumId/mediaItemIdReturns the media item.PUT /mediaitems/@me/@self/albumId/mediaItemIdUpdates the media item.DELETE /mediaitems/@me/@self/albumId/mediaItemIdDeletes the media item.XRDS Type: http://ns.opensocial.org/2008/opensocial/cache/invalidateURI structure: n/a-- URI only accepts POST data.An application can execute an invalidation request as a POST to the REST
endpoint described in the containers XRDS or as a JSON-RPC call. Response
codes have the following meanings:
200 - Success, all invalidations processed successfully.403 - Forbidden because authentication failed.409 - The request was partially processed, the set of invalidation keys
that were not honored MUST be included in the response body in the format
the request was made.Containers MAY reject invalidation requests for policy reasons.
Containers MAY continue to serve content that has already been invalidated
until the container is able to successfully fetch a replacement from it
original source.Examples
Invalidate the gadget spec and message bundle of an application
using REST
POST /api/rest/cache/invalidate
HOST opensocial.example.org
Content-Type application/json
{
invalidationKeys : [ "http://www.myapp.com/gadgetspec.xml", "http://www.myapp.com/messagebundle.xml"]
}
These additional query parameters may be used with any URI above. The
parameters startIndex and count are interpreted according to
.
Querystring ParameterDescriptioncount={count}Requests page size for paged collection. If no parameter is specified
the container can choose how many items in the collection should be
returned. However, the container SHOULD support a large default count
value so that all items can be returned by default.filterBy={fieldname}For a collection, return entries filtered by the given field.filterOp={operation}The operation to use when filtering a collection, defaults to
"contains". Valid values are contains, equals, startsWith, and
present.filterValue={value}The value to use when filtering a collection. For example,
filterBy=name&filterOp=startsWith&filterValue=John will return all
items whose name field starts with John. Johnny and John Doe would both be
included.)format={format}Format desired; one of (atom, json, xml); default is json if not
providedfields={-join|,|field}List of fields to include in representation or in the members of a
collection. If no fields are provided it is up to the container to decide
which fields to return. However, the set MUST include the minimum set of
fields. For people this is id, name, and thumbnailUrl. For activities this
is id and title. @all is accepted to indicate returning all available
fields.networkDistance={networkDistance}Modifies group-relative requests (@friends, etc.) to include the
transitive closure of all friends up to {networkDistance} links away. MAY
NOT be honored by the container.sortBy={fieldname}For a collection, return entries sorted by the given field.sortOrder={order}Can either be "ascending" or "descending", defaults to ascending. Used
to sort objects in a collection.startIndex={startIndex}Index into a paged collection.updatedSince={xsdDateTime}When specified the container should only return items whose updated
date is equal to or more recent then the specified value.Behavior of query parameters to determine if two people are
friends (important part is the query string):
/people/@me/@self?filterBy=@friends&filterOp=contains&filterValue=<someUserId>
This will return nothing if the other ID is not a friend, the
current user if the two are friends. filterValue may take a specific person
identifier of @owner or @viewer.
To determine the mutual friends between two people (important
part is the query string):
/people/@me/@friends?filterBy=@friends&filterOp=contains&filterValue=<someUserId>
This will return the set of mutual friends between the current
user and someUserId. filterValue may take a specific person identifier of
@owner or @viewer.Note: The container is not required to support all values for filtering,
sorting and getting the last set of updated items from a collection. If the
container does not respect the filer, sort or updatedSince param the
response should contain "filtered : false", "sorted : false", or
"updatedSince : false".Containers SHOULD carefully consider security. Containers MUST support
but SHOULD use appropriate policies to
determine allowed operations on a per-Consumer and per-user basis. Per
, Containers SHOULD document how a Consumer
can direct a user to a Container web page to obtain an oauth_token for
future use. Note that this is a vector for phishing if the user is required
to enter their credentials.Containers SHOULD support SSL connections for sensitive data as OAuth on
its own does not provide encryption or message body integrity checking.
Containers should base their security decisions on the type of client in
use; a generally available desktop client, for example, cannot effectively
protect a Consumer Secret that is installed with each client. The security
of communications with a partner service, on the other hand, is dependent on
the effectiveness of that service's security procedures. Containers may wish
to rate limit requests from unknown clients, or require registration, in
order to mitigate risk.Containers SHOULD scope oauth_tokens as narrowly as possible (e.g., allow
reading but not writing if a client only performs reads).This feature allows a container and client to cooperate in order to
prevent multiple containers from overwriting each other's data. It uses the
standard HTTP/AtomPub optimistic concurrency mechanism based on ETags (see
section 9.5 of
for details; the same mechanism applies regardless
of the data format used for the body of the PUT).Concurrency control is available on a resource-by-resource basis. When
an updateable resource supports concurrency control, the container SHOULD
supply an ETag encoding the resource's current state when supplying a
representation to clients. If a resource does not support optimistic
concurrency, it MUST respond to an update request containing an If-Match:
header with a 403 Not Implemented error.A server which chooses not to support optimistic concurrency SHOULD omit
ETags on its responses for updateable resources. A client SHOULD assume
that optimistic concurrency is not available if no ETag is present.When a client is given an ETag, it MAY supply that ETag in an If-Match:
header on subsequent updates. The semantics are that the client can supply
the new representation and the previous ETag; the server inspects the
current state of the resource and applies the update if the client supplied
ETag matches (meaning no intervening updates have happened), otherwise
responds with a 409 Conflict error and the new ETag. Clients may then take
appropriate actions to resolve the conflict, or fail the operation,
depending on their needs. Clients are also free to use PUT to simply
overwrite a resource with a new state at any time, ignoring possible
overwriting problems.If partial updates are supported (see below), a server MUST accept an
ETag given for either a base resource or a projection of that resource upon
a subsequent PUT for that resource. That is, it is legal to supply an ETag
you received when GETting the full representation of a resource even if you
are only PUTting back a single field. If you intend to simply overwrite
that single field, then you skip sending any ETag.Partial updates avoid the need to send full representations of data on
updates, especially for People and App Data. The primary use case is when a
client has retrieved a full representation and subsequently wishes to send
a small update to a server. In the most general case, the client may have a
series of small updates (e.g., changing tags on a large number of contacts)
scattered across many resources. To accomplish these partial updates we
will take advantage of the "fields" parameter.When the "fields" parameter is specified on a url, only those fields
will be looked at when updating an object. If a field is in the parameter
list but not part of the post, that would be considered a removal of that
field. If the field is in the post but not in the parameter list a 400 bad
request error will be returned. If a field is in both places then it will
be updated normally.A social network service may optionally expose a mechanism for retrieving
and sending short messages between users. The functionality and policies are
parallel to those of the JS API's requestSendMessage.XRDS Type: http://ns.opensocial.org/2008/opensocial/messagesURI structure: {guid}/{msgcolluid}/{msgid}guid: as defined for people above. Generally a unique user id, however
could also refer to a community, or @me to refer to the current
authentication context.msgcolluid : Container-globally-unique message collection identifier can
be:
A container specific identifier of a collection of messages@inbox to indicate the collection of all messages sent to the user@outbox to indicate the collection of all messages sent by the user and
used as a special endpoint for posting outbound messages.msgid: Container unique message id.If a container supports messaging, it advertises a "messages"
Service in its discovery document:
<Service>
<Type>http://ns.opensocial.org/messages/0.8</Type>
<URI>http://api.example.org/messages/</URI>
</Service>
Basic REST operations are available for Message Collections:
URI FragmentDescriptionGET /messages/{guid}Returns list of message collections for user specified in guid.POST /messages/{guid}Posting data here results in a new message collection.PUT /messages/{guid}/{msgcollid}Updates the data for a message collection, for example, renaming.All standard collection handling parameters work here, including sortBy,
filterBy etc.When you have a message collection you can then perform operations on
messages.URI FragmentDescriptionGET /messages/{guid}/{msgcollid}Gets a list of messages in a specific collection. Specify the message
collection ID (msgcollid) or @inbox/@outbox for all messages. You can also
use the filterBy, and sortBy parameters to return a smaller, sorted subset
of messages.POST /messages/{guid}/@outboxCreates a message and place it in a queue, a client POSTs a message to
an 'outbox' collection.The outbox is owned by the source user. Placing a message in
the outbox requests that the message be delivered to one or more recipients
as specified in the message. Containers are free to filter or alter the
message according to their own policies (such as security or rate limiting
policies).Access to individual messages is also available. You can retrieve an
individual message by sending a GET request with a valid msgid value and a
valid message collection. A PUT request can alter fields of an individual
message (i.e. marking the message as 'read'). A DELETE request will remove
the specified message from the given collection. A DELETE from the @all
collection should remove the message from all collections in the system.
Here are some example requests:
GET /messages/{guid}/@all/{msgid}PUT /messages/{guid}/@all/{msgid}DELETE /messages/{guid}/{msgcollid}/{msgid}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 {msgid} is server generated and is globally unique. The client
should use a standard AtomPub POST to /messages/{guid}/@outbox. The
response is 201 Created on success.If not supported, the response code should be 403 Not Implemented.Typically a container would choose to only allow a POST to an outbox
where the {guid} equals the requester id, but this is a container security
policy decision.Containers may choose to allow messaging only between friends or user
other heuristics to prevent spam.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.Each field is defined as either a Singular Field, in which case there can
be at most one instance of that field per contact, or as a Plural Field,
which case any number of instances of that field may be present per contact.
Unless otherwise specified, all fields are optional and of type
xs:string.Each person returned MUST include the id and displayName fields with
non-empty values, but all other fields are optional, and it is recognized
that not all Service Providers will be able to provide data for all the
supported fields. The field list is below is broad so that, for Service
Providers that do support any of these fields, there is a standard field
name availableField NameDescriptionanniversaryThe wedding anniversary of this person. The value MUST be a valid
xs:date (e.g. 1975-02-14). The year value MAY be set to 0000 when the
year is not available.birthdayThe birthday of this person. The value MUST be a valid xs:date (e.g.
1975-02-14). The year value MAY be set to0000 when the age of the Person
is private or the year is not available.connectedBoolean 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.displayNameThe name of this Person, suitable for display to end-users. Each
Person returned MUST include a non-emptydisplayName 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.genderThe 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.idUnique identifier for the Person. Each Person returned MUST include a
non-empty id value. This identifier MUST be unique across this user's
entire set of people, but MAY not be unique across multiple users' data.
It MUST be a stable ID that does not change when the same contact is
returned in subsequent requests. For instance, an e-mail address is not a
good id, because the same person may use a different e-mail address in
the future. Usually, in internal database ID will be the right choice
here, e.g. "12345".nameThe broken-out components and fully formatted version of the person's
real name, as described in
(name Element).nicknameThe 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.noteNotes about this person, with an unspecified meaning or usage
(normally notes by the user about this person). This field MAY contain
newlines.preferredUsernameThe 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.publishedThe 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
(e.g. 2008-01-23T04:56:22Z).updatedThe most recent date the details of this Person were updated (i.e. the
modified date of this entry). The value MUST be a valid
(e.g. 2008-01-23T04:56:22Z). 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 xs:dateTime. This enables Consumers to repeatedly
access a user's data and only request newly added or updated contacts
since the last access time.utcOffsetThe offset from UTC of this Person's current time zone, as of the time
this response was returned. The value MUST conform to the offset portion
of
, e.g. -08:00. 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.The following additional Singular Fields are defined, based on
their specification in the OpenSocial javascript apis: aboutMe,
bodyType,currentLocation, drinker, ethnicity, fashion, happiestWhen,
humor, livingArrangement, lookingFor, profileSong,profileVideo,
relationshipStatus, religion, romance, scaredOf, sexualOrientation,
smoker, and status.Unless specified otherwise, all Plural Fields have the same three
standard sub-fields:
Field NameDescriptionvalueThe primary value of this field, e.g. the actual e-mail address, phone
number, or URL. When specifying a sortByfield in the Query Parameters for
a Plural Field, the default meaning is to sort based on this value
sub-field. Each non-empty Plural Field value MUST contain at least the
value sub-field, but all other sub-fields are optional.typeThe type of field for this instance, usually used to label the
preferred function of the given contact information. Unless otherwise
specified, this string value specifies Canonical Values of work, home,
and other.primaryA Boolean value indicating whether this instance of the Plural Field
is the primary or preferred value of for this field, e.g. the preferred
mailing address or primary e-mail address. Service Providers MUST NOT
mark more than one instance of the same Plural Field as primary="true",
and MAY choose not to mark any fields as primary, if this information is
not available. For efficiency, Service Providers SHOULD NOT mark all
non-primary fields with primary="false", but should instead omit this
sub-field for all non-primary instances.When returning Plural Fields, Service Providers SHOULD canonicalize the
value returned, if appropriate (e.g. for e-mail addresses and URLs).
Providers MAY return the same value more than once with different types
(e.g. the same e-mail address may used for work and home), but SHOULD NOT
return the same (type, value) combination more than once per Plural Field,
as this complicates processing by the Consumer.
Field NameDescriptionemailsE-mail address for this Person. The value SHOULD be canonicalized by
the Service Provider, e.g.joseph@plaxo.com instead of
joseph@PLAXO.COM.urlsURL 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.phoneNumbersPhone 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.imsInstant 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.photosURL 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.tagsA 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.relationshipsA bi-directionally asserted relationship type that was established
between the user and this person by the Service Provider. The value
SHOULD conform to one of the XFN relationship values (e.g. kin, friend,
contact, etc.) if appropriate, but MAY be an alternative value if needed.
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.addressesA physical mailing address for this Person, as described in
(address Element).organizationsA current or past organizational affiliation of this Person, as
described in
(organization Element).accountsAn online account held by this Person, as described in
(account Element).appdataA collection of AppData keys and values, as described in
(an isolated AppData
example).The following additional Plural Fields are defined, based on
their specification in OpenSocial: activities, books, cars, children,food,
heroes, interests, jobInterests, languages, languagesSpoken, movies,
music, pets, politicalViews, quotes, sports,turnOffs, turnOns, and
tvShows.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 NameDescriptionformattedThe 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.familyNamehe family name of this Person, or "Last Name" in most Western
languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr,
Esq.).givenNameThe given name of this Person, or "First Name" in most Western
languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr,
Esq.).middleNameThe middle name(s) of this Person (e.g. Robert given the full name Mr.
Joseph Robert Smarr, Esq.).honorificPrefixThe honorific prefix(es) of this Person, or "Title" in most Western
languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr,
Esq.).honorificSuffixThe honorifix suffix(es) of this Person, or "Suffix" in most Western
languages (e.g. Esq. given the full name Mr. Joseph Robert Smarr,
Esq.).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 NameDescriptionformattedThe 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.streetAddressThe 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.localityThe city or locality component.regionThe state or region component.postalCodeThe zipcode or postal code component.countryThe country name component.latitudeExpresses the latitude of the location on a map.longitudeExpresses the longitude of the location on a map.typeThe address type or label. Examples include 'work', 'home'.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 NameDescriptionnameThe 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.departmentThe department within this organization.titleThe job title or organizational role within this organization.typeThe type of organization, with Canonical Values job and school.startDateThe date this Person joined this organization. This value SHOULD be a
valid
if possible, but MAY be an unformatted
string, since it is recognized that this field is often presented as
free-text.endDateThe date this Person left this organization or the role specified by
title within this organization. This value SHOULD be a valid
if possible, but MAY be an unformatted
string, since it is recognized that this field is often presented as
free-text.locationThe physical location of this organization. This may be a complete
address
, or an abbreviated location like "San
Francisco".descriptionA textual description of the role this Person played in this
organization. This field MAY contain newlines.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 NameDescriptiondomainThe 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.usernameAn alphanumeric user name, usually chosen by the user, e.g.
"jsmarr".useridA user ID number, usually chosen automatically, and usually numeric
but sometimes alphanumeric, e.g. "12345" or "1Z425A".The following fields are defined, based on their specification in the
OpenSocial JavaScript apis: appId, body, bodyId, externalId, id,
mediaItems, postedTime, priority, streamFaviconUrl, streamSourceUrl,
streamTitle, streamUrl, templateParams, title, url, userId.The following fields are defined, based on their specification in the
OpenSocial JavaScript apis: type, title, body, titleId, bodyId, id,
recipients, senderId, timeSent, inReplyTo, replies, status, appUrl,
collectionIds, updated, urls.
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:tns="http://ns.opensocial.org/2008/opensocial"
elementFormDefault="qualified"
targetNamespace="http://ns.opensocial.org/2008/opensocial"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="EscapeTypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="HTML_ESCAPE" />
<xs:enumeration value="NONE" />
</xs:restriction>
</xs:simpleType>
<!-- this is a proposal for the OpenSocial 0.9 XSD. -->
<xs:element name="person" type="tns:Person" />
<xs:element name="group" type="tns:Group" />
<xs:element name="activity" type="tns:Activity" />
<xs:element name="appData" type="tns:Appdata" />
<xs:element name="response" type="tns:Response" />
<xs:element name="list.container" type="xs:anyType" />
<xs:complexType name="Response">
<xs:choice minOccurs="0" maxOccurs="unbounded" >
<xs:element minOccurs="0" name="itemsPerPage" type="xs:int" />
<xs:element minOccurs="0" name="startIndex" type="xs:long" />
<xs:element minOccurs="0" name="totalResults" type="xs:long" />
<xs:element minOccurs="0" name="isFiltered" type="xs:boolean" />
<xs:element minOccurs="0" name="isSorted" type="xs:boolean" />
<xs:element minOccurs="0" name="isUpdatedSince" type="xs:boolean" />
<xs:element minOccurs="0" name="group" type="tns:Group" />
<xs:element minOccurs="0" name="activity" type="tns:Activity" />
<xs:element minOccurs="0" name="person" type="tns:Person" />
<xs:element minOccurs="0" name="album" type="tns:Album" />
<xs:element minOccurs="0" name="mediaItem" type="tns:MediaItem" />
<xs:element minOccurs="0" name="message" type="tns:Message" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="entry" type="tns:Entry" />
<!-- this is to allow responses to create to validate -->
<xs:element minOccurs="0" name="map" type="xs:anyType" />
</xs:choice>
</xs:complexType>
<xs:complexType name="Entry" >
<xs:choice>
<xs:element minOccurs="0" name="activity" type="tns:Activity" />
<xs:element minOccurs="0" name="person" type="tns:Person" />
<xs:element minOccurs="0" name="group" type="tns:Group" />
<xs:element minOccurs="0" name="appData" type="tns:Appdata" />
<xs:element minOccurs="0" name="album" type="tns:Album" />
<xs:element minOccurs="0" name="mediaItem" type="tns:MediaItem" />
</xs:choice>
</xs:complexType>
<xs:complexType name="Activity">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element minOccurs="0" name="appId" type="xs:string" />
<xs:element minOccurs="0" name="body" type="xs:string" />
<xs:element minOccurs="0" name="bodyId" type="xs:string" />
<xs:element minOccurs="0" name="externalId" type="xs:string" />
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="mediaItems" type="tns:MediaItem" />
<xs:element minOccurs="0" name="postedTime" type="xs:long" />
<xs:element minOccurs="0" name="priority" type="xs:double" />
<xs:element minOccurs="0" name="streamFaviconUrl" type="xs:string" />
<xs:element minOccurs="0" name="streamSourceUrl" type="xs:string" />
<xs:element minOccurs="0" name="streamTitle" type="xs:string" />
<xs:element minOccurs="0" name="streamUrl" type="xs:string" />
<xs:element minOccurs="0" name="templateParams" type="tns:ActivityTemplateParams" />
<xs:element minOccurs="0" name="title" type="xs:string" />
<xs:element minOccurs="0" name="titleId" type="xs:string" />
<xs:element minOccurs="0" name="url" type="xs:string" />
<xs:element minOccurs="0" name="userId" type="xs:string" />
</xs:choice>
</xs:complexType>
<xs:complexType name="ActivityTemplateParams">
<xs:all>
<xs:element minOccurs="0" name="PersonKey" type="xs:string" />
<xs:element minOccurs="0" name="PersonKey.DisplayName" type="xs:string" />
<xs:element minOccurs="0" name="PersonKey.Id" type="xs:string" />
<xs:element minOccurs="0" name="PersonKey.ProfileUrl" type="xs:string" />
<xs:element minOccurs="0" name="person" type="tns:Person" />
</xs:all>
</xs:complexType>
<xs:complexType name="Person">
<xs:choice minOccurs="1" maxOccurs="unbounded">
<xs:element minOccurs="0" name="aboutMe" type="xs:string" />
<xs:element minOccurs="0" name="accounts" type="tns:Account"/>
<xs:element minOccurs="0" maxOccurs="unbounded" name="activities" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="addresses" type="tns:Address" />
<xs:element minOccurs="0" name="age" type="xs:string"/>
<xs:element minOccurs="0" name="anniversary" type="xs:dateTime" />
<xs:element minOccurs="0" name="appData" type="tns:Appdata" />
<xs:element minOccurs="0" name="birthday" type="xs:dateTime" />
<xs:element minOccurs="0" name="bodyType" type="tns:BodyType" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="books" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="cars" type="xs:string" />
<xs:element minOccurs="0" name="children" type="xs:string" />
<xs:element minOccurs="0" name="connected" type="tns:Presence" />
<xs:element minOccurs="0" name="currentLocation" type="tns:Address" />
<xs:element minOccurs="0" name="displayName" type="xs:string" />
<xs:element minOccurs="0" name="drinker" type="tns:Drinker" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="emails" type="tns:PluralPersonField" />
<xs:element minOccurs="0" name="ethnicity" type="xs:string" />
<xs:element minOccurs="0" name="fashion" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="food" type="xs:string" />
<xs:element minOccurs="0" name="gender" type="xs:string" />
<xs:element minOccurs="0" name="happiestWhen" type="xs:string" />
<xs:element minOccurs="0" name="hasApp" type="xs:boolean" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="heroes" type="xs:string" />
<xs:element minOccurs="0" name="humor" type="xs:string" />
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="ims" type="tns:PluralPersonField"/>
<xs:element minOccurs="0" maxOccurs="unbounded" name="interests" type="xs:string" />
<xs:element minOccurs="0" name="jobInterests" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="languagesSpoken" type="xs:string" />
<xs:element minOccurs="0" name="livingArrangement" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="lookingFor" type="tns:LookingFor" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="movies" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="music" type="xs:string" />
<xs:element minOccurs="0" name="name" type="tns:Name" />
<xs:element minOccurs="0" name="networkPresence" type="tns:NetworkPresence" />
<xs:element minOccurs="0" name="nickname" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="organizations" type="tns:Organization" />
<xs:element minOccurs="0" name="pets" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="phoneNumbers" type="tns:PluralPersonField" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="photos" type="tns:PluralPersonField" />
<xs:element minOccurs="0" name="politicalViews" type="xs:string" />
<xs:element minOccurs="0" name="preferredUsername" type="xs:string" />
<xs:element minOccurs="0" name="profileSong" type="tns:Url" />
<xs:element minOccurs="0" name="profileUrl" type="xs:string" />
<xs:element minOccurs="0" name="profileVideo" type="tns:Url" />
<xs:element minOccurs="0" name="published" type="xs:dateTime"/>
<xs:element minOccurs="0" maxOccurs="unbounded" name="quotes" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="relationships" type="xs:string" />
<xs:element minOccurs="0" name="relationshipStatus" type="xs:string" />
<xs:element minOccurs="0" name="religion" type="xs:string" />
<xs:element minOccurs="0" name="romance" type="xs:string" />
<xs:element minOccurs="0" name="scaredOf" type="xs:string" />
<xs:element minOccurs="0" name="sexualOrientation" type="xs:string" />
<xs:element minOccurs="0" name="smoker" type="tns:Smoker" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="sports" type="xs:string" />
<xs:element minOccurs="0" name="status" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="tags" type="xs:string" />
<xs:element minOccurs="0" name="thumbnailUrl" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="turnOffs" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="turnOns" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="tvShows" type="xs:string" />
<xs:element minOccurs="0" name="updated" type="xs:dateTime"/>
<xs:element minOccurs="0" maxOccurs="unbounded" name="urls" type="tns:Url" />
<xs:element minOccurs="0" name="utcOffset" type="xs:int" />
</xs:choice>
</xs:complexType>
<xs:complexType name="Group">
<xs:all>
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" name="title" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="AppdataEntry" mixed="true">
<xs:all>
<xs:element minOccurs="1" name="key" type="xs:string" />
<xs:element minOccurs="1" name="value" type="xs:anyType" />
</xs:all>
</xs:complexType>
<xs:complexType name="Appdata">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="entry" type="tns:AppdataEntry" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="BodyType">
<xs:all>
<xs:element minOccurs="0" name="build" type="xs:string" />
<xs:element minOccurs="0" name="eyeColor" type="xs:string" />
<xs:element minOccurs="0" name="hairColor" type="xs:string" />
<xs:element minOccurs="0" name="height" type="xs:double" />
<xs:element minOccurs="0" name="weight" type="xs:double" />
</xs:all>
</xs:complexType>
<xs:complexType name="Address">
<xs:all>
<xs:element minOccurs="0" name="country" type="xs:string" />
<xs:element minOccurs="0" name="extendedAddress" type="xs:string" />
<xs:element minOccurs="0" name="latitude" type="xs:double" />
<xs:element minOccurs="0" name="locality" type="xs:string" />
<xs:element minOccurs="0" name="longitude" type="xs:double" />
<xs:element minOccurs="0" name="poBox" type="xs:string" />
<xs:element minOccurs="0" name="postalCode" type="xs:string" />
<xs:element minOccurs="0" name="primary" type="xs:boolean"/>
<xs:element minOccurs="0" name="region" type="xs:string" />
<xs:element minOccurs="0" name="streetAddress" type="xs:string" />
<xs:element minOccurs="0" name="type" type="xs:string" />
<xs:element minOccurs="0" name="formatted" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="Account">
<xs:all>
<xs:element minOccurs="0" name="domain" type="xs:string" />
<xs:element minOccurs="0" name="primary" type="xs:boolean"/>
<xs:element minOccurs="0" name="userid" type="xs:string" />
<xs:element minOccurs="0" name="username" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="Organization">
<xs:all>
<xs:element minOccurs="0" name="address" type="tns:Address" />
<xs:element minOccurs="0" name="department" type="xs:string" />
<xs:element minOccurs="0" name="description" type="xs:string" />
<xs:element minOccurs="0" name="endDate" type="xs:dateTime" />
<xs:element minOccurs="0" name="name" type="xs:string" />
<xs:element minOccurs="0" name="startDate" type="xs:dateTime" />
<xs:element minOccurs="0" name="type" type="xs:string" />
<xs:element minOccurs="0" name="title" type="xs:string" />
<xs:element minOccurs="0" name="field" type="xs:string" />
<xs:element minOccurs="0" name="subField" type="xs:string" />
<xs:element minOccurs="0" name="webpage" type="xs:string" />
<xs:element minOccurs="0" name="salary" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="Name">
<xs:all>
<xs:element minOccurs="0" name="additionalName" type="xs:string" />
<xs:element minOccurs="0" name="familyName" type="xs:string" />
<xs:element minOccurs="0" name="givenName" type="xs:string" />
<xs:element minOccurs="0" name="honorificPrefix" type="xs:string" />
<xs:element minOccurs="0" name="honorificSuffix" type="xs:string" />
<xs:element minOccurs="0" name="formatted" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="Url">
<xs:all>
<xs:element minOccurs="0" name="value" type="xs:string" />
<xs:element minOccurs="0" name="linkText" type="xs:string" />
<xs:element minOccurs="0" name="type" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="Album">
<xs:all>
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" name="thumbnailUrl" type="xs:string" />
<xs:element minOccurs="0" name="title" type="xs:string" />
<xs:element minOccurs="0" name="description" type="xs:string" />
<xs:element minOccurs="0" name="location" type="tns:Address" />
<xs:element minOccurs="0" name="ownerId" type="xs:string" />
<xs:element minOccurs="0" name="mediaType" type="tns:MediaItemType" />
<xs:element minOccurs="0" name="mediaMimeType" type="xs:string" />
<xs:element minOccurs="0" name="mediaItemCount" type="xs:integer" />
</xs:all>
</xs:complexType>
<xs:complexType name="MediaItem">
<xs:all>
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" name="title" type="xs:string" />
<xs:element minOccurs="0" name="created" type="xs:dateTime" />
<xs:element minOccurs="0" name="thumbnailUrl" type="xs:string" />
<xs:element minOccurs="0" name="description" type="xs:string" />
<xs:element minOccurs="0" name="duration" type="xs:integer" />
<xs:element minOccurs="0" name="location" type="tns:Address" />
<xs:element minOccurs="0" name="language" type="xs:string" />
<xs:element minOccurs="0" name="albumId" type="xs:string" />
<xs:element minOccurs="0" name="fileSize" type="xs:long" />
<xs:element minOccurs="0" name="startTime" type="xs:dateTime" />
<xs:element minOccurs="0" name="rating" type="xs:integer" />
<xs:element minOccurs="0" name="numVotes" type="xs:integer" />
<xs:element minOccurs="0" name="numComments" type="xs:integer" />
<xs:element minOccurs="0" name="numViews" type="xs:integer" />
<xs:element minOccurs="0" name="tags" type="xs:string" />
<xs:element minOccurs="0" name="taggedPeople" type="xs:string" />
<xs:element minOccurs="0" name="mimeType" type="xs:string" />
<xs:element minOccurs="0" name="type" type="tns:MediaItemType" />
<xs:element minOccurs="0" name="url" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:simpleType name="MediaItemType">
<xs:restriction base="xs:string">
<xs:enumeration value="AUDIO" />
<xs:enumeration value="IMAGE" />
<xs:enumeration value="VIDEO" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Drinker">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:DrinkerType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="DrinkerType">
<xs:restriction base="xs:string">
<xs:enumeration value="HEAVILY" />
<xs:enumeration value="NO" />
<xs:enumeration value="OCCASIONALLY" />
<xs:enumeration value="QUIT" />
<xs:enumeration value="QUITTING" />
<xs:enumeration value="REGULARLY" />
<xs:enumeration value="SOCIALLY" />
<xs:enumeration value="YES" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Presence">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:PresenceType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="PresenceType">
<xs:restriction base="xs:string">
<xs:enumeration value="AWAY" />
<xs:enumeration value="CHAT" />
<xs:enumeration value="DND" />
<xs:enumeration value="OFFLINE" />
<xs:enumeration value="ONLINE" />
<xs:enumeration value="XA" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Smoker">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:SmokerType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="SmokerType">
<xs:restriction base="xs:string">
<xs:enumeration value="HEAVILY" />
<xs:enumeration value="NO" />
<xs:enumeration value="OCCASIONALLY" />
<xs:enumeration value="QUIT" />
<xs:enumeration value="QUITTING" />
<xs:enumeration value="REGULARLY" />
<xs:enumeration value="SOCIALLY" />
<xs:enumeration value="YES" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="CreateActivityPriority">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:CreateActivityPriorityType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="CreateActivityPriorityType">
<xs:restriction base="xs:string">
<xs:enumeration value="HIGH" />
<xs:enumeration value="LOW" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="EscapeType">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:EscapeTypeType" />
</xs:all>
</xs:complexType>
<xs:complexType name="Message">
<xs:choice>
<xs:element minOccurs="0" name="body" type="xs:string" />
<xs:element minOccurs="0" name="bodyId" type="xs:string" />
<xs:element minOccurs="0" name="title" type="xs:string" />
<xs:element minOccurs="0" name="titleId" type="xs:string" />
<xs:element minOccurs="0" name="id" type="xs:string" />
<xs:element minOccurs="0" name="recipients" type="xs:string" />
<xs:element minOccurs="0" name="senderId" type="xs:string" />
<xs:element minOccurs="0" name="timeSent" type="xs:dateTime" />
<xs:element minOccurs="0" name="inReplyTo" type="xs:string" />
<xs:element minOccurs="0" name="replies" type="xs:string" />
<xs:element minOccurs="0" name="status" type="xs:string" />
<xs:element minOccurs="0" name="appUrl" type="tns:Url" />
<xs:element minOccurs="0" name="collectionIds" type="xs:string" />
<xs:element minOccurs="0" name="updated" type="xs:dateTime" />
<xs:element minOccurs="0" maxOccurs="unbounded" name="urls" type="tns:Url" />
</xs:choice>
</xs:complexType>
<xs:complexType name="MessageType">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:MessageTypeType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="MessageTypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="EMAIL" />
<xs:enumeration value="NOTIFICATION" />
<xs:enumeration value="PRIVATE_MESSAGE" />
<xs:enumeration value="PUBLIC_MESSAGE" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Environment">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:EnvironmentType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="EnvironmentType">
<xs:restriction base="xs:string">
<xs:enumeration value="ACTIVITY" />
<xs:enumeration value="ADDRESS" />
<xs:enumeration value="BODY_TYPE" />
<xs:enumeration value="EMAIL" />
<xs:enumeration value="FILTER_TYPE" />
<xs:enumeration value="MEDIAITEM" />
<xs:enumeration value="MESSAGE" />
<xs:enumeration value="MESSAGE_TYPE" />
<xs:enumeration value="NAME" />
<xs:enumeration value="ORGANIZATION" />
<xs:enumeration value="PERSON" />
<xs:enumeration value="PHONE" />
<xs:enumeration value="SORTORDER" />
<xs:enumeration value="URL" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="LookingFor">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:LookingForType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="LookingForType">
<xs:restriction base="xs:string">
<xs:enumeration value="ACTIVITY_PARTNERS" />
<xs:enumeration value="DATING" />
<xs:enumeration value="FRIENDS" />
<xs:enumeration value="NETWORKING" />
<xs:enumeration value="RANDOM" />
<xs:enumeration value="RELATIONSHIP" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="NetworkPresence">
<xs:all>
<xs:element minOccurs="0" name="displayValue" type="xs:string" />
<xs:element minOccurs="0" name="value" type="tns:NetworkPresenceType" />
</xs:all>
</xs:complexType>
<xs:simpleType name="NetworkPresenceType">
<xs:restriction base="xs:string">
<xs:enumeration value="AWAY" />
<xs:enumeration value="CHAT" />
<xs:enumeration value="DND" />
<xs:enumeration value="OFFLINE" />
<xs:enumeration value="ONLINE" />
<xs:enumeration value="XA" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="PluralPersonField">
<xs:all>
<xs:element minOccurs="0" name="value" type="xs:string" />
<xs:element minOccurs="0" name="type" type="xs:string" />
<xs:element minOccurs="0" name="primary" type="xs:boolean"/>
</xs:all>
</xs:complexType>
</xs:schema>
Status CodeDescription400 BAD REQUESTOpenSocial application servers MUST return 400 BAD REQUEST
under any one or more of the following conditions:
Invalid request URIInvalid HTTP HeaderReceiving an unsupported, nonstandard parameterReceiving an invalid HTTP Message Body401 UNAUTHORIZEDOpenSocial container servers MUST return 401 UNAUTHORIZED
when receiving a request for a protected resource and the request is either
Missing OAuth authorization credentials as described in
.OAuth authorization credentials are present, but the user identity is
not authorized to access the protected resource. If the request already
included authorization credentials, the 401 response indicates that the
request has been refused for those credentials. A 401 response MUST
include a WWW-Authenticate header field indicating the request MAY present
an OAuth token for the container server's realm. Example:
WWW-Authenticate: OAuth realm="http://sp.example.com/"403 FORBIDDENThe server understood the request but is refusing to
fulfill it. Authorization will not help. The current authorization context
does not allow the request.404 NOT FOUNDThe server has not found a resource (such as a feed or
entry) that matches the request URI.405 METHOD NOT ALLOWEDThe method specified in the Request-Line is not allowed for
the resource identified by the Request-URI. The response MUST include an
Allow header containing a list of valid methods for the requested
resource.409 CONFLICTThe request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where it is
expected that the user might be able to resolve the conflict and resubmit
the request. The response body SHOULD include enough information for the
user to recognize the source of the conflict. Ideally, the response entity
would include enough information for the user or user agent to fix the
problem; however, that might not be possible and is not required. Conflicts
are most likely to occur in response to a PUT request. For example, this
code can be used for a limit exceeded error as well as conflicting updates.
See the error message for more information.500 INTERNAL SERVER ERRORInternal error. This is the default code that is used for
all unrecognized errors.501 NOT IMPLEMENTEDThe request was valid but has not been implemented by the
provider. A container SHOULD return 501 NOT IMPLEMENTED when receiving a
request for an OPTIONAL/MAY feature that the container does not
implement.This version of the OpenSocial RESTful protocol specification is
currently wire-compatible with the Portable Contacts version 1.0 overlapping
portion of OpenSocial. Specifically, any compliant OpenSocial 0.9 People
Provider is also a compliante Portable Contacts 1.0 Provider, because they
are specified to use the same Authorization methods (OAuth), Additional Path
Information, Query Parameters, and Contact Schema. The OpenSocial and
Portable Contacts communities chose to wire-align our respective specs in
order to maximize widespread adoption of a single API for accessing people
data. It is our intention to maintain this compatibility going forward, so
long as it is feasible, and so long as the changes required are compatible
with the Goals and Approach of this spec. Although Portable Contacts is an
independent spec, with a more limited scope than OpenSocial, any proposed
changes to either this OpenSocial RESTful Protocol spec or the Portable
Contacts spec should be considered in the context of both communities, and
we should strive not to break compatibility unless it is truly necessary,
e.g. if the goals of the two communities diverge significantly in the
future.Key words for use in RFCs to Indicate Requirement LevelsHarvard UniversityReserved Top Level DNS NamesIBMReserved Top Level DNS NamesClearswift CorporationSun MicrosystemsThe Atom Syndication FormatThe application/json Media Type for JavaScript Object Notation
(JSON)JSON.orgThe Atom Publishing ProtocolGoogleNewBay SoftwareExtensible Markup Language (XML) 1.0 (Fifth Edition)TextualityNetscapeMicrosoftW3CSun Microsystems, Inc.XML Schema Part 2: Datatypes Second EditionKaiser Permanente, for Health Level SevenMicrosoftOpenSearch 1.1, Draft 3OpenSearch.orgSocial Graph Node MapperOAuth Consumer Request 1.0 Draft 1OAuth Core 1.0GoogleTwitterPownceFlickrma.gnoliaGoogleTwittersix apartYeddama.gnoliaJaiku