OpenSocial Social Data Specification (draft)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The group ID must only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-), and must uniquely identify the group in a container. Group-ID = Object-Id / "@self" / "@friends" / "@all"

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

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

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

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

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

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